Adaptive Website Framework (AWF) is a remarkable tool that helps the administrator/developer create and work with enterprise-level news and Web portals. This creation is an open source project from the German company Liquid Bytes and is probably the simplest, most robust open source news/Web portal tool I’ve used to date.

The one downfall of this application, should you not speak German, is that the English documentation is, to put it mildly, severely lacking. Fortunately, I was able to pass back and forth a great deal of e-mail to the creators of the application, who were kind enough to lead me around the tool.

This Daily Feature will walk you through the simple installation and then pick up where the documentation leaves off and show you how to set up your site.

What you need
In order to take advantage of this tool from the Liquid Bytes wunderkinds, you will need:

  • PHP 4.06 or better.
  • A working installation of MySQL.
  • A Web server.

Get and install
One thing I learned the hard way is that you have to download the latest version of the application. Should you choose an earlier version, you will find yourself surrounded by a number of pesky little bugs, a few of which nearly ate me alive! So grab the file of the latest version and save it in /usr/local/src.

Once you’ve saved the file, su to root and run the command tar xvzf awf-latest.tar.gz. Once the file has completed the unpacking, you will notice a new directory called awf. You need to move that directory to the document root of your Web server. To do this, I ran the command:
mv awf /var/www/html

The next step is the final step in the installation. Open up a browser and point it to http://<servername>/awf/admin/setup.php. The setup screen will ask you to enter your e-mail address (which will be the administrator’s address, of course). On that same page, you’ll also be asked if you want to register the application (this is not necessary), if you want to subscribe to the mailing list, and if you want to receive update notifications.

The second page is at the heart of the installation. Here, you will select the type of database you use. (There are only two choices: MySQL and PostgreSQL, with MySQL being the recommended choice.) On this page, you will also enter the Host name of the server (the default is localhost), name the database (the default is awf), enter the Username (this will be the database user name; the default is root), the Password of the user, and the Table prefix (this is optional). Once you click on this page, there are seven things for you to select:

  1. Title of the Web site
  2. The Webmaster’s e-mail address
  3. The path to the server
  4. The default design
  5. If you want to install Phorum (a bulletin board system that is recommended)
  6. If you want to install demo content
  7. If you want to update the database from 1.00 to 1.02

I would advise selecting all three of the clickable radio buttons: Phorum, Demo Content, and Update Database. Why? Phorum is a very nice bulletin board system that can be somewhat complex to install manually (so it’s nice to have it done automatically), and the demo content will make it easier for you to understand how things are laid out within AWF.

Make your selections and click Finish. You are now ready to fire up your default portal.

Installation and interface gotchas
The biggest installation gotcha that I encountered was the installer not being able to connect to the MySQL database. This was easily overcome by opening up a command prompt and manually connecting to the database with the following commands:
mysql –p -u root awf
<here I was required to enter root’s MySQL password>
exit

Once I had run the manual database connection, I was able to get through the AWF installation without a hitch. This situation was unique to my Linux box because I had to repeat the installation of AWF (for reviewing purposes). For some odd reason, the second installation broke the connection to the MySQL database. Fortunately, the above command solved the problem.

It wasn’t until the page creation actually began that I had to call in the cavalry at Liquid Bytes to help me around the language barrier that I mentioned before. But before I get into creating a page in AWF and distilling the AWF terminology into plain-and-simple geek speak for you, I’d like to point out two last configurations that can be done: one that makes the site a bit more unique to the company, and one that allows you to administer the site.

Last touches
The first configuration, and probably the most difficult (if you are artistically challenged), is to replace the default masthead image. Since there is no way to do this through any configuration tool, it must be done by hand. I was able to pull this off by first figuring out what the two images were and then figuring out where they were.

In the default scheme (in AWF terms, it is Default Design), the two images you are looking for are: /awf/img/platine_letf_top_old.jpg and /awf/img/platine_top_old.jpg. The easiest way to change these images is to copy them to a safe directory, open them up in an image editor (like the GIMP), erase the image, create or copy the new image in the blank space, and save it under the same name. Once you do this, your company’s image will appear after you refresh your browser, but it may require a cache refresh as well.

The second configuration requires you to set up a user on the system. To do this, point your browser to http://<yourserver>/awf/admin/users.php. When the new screen opens up, you will enter the new user’s e-mail address and a password (see Figure A below) and click Add.

Figure A
It is also possible to create a user account, but you should set the account as valid at a later time.

Once you click Add, a new box will pop up (see Figure B) that will allow you to add the user to various groups. By default, there are only two groups: Administrators and File Management. To administer the site, you will need to add yourself to Administrators and click the Add/Remove button.

Figure B
You should also set your administrator up as editor by selecting the User Is Editor radio button.

Now your new user is an administrator. Once you log in with this username/password, you will see the administration screens instead of the regular site.

Learn the lingo
As I said earlier, the creators of AWF have created an application that creates dynamic Web sites, but they have done so with a unique vocabulary and a different way of looking at things. This is not to say their way is difficult or wrong—you just have to get used to it.

The administrator interface is a mixture of clickable links, drop-down boxes, radio buttons, clickable buttons, and text areas. As an administrator, you control a number of items that I am going to designate as Navigation, Polls, News, Latest News, Login, Language, Main, Community, Downloads, and Options. There are a few more items that you may explore as you set up your site, but these are the ones that are most suitable for an enterprise environment.

