Site hosted by Angelfire.com: Build your free website today!
Chico Digital Engineering

Administrator's Guide

Introduction
Integrating Web Tool into your Web Site
Creating HTML Template Files
Customizing Link and Text Formatting
Re-arranging Page Link Order
Using .htaccess for Password Protection
Managing the Web Tool Database File
Performance Limits on Web Tool

Introduction

Web Tool can be the editor for an entire web site, or just a single page on a web site. It's just a matter of where you place the Web Tool content directory and how you link into the pages that it creates from other pages on your web site.

WebTool 1.0 does not control who can access certain pages; all user who have access to webtool.cgi can edit or delete any page. Deleting a page within the Web Tool editor will also schedule that static HTML page to be deleted at the end of the edit session.

On any Web Tool controlled page, it's always possible to add static links back to other static pages on your site; this is done by adding that information into the HTML template itself. For example, you can add a horizontal banner of links to the main sub-categories on your web site home page.

HTML template files don't have to be static: they can have forms, javascript and other dynamic content in them. Web Tool simply pastes in a single text area from it's database into the template file and writes it to it's proper location. So, for example, adding a search form or other dynamic content is easy.

Another application of multiple templates is to allow users to customize the attributes of a page by selecting templates that only differ in that one attribute. For example, the templates BlueWithLogo.html and BlueNoLogo.html can be two identical pages with only one visual change. Since Web Tool allows an unlimited number of templates, many different formatting options can be made available to the user in this manner.

Web Tool works by combining the user text box input with the HTML template for that page. Note that any changes made directly to the static HTML file will be overwritten by Web Tool. In other words, never directly edit files that are generated by Web Tool. Users must edit the page via the Web Tool interface.

Administrators can force changes to a HTML template to be propagated to all web pages using that template. Change the template file, then go into the Web Tool editor and 'end session' and then select 'regenerate all pages'. This will rewrite all web pages using the updated template files. If one template controls a dozen pages, all these pages will be updated.

Note that by default, page link names added to a page are also in the main text area turned into clickable links. So it'd be possible to use this feature to create pages that have links within the text body, and the template for that page would not need the 'link_list' tag. This would be a way to allow the user to gain edit control of the entire body of the web page, and yet also allow them to link to it's own sub-pages.

For example, if you name a link page 'my story' and the text 'my story' appears on that page's text, the final static HTML page created will replace that text in the text body with a clickable web link to the 'my story' page.

If you aren't experienced with Perl or HTML, we can configure Web Tool to your needs at a very low cost. Email us.

Integrating WebTool into your Web Site

In the examples below, BASE_TITLE, CONTENT_URL, and CONTENT_DIR refer to variables that are created in the startup script, or can be edited later in the cgi-bin directory config file WebTool/Config/wtConfig.pm.

Here are some examples of web site configurations:

Example 1: You can use Web Tool to generate an entire sub-section of your web site. Other pages from your site will link into the Web Tool-controlled area by static links to the base content page. So if your base page is 'Current Events', you link into 'CurrentEvents.html' in the Web Tool CONTENT_DIR, and the subcategories 'Music', 'Theatre', 'Lectures', 'Recreation', can then branch off from this point. The tree structure of pages Web Tool creates can be as large as needed. This entire area of the site can then be managed through the Web Tool interface; your authorized users can add, delete and change pages within this area without any need for further technical administration.

Example 2: You may want to have a single web page controlled by Web Tool. This is just a matter of linking from your static HTML pages into the Web Tool "base page" and using that to allow user edits. You should create a template that does not include the link list tag, so this base page will only be user text. During the initial setup, set the BASE_TITLE to the name you want for the web page. For example, if you want the page to be called 'closeouts.html', set the BASE_TITLE to 'closeouts'. Spaces are removed from the base title, and only letters, numbers and spaces are allowed; note that spaces are removed to form the filename. So a BASE_TITLE of 'Current Events' will become 'CurrentEvents.html'.

Example 3: You can have any number of Web Tool edited pages anywhere on your site, controlled by a single instance of Web Tool.

Since Web Tool always creates static pages in the same web directory, named after the link name given in the editor, if you hold this list of pages constant (if you don't delete pages or move them within Web Tool), the pages edited by Web Tool will always have the same static URL (web address). Thus you can link into these pages from anywhere else on your site.

New pages can be directly added to the base page. Users can see what the static URL of that page is by ending the session, have the editor write static files, and then browsing to the page you created; use the static URL of that page as a link from other pages on your site.

As long as the page isn't deleted within Web Tool, it will always be placed in the same directory and have the same name, and so the static link will always be valid.

Example 4: Web Tool can be the editor interface into an entire web site. Just configure Web Tool wtConfig.pm variables CONTENT_URL and CONTENT_DIR to be the base web directory of the site, and set the BASE_TITLE to 'index'. Web Tool is now the interface to all web pages on that site, since the site index.html page is the Web Tool base page.

Example 5: Since Web Tool allows an infinite number of links and pages, you can make access to the page editor script public and use Web Tool as a way for visitors to directly add web pages to your site. Since visitors have an interest in the subject of your site (that's why they're visiting), allowing them to add web pages directly empowers then in a way that a guest book or discussion group posting never would.

For example, a web site could have a self-serve online resource listings, or product reviews or event listings. Visitors can navigate to the appropriate sub directory themselves, or create their own subdirectories.

Although this certainly leaves your site open for inappropriate content, most visitors are responsible and pages can be removed or edited as needed.

Creating HTML Template Files

The templates used to create user web pages are in www/WebTool/Templates/user. Any file in this directory with a '.html' suffix will appear in the pulldown menu on the editor screen, regardless of whether it is a valid template file or not. Valid template files must have at least the main body tag, 'content_string'.

Templates are HTML files with tags inserted that are recognized by the application. Preview HTML and the final static HTML files are created by simply replacing the tags with data from the Web Tool database. Each tag is replaced by an associated data field.

Here are the current tags for Web Tool HTML template files:

    <!-- INSERT_TEXT=link_list -->

      The list of links.
      In vertical format by default, you can edit the HTML format of each link in Customize.pm (see below)

    <!-- INSERT_TEXT=content_string -->

      The main text area

    <!-- INSERT_TEXT=main_category -->

      This is the first sub-directory name

    <!-- INSERT_TEXT=directory_path -->

      The directory pagth.
      This is the directory path describing your current location within the Web Tool structure: 'first subdir : second subdir : etc : etc'.

None of the tags are required, although the page will be an empty template with no tags. If a tag is not found in the file, that data simply isn't used. If a tag in a file does not have a corresponding data string, the tag will be replaced with an empty string.

Customizing Link and Text Formatting

For administrators or technical staff that want to customize the formatting of the Web Tool controlled page links and/or the user textbox entry formatting, we have encapsulated these functions into the file cgi-bin/WebTool/WebTool/Customize.pm. This is a Perl language module, be careful to save backup copies if you edit it.

The source code in Customize.pm has general instructions and examples.

There are currently two functions: TextFilter() processes user textbox input, and SetLinkFormat() controls the HTML format of the page links that Web Tool writes into the "link_list" tag area.

    TextFilter() currently implments the default function of replacing newlines with HTML < BR > tags. This can cause alignment problems for pages if the user adds large amounts of HTML formatting. You can thus disable the line break feature here.

    The page links that are controlled by Web Tool have a default HTML format, but the graphical layout of your pages may require you to change this. SetLinkFormat() processes each link, returning the HTML format string back to the program. By editing the string format within this function, page links can be aligned properly with HTML templates.

Rearranging Page Link Order

There is no way to rearrange the page order through the editor interface. I realized this is an issue and future versions will provide an up and down arrow alongside each page entry to push it down the list or raise it up. This will be a no-cost upgrade for those who buy the 1.xx Site License.

Here is the 'hard' way to do it (it's not really that hard): download your database file (cgi-bin/WebTool/Data/.pm) and open it up in a text editor. There are a bunch of nested data structures that represent the data, and you just need to find the "link_order1" array that represent your top page and rearrange the order:

     "link_order1" => [
          "Off Leash Areas",
          "Dog Friendly Accomadations",
          "Forums",
          "Contact Us"
        ],

By rearranging the order of the entries in this array, that will change the order as they appear on the editor page (and on the finished static web page). Be sure to save a backup file of the original before you edit it, you'll get a Perl syntax error if there are problems. Upload the file back to your server and that should do it.

Using .htaccess for Password Protection

An easy way to add password protection for editor access is to setup your cgi-bin/WebTool sub-directory with the .htaccess protocol (as the demo does on the chicodigital.com site) on unix based web servers.

This will prompt users to enter a name and password in order to access any file in the protected directory, including scripts such as webtool.cgi.

There are many tutorials on the web regarding setting up the .htaccess file on unix/linux web servers, just do a google search for ".htaccess tutorial".

Note that .htaccess supports access groups. It's possible to set the access restriction to Web Tool to a group definition. You can then create separate name/passwords for each Web Tool user, and assign them to that group, rather than giving multiple users the same password.

Here are some web links to htaccess tutorials:


Managing the Web Tool Database File

Moving or renaming the database file requires that you manually edit the Config/wtConfig.pm BASE_TITLE entry to the new name, and also, you must edit the package declaration WITHIN the database file.

The setup script writes the initial database file using the BASE_TITLE entry. If you change the BASE_TITLE, you must also rename and edit the cgi-bin/WebTool/Data/.pm file. You cannot simply rename this file; you must also edit the declaration at the top of the file, "package Data::.pm. Change this entry to match your new BASE_TITLE.

Any changes should be immediately recognized the next time webtool.cgi is run.

When you're using Web Tool, it's important to maintain backups not just of the static pages, but also, more importantly, of the Perl Database cgi-bin/WebTool/Data/.pm and all the templates in the www/WebTool/Templates/user directory. This is the real source of the web pages controlled by Web Tool. If you lose these, there is no way to edit the files (although you could go back to editing the static HTML files if they were preserved).

The fact that Web Tool generates static HTML also means that any failure of the Web Tool application doesn't effect the current web site content. Visitors will still be able to access all content that was generated, even if Web Tool is un-installed or disabled.

The Perl Database Archive File

In the directory cgi-bin/WebTool/Data/archive are backup copies of the Perl database file. A backup is created each time a user re-writes the database (each page edit submitted). Note that a single editor session may iterate through dozens of page submits, so the archive can be filled up quickly on an active site. The ARCHIVE_DEPTH variable set up at startup config controls how many backup files are saved. And can be changed in the cgi-bin/WebTool/Config/wtConfig.pm file. It is set equal to the number of backup copies that should be stored.

The HTML Output directory

CONTENT_URL and CONTENT_DIR in the config file Config/wtConfig.pm control where the static HTML pages are created. These variables are initially set up by the installation script, but can be edited at any time to change where Web Tool writes it's static pages.

Performance Limits on Web Tool

There are no built-in limits to the size of web pages or the number of web pages that Web Tool can handle, however there are performance limits due to the hardware limitations of the machine it runs on. Perl is not the most efficient language, and whether Web Tool can manage X web pages is largely a matter of the processing power, loading and memory of the server it runs on.

For example, we've characterized Web Tool on a 100 Mhz Pentium server with 32 MB of memory running apache and Red Hat Linux. The difference in server response time between 1 small web page and 20 medium sized web pages (~100 kb of text data) was about 20%. It was still very useable, with average response times under 350 ms (1/3 of a second).

Running Web Tool from a hosting service is generally not a problem, but if your hosting service overloads their server with hundreds of accounts, Web Tool may not have decent performance. Considering the slow site response of many database-driven web sites, we think Web Tool performance on sites with less than 20 pages to be be excellent.

What about large sites? We have internal versions of Web Tool that have been fully optimized to take advantage of apache mod_perl. Mod_perl is a way apache web servers can cache Perl executables in memory. Mod_perl is free and easy to install. Web Tool runs 4 to 10 times faster when running on mod_perl. More importantly, the size of the database Web Tool does not degrade web server performance appreciably. Server platforms with 2 GB of RAM are common these days, and with low DRAM prices, there is no reason why Web Tool cannot be the core technology for the largest web sites.


Copyright 2002
Chico Digital Engineering
contact: support@chicodigital.com