There are 20 standard ”objects,” a term I am using here to refer to the different areas you will need to complete in order to create a page. The most commonly used objects are:

  • Text Document: This is the Web page itself. You can think of a Text Document as a blank Web page that you will fill with information.
  • Text Paragraph: This is what constitutes the actual content of the page. You can look at a Text Paragraph in two ways: either individual Text Paragraphs that make an entire page, or multiple Text Paragraphs that combine to make an entire page.
  • File Browser: This is very useful to an enterprise environment. This object will be used to create downloadable files for employees (or users).
  • Forum: This object allows you to create bulletin boards for use within the site.
  • News Item: This object allows you to insert new news blurbs onto your site.
  • News Overview: Unlike News Item, this object allows you to create categories for various news items.

There are also a number of other objects that can be placed onto the page via the admin tool.

Before I continue, I need to explain the parent/child relationship of AWF. In this application, you have to think of everything in terms of being either a parent or a child. Like the process relationship in Linux/UNIX-land, you will have a parent object that will have children that are within the parent document. For example, you set up your main page (this will be index.php) as a Text Document. This Text Document will have an ID number that will be used as the Parent ID of the child object when creating the Text Paragraphs that make up the body (or summaries) of the page.

Creating a page
With all that in mind, it’s time to set up your front page. First, you will have to log in as administrator. Then, from the Create New Document section (see Figure C below), select Text Document from the Document Type drop-down box, enter 100 in the sort order (the higher the sort order, the higher the object will be on the page—and 100 will place this page at the top), enter 0 as the Parent ID, click the Published check box, and click the Create button.

Published content

By checking the Published check box, this document will be listed on the left navigation bar. In fact, anything that has the Published check box selected will appear on the left navigation bar.

The Text Document object will appear in the main editing section, which is located at the top of the center column of the Administration screen. You will notice that the database engine has applied an ID number to this Text Document. I’ll say for this example that the ID number for the Text Document is 1. This ID number cannot be edited and will be used for the next object’s Parent ID.

The only thing you need to do to this Text Document object is to give it a title (in the Document Title text area). Take care not to use HTML tags here because this section will all be converted to text. After you enter your title, click the Save button. Once the document reappears, you’ll be ready to enter your first summary.

After the document reappears, you will notice that the information displayed in the Create New Document window will be based on the Text Document you just created and will be correct and ready to use. From the Document Type drop-down menu, Text Paragraph will already be selected, the Sort Order will be a lower number than that of the Text Document you just created, and the Parent ID will already be set to the database-generated ID number of the Text Document (in this case, 1). Do not click the Publish check box, and click Create.

Then you will see a new window that will look like Figure C below.

Figure C
This very simple interface allows you to enter the body of your page through the HTML text area.

First, you’ll want to give this paragraph a title by entering the text of the title in the Document Title area. Then, you will want to select an image (if necessary) by browsing through the Image Upload section. Once you have selected the image, choose its location from the Image Position drop-down box.

At this point, you will click what type of text will be entered as the text of the document. If you plan to use any HTML within the text, you obviously need to select HTML. Likewise, if you use a PHP in the text, select PHP. If the text will be straight text, select Text. If the text of the document will be taken from an external location, select External. (Note: This must still be Text, HTML, or PHP.) If you choose External for your Body Type, the given external (HTML) document or URL will be displayed. (File Upload helps you to upload HTML/Text/PHP files, offering a nice replacement to cutting and pasting.)

If you are entering your text by hand or cutting and pasting your text, do so in the large text area. Once you have entered your text, click Save and you will be brought back to the same window. If you included an image in this document, you will now have to revisit the image section and select the image from the Image drop-down box (it will only appear after the first save).

If you click on the Home link from the left navigation bar (this Home link is actually the Text Document you created a moment ago), you will see the Text Paragraph you just created. Of course, if you are still logged on as administrator, it will show up in the Edit window instead. To see the page as users will see it, you must log out of administrator.

One nice little feature of this tool is the ability to set the document as Published. By setting a document as Published (this is selected either from the Create New Document section or the Edit Document section), you will make a clickable link appear for that item in the left navigation bar.

One of the limitations of this application is its inability to cleanly create summaries on the main page that have clickable links or titles within the document that will direct you to the full story. I discovered a way around this mess by creating the Text Paragraph (within the main Text Document), then creating the page the summary will link to (making note of the URL of the new page), and then embedding the linked page’s URL in the Text Paragraph summary on the main Text Document. For this, the hierarchy would look like:

I. Text Document (main page) ID 1
     II. Text Paragraph (first ‘summary’ on main page) ID 2, Parent ID 1
          III. Text Document (page first ‘summary’ is referring to) ID 3, Parent ID 2
              IV. Text Paragraph (body of Text Document ID 3) ID 4, Parent ID 3

So, from the above hierarchy, you should be able to see that your new page (Text Document 3 with child Text Paragraph 4) is linked to from the Text Paragraph 2, which is a child of Text Document ID 1.

It may seem a bit confusing now, but once you start getting used to the hierarchies, it’s really simple.

Conclusion
We’ve only scratched the surface of what this application can do. But don’t worry, we’ll be revisiting this soon so that we can complete the tour of the AWF news/Web portal builder, as well as cover the creation of File Uploads, News, and Forums.

After using this application for about three weeks, I’ve become quite fond of its simplistic ability to create very rich and pleasing portals. I am shocked that this application is flying so low under the radar of enterprises in need of fast, stable, and feature-rich news/Web portals for both their internal and external networks.

If you are looking for a tool to build database-driven, dynamic sites, look no further than AWF to fit the bill.