WeaveWeb

Automated Web Site Maintenance

WeaveWeb © 1999-2001 Gert Poletiek, gert@gerts.net

Contents

Introduction

WeaveWeb is a Web site maintenance utility that simplifies building Web sites with a consistent look and feel. While you concentrate on the content and documents you wish to publish, WeaveWeb takes care of building the headers, footers and navigation sidebars and a complete site map web page.

When run, WeaveWeb also checks all URL's to documents on the local Web server. Unresolvable URL's are flagged as an error. This a valuable aid when you move documents around.

WeaveWeb supports multi-language web sites and automatically generates a language switch using userconfigurable buttons or text. WeaveWeb has no limitations for the number of languages it can support.

WeaveWeb uses tables and cascading stylesheets and a sitespecific layout file (in html) for consistent styling of the web pages. HTML frames are not supported as frames gives you less control over placement of elements on a webpage. WeaveWeb generates the following page layout (when used with the sample layout):

For different page styles and layouts alternative layout and stylesheet files may be used.

The appearance of the generated web pages can be influenced through the weaveweb.conf file as explained below.

Website Structure Convention

WeaveWeb will only successfully build your website if you adhere strictly to the WeaveWeb directory structure convention. Filenames also need to be standardized throughout your web-site. The base of the filenames can be set through the weaveweb.conf file.

Directory Structure

To illustrate the structure we take the sample site that you can also find in the navigation bar of this document. The toplevel directory is called sample; it contains the homepage, the weaveweb.conf file and all other web documents inside subdirectories. The example contains both english and dutch pages.

sample................Directory
  weaveweb.conf.......Your site's weaveweb configuration
  doc_en.html.........Your homepage in english
  doc_nl.html.........Your homepage in dutch
  directory1..........Subdirectory 1
    doc_en.html..........Subdocument in english
    doc_nl.html..........Subdocument in dutch
  directory2..........Subdirectory 2
    doc_en.html..........Subdocument in english
    doc_nl.html..........Subdocument in dutch

The number of subdirectories in your website is unlimited by WeaveWeb. The nesting level (directories inside directories) is limited to 100. This is an arbitrary constant in the WeaveWeb program. If you ever need to enlarge this constant, your webdesign is flawed: nobody will ever want to navigate up to a 100 levels deep.

Note that there are no files called index.html and that all documents are inside their own directories and have "doc_XX.html" as standard name All documents that WeaveWeb examines must have the same name (with XX replaced by a language identifier; both the document base name and the language identifier can be changed through the weaveweb.conf file.

The basename of a document (doc) is appended with an underscore and the abbreviated language identifier (the example uses nl for dutch and en for english).

When WeaveWeb is run on the sample directory WeaveWeb will add files as shown below:

sample................Directory
  index_en.html.......GENERATED: the english page
  index_nl.html.......GENERATED: the dutch page
  index.html..........GENERATED: a symbolic link to your default page
  weaveweb.conf.......Your site's weaveweb configuration
  doc_en.html.........Your homepage in english
  doc_nl.html.........Your homepage in dutch
  directory1..........Subdirectory 1
    index_en.html........GENERATED: the english page
    index_nl.html........GENERATED: the dutch page
    index.html...........GENERATED: a symbolic link to your default page
    doc_en.html..........Subdocument in english
    doc_nl.html..........Subdocument in dutch
  directory2..........Subdirectory 2
    index_en.html........GENERATED: the english page
    index_nl.html........GENERATED: the dutch page
    index.html...........GENERATED: a symbolic link to your default page
    doc_en.html..........Subdocument in english
    doc_nl.html..........Subdocument in dutch

Never edit the files WeaveWeb generates! Your changes will be lost each time WeaveWeb is run.

Configuration

WeaveWeb is configured through the weaveweb.conf file which must be present in the top-level directory of your web-site (next to html document of your homepage in general). The configuration file shown is discussed in detail.

Global 
	Server			http://www.gerts.net
	ServerRoot		/home/web
	Site			yoursite
	PrivateStyle		false
	UseRootTitle		true
	Layout			style/layout
	StyleSheet		style/sample.css
	DirFooter		footer
	MenuOrder		menuorder
	TopMenu			topmenu
    	MenuHierarchy           false
	SiteMapDir		sitemap
    	DocBase			doc
	IndexBase		index
	ScriptBase		script
	Html			.html
	Cgi			.cgi .CGI
	PruneFile		.noweave
End

Language en
	TopIcon1		style/images/icon1.gif
	TopIcon2		style/images/icon2.gif
	TopIcon1Href		/someurl
	TopIcon2Href		/someotherurl
	Signature		username@gerts.net
	Footer			<HR>
	Message			'English message'
	Switch			'English'
	HitCountText		'hits in'
	LastUpdateText		'last update'
	NoTitle			'No Title'
	Search                  'http://your_search_page'
	SearchTag               'Search'
End

Language nl
	TopIcon1		style/images/icon1.gif
	TopIcon2		style/images/icon2.gif
	TopIcon1Href		/someurl
	TopIcon2Href		/someotherurl
	Signature		username@gerts.net
	Footer			<HR>
	Message			'Nederlands bericht'
	Switch			'Nederlands'
	HitCountText		'maal geraadpleegd in'
	LastUpdateText		'laatste wijziging'
	NoTitle			'Zonder Titel'
	Search                  'http://your_search_page'
	SearchTag               'Zoek'
End

The weaveweb contains at least two sections. One global configuration (between the keywords Global and End; and at least one language section Language XX and End tags). All keywords are case-insensitive.

The Global section

Server	Default value: http://localhost The Server variable identifies the URL of the server your website is hosted on. It is essential for building the navigation bar. Do not assign a complete URL such as http://servername/path to the Server variable: this yields unusable URLs in the generated documents.
ServerRoot	Default value: /home/web The ServerRoot variable identifies the path to the webserver root directory. The path must be specified in the UNIX namespace. Note that a UNIX path is case sensitive.
Site	Default value: no value The Site variable identifies the directory where your website is. This directory is relative to the ServerRoot directory. E.g., if your task is to build a website in /home/web/somesite the path would be "somesite". Note that a UNIX path is case sensitive. The Site variable can also have the special value ~username. In that case WeaveWeb will build the website in ~username/public_html. Note that WeaveWeb will check that you're actually building in the ~username/public_html directory to prevent erroneous html from being generated.
PrivateStyle	Default value: false The PrivateStyle variable determines if the style files are taken from the main server (PrivateStyle is false) or from your own website (PrivateStyle is true). The default for this variable is "false", i.e., use the main site's style files.
UseRootTitle	Default value: true The UseRootTitle variable determines whether WeaveWeb includes the title of the document at the ServerRoot location in the navigation bar. If the value is false your homepage will be taken as the starting point in the navigation bar; if true the title of the organization homepage document will be the starting point. For personal homepages this variable is typically set to false.
Layout	Default value: style/layout The Layout gives the location for the layout file that determines the webpage composition. The full path to the layout file is constructed by concatenation of the values of the Site and Layout variables.
StyleSheet	Default value: style/local.css The StyleSheet gives the location for the the CCS stylesheet files. The full path to the stylesheet file is constructed by concatenation of the values of the Site and StyleSheet variables.
DirFooter	Default value: footer The DirFooter defines an alternate directory dependent footer file. If a directory contains footer_language (language being one of the language identifiers for your website) when the index_language.html is being generated the contents of the footer file is included in the index to act as the page footer. Note that you must create a footer file for each language your website uses (See the Language variable), to get consistently generated pages.
MenuOrder	Default value: menuorder The MenuOrder variable may be used to set the name of a per directory file containing ordering hints used to order the items in the navigation menu. See below for a detailed description.
TopMenu	Default value: topmenu A file searched for in each of the directories comprising the website. Its contents is a list of key/value pairs, one on each line. The key and the value should be separated from each other using a semicolon (:). The key is a text, the value an url. These are used to build a navigation menu separate from the normal directory-structure navigation menu. Its orientation is horizontal and it is normally placed on the top of the webpage. If the topmenu file is missing (which is not an error), weaveweb will automatically add a "Home" button in the navigation menu. The topmenu is only generated if the layout file contains the replacement key '#topmenu#'. See below.
MenuHierarchy	Default value: false The MenuHierarchy variable determines the appearance of the navigation menu. If false, the navigation menu is right-aligned. If true the menu is left aligned and has a pop-open behaviour, i.e., if a user clicks on an item subitems are shown in context. The indentation level shows the hierarchy. The hierarchical menumode (MenuHierarchy true) is not recommended if titles in your website are long: they may become clipped using ellipsis (...) to prevent wrapping of menu-items to new lines.
SiteMapDir	Default value: sitemap The SiteMapDir (create it in the toplevel directory of your website) will be used to store a WeaveWeb generated html page that shows the layout of your website. If the directory named in the SiteMapDir variable is not present the site map layout page will not be generated.
BodyBGColor	Default value: white The BodyBGColor variable is depricated and has no effect. It is accepted only for backward compatibility reasons.
DocBase	Default value: doc The DocBase variable sets the default basename for documents and may be chosen freely.
IndexBase	Default value: index The IndexBase is the basename for index files (its value is dictated by the webserver configuration).
ScriptBase	Default value: script The ScriptBase variable sets the basename for CGI scripts, and may be chosen freely.
Html	Default value: .html .htm The Html variable lists the extensions for documents.
Cgi	Default value: .cgi .CGI The Cgi variable lists the extensions for CGI scripts.
PruneFile	Default value: .noweave The PruneFile variable sets the filename that will inhibit WeaveWeb to examine a directory if the named PruneFile is present. You should create a PruneFile in every directory that WeaveWeb should not descend into. WeaveWeb warns you for directories it thinks should contain a PruneFile.

The Language section

The language sections specify some variable that may contain language dependent text or images.

The line "Language XX" sets the language to XX and implicitly completes the filenames examined and generated by WeaveWeb. Weaveweb constructs filenames as follows:

file type	constructed using	example (default)
document	DocBase _ Language Html	doc_en.html
index	IndexBase _ Language Html	index_en.html
script	ScriptBase _ Language Cgi	script_en.cgi and script_en.CGI

The other variable influence the appearance of the header, footer and sidebar.

Signature	Default value: no value SignatureThe email address of the website maintainer, display inside a MAILTO environment on the righthand side of the footer.
HitCountText	Default value: no value HitCountText is a text appended to the number representing the number of visits to a webpage. Typical value: 'visits in'. The visit counter is prepended to this text, and the current month is appended tothis text.
LastUpdateText	Default value: no value LastUpdateText contains the text prepended to the date of last modifications for the page. Typical value: 'last modified'.
Message	Default value: no value Message contains the message in the header of the page. You may use this to refer to a 'last updated page' or to put the name of the department in the header.
Site	Default value: no value The Switch is the HTML element that WeaveWeb inserts to create a language switch. This will of course only be used if your web pages use two or more languages.
NoTitle	Default value: no value The NoTitle variable is used in the navigation bar and the side bar whenever WeaveWeb is unable to determine the title of a document. Ideally this text is never used (then all your pages are correct).
Search	Default value: empty string The Search variable may be used to enable a search button on every webpage WeaveWeb generates. The value of the Search variable should be the URI of a searchform. The default is to not present a search button (the value is the empty string). When the Search variable is defined the SearchTag should also be defined.
SearchTag	Default value: no value The value of the SearchTag variable is the text for the button directing the user to the searchform.
TopIcon1 TopIcon2 TopIcon1Href TopIcon2Href	Default values: no value TopIcons can be used for banner images. When defined in your configuration (and subsequently used in your layout file (see below) these images become clickable and guide the visitor to one of the two associated URL's.

Operation

To use WeaveWeb you should login to the web server (using telnet or rlogin) and then change to the directory where your website is stored (e.g., /home/web/somesite). Then run the WeaveWeb program (sample output is shown).

$  cd /home/web/somesite
$  weaveweb

(Note: the $ is the default unix shell prompt and may be different).

WeaveWeb is supported only on UNIX; Windows and Macintosh users can edit their web pages using their favorite html editor but must run WeaveWeb on the webserver.

WeaveWeb will fail if you cannot write to the directories WeaveWeb examines.

If you use WeaveWeb for the first time, it will generate all index files as well as the sitemap. For the sitemap to show up in the navigation bar you should run WeaveWeb for a second time.

If you intend to use WeaveWeb on an existing web-site, do try it out on a scratch document first. Since WeaveWeb rapidly writes new index files, running WeaveWeb on a production site may inadvertly destroy exsting (handcrafted) index files.

Special Tricks

WeaveWeb will never traverse symbolic links in the UNIX filesystem to ensure it doesn't disturb other people's web pages.

There is however a special trick in the way WeaveWeb handles symbolic links that allows you to refer to other web sites and show the other website in your navigation bar.

On UNIX, in your web site directories, you can create the following type of (seemingly invalid) symbolic link:

$  ln -s 'http://webservername/johnspage'  'My_Reference_to_John.en'

After you have run WeaveWeb the text My Reference to John (note the underscores are gone) will show in the navigation bar for language 'en' and clicking it will direct you to the server http://webservername/johnspage.

You can also put other service types in the symbolic link. Below is a couple of examples:

$  ln -s http://www.gerts.net/weaveweb  Link_to_WeaveWeb_Homepage.en
$  ln -s http://www.gerts.net/weaveweb  Link_to_WeaveWeb_Homepage.nl
$  ln -s ftp://ftp.gerts.net  Link_to_FTP_server.en
$  ln -s ftp://ftp.gerts.net  Link_to_FTP_server.nl

If your create a symbolic link to a directory or folder that starts with 'http://server/site', e.g.:

$  ln -s http://server/site/search  Search.en
$  ln -s http://server/site/search  Search.nl

CGI Scripts

Some sites have CGI scripts written in perl5. Those scripts generate HTML code on the fly and would normally not show up in the navigation bar or the site map page generated by WeaveWeb.

When you insert a perl comment with a speudo-html tag

# <SCRIPTTITLE>My script has a name!</SCRIPTTITLE>

in your script, WeaveWeb will recognize the name and will generate the navigation bar entry and sitemap reference correctly.

This trick may also be used in scripts written in other languages than perl.

PHP4 Support

For each directory containing a doc_XX.php file, weaveweb will generate the corresponding index_XX.php file.

If the webserver itself is configured to support PHP4 for your website, the PHP4 index files will automatically show in a browser.

Errors

WeaveWeb may issue errors in each of its three phases. During the initialization phase WeaveWeb may detect errors in your configuration file.

During the second phase (scanning phase) WeaveWeb can issue an error such as:

Stop at ./weaveweb/sample: directory not writable

This means the named directory cannot be written to by you, and therefore that directory and all directories below it are not scanned by WeaveWeb. If, for example, there are two maintainers for a web-site (one for the entire web-site and one for a subsite of the web-site) both maintainers can use WeaveWeb. The subsite maintainer can make sure the other maintainer will not inadvertly rebuild index files using WeaveWeb by making the first directory (top directory) of the subsite unwritable by the other maintainer.

During the third phase (writing phase) WeaveWeb can issue the error:

Stop at ./weaveweb/sample: cannot open index.html: permission denied

This indicates something is wrong in your web directory structure. WeaveWeb has detected a file it should regenerate but can't access. Most likely the named file is not group-writable.

Ordering Menus (non-edible)

The order in which menu items appear in the menu is by default determined by the alphabetical order of titles of the documents the items refer to. Since this may not be identical to the importance of the items, WeaveWeb can be assisted in the ordering process by a per directory order file.

The name of the per directory orderfile can be set through the MenuOrder configuration variable. The default value for this variable is "menuorder".

If a file called "menuorder" is present in a directory it is used by WeaveWeb as an aide in sorting the menu items.

Each line in the menuorder file may contain the single name of a subdirectory or symbolic link in that directory.

If a directory contains the following directories: A, with document title "A"; B, with document title "B" and C with document title "C". Then the default order would be: A, B, C.

If you create a menuorder file in that directory with the following contents:

   a
   c
   b

WeaveWeb will create a menu ordered as: A, C, B.

As you can see from the example, WeaveWeb compares the names in the menuorder file and the names of the subdirectories in a case-insensitive manner.

Now, if the directory also contains a symbolic link for languages "en" and "nl", the directory could contain: A, B, C, Symbolic_Link.en and Symbolische_Link.nl. (Remember that symbolic names carry the names as they appear in the webpage).

Since there is only one possible "menuorder" file, the names of both symbolic links should be entered in menuorder file (including the language extensions "en" and "nl"). Suppose you'd want to order the menu as follows: C, Symbolic links, B, A, then the menuorder file should look like

   c
   Symbolic_Link.en
   Symbolische_Link.nl
   b
   a

WeaveWeb will treat the contents of the menuorder file as follows:

• Whitespace at the start or the end of lines are insignificant.
• Lines starting with a hash ('#') are considered comment lines.
• Empty lines are ignored.

If directorynames are not found in the menuorder file, they automatically float to the bottom of the menu and are sorted alphabetically.

Building Layout Files

The layout file(s) used by WeaveWeb are itself HTML documents. The layout file specifies the standard layout for all pages in a website. Elements in each generated webpage are specified in the layout file using special keywords recognized only by WeaveWeb.

Each webpage generated by WeaveWeb is a combination of:

• the layout file
• static information from weaveweb.conf
• the contents of a specific doc.html file
• dynamic information depending on the location of the document in the web structure (navigation elements)
• dynamic information provided by the webserver (Apache), such as reference counters, last date of modification of the document.

In order to generate the final webpage, WeaveWeb replaces special keywords found in the layout file. You may use the following keywords:

#scriptname#	The name (including full path) of the WeaveWeb executable. Can be used in HTML comments to indicate how to regenerate a webpage.
#stylesheet#	The URI for the stylesheet that your documents should use. The value is derived from the weaveweb.conf StyleSheet variable.
#documenttitle#	The title for the generated document. Taken from the TITLE tag in the original document. Normally used in the TITLE tag in the layout file.
#message#	The localized (language dependend) message. Taken from the one of the Message variables in the language sections in the weaveweb.conf file.
#navigationbar#	The horizontally oriented navigation bar showing all titles from the root of the webserver up to the current document. Normally stretches over the entire width of the generated page.
#menu#	The vertically oriented navigation menu showing all titles selectable in the current location (showing titles of documents in subdirectories of the current one).
#document#	The contents of the original document parsed to contain only the HTML code between (and not including) the begin and ending BODY tags. If you do not include the #document# keyword, the generated webpages will not contain any text from the original doc.html file.
#signature#	The signature (language dependend) from one of the langage sections in the weaveweb.conf file.
#footer#	The (language dependend) text from the Footer variable in the in the weaveweb.conf file, or the complete contents of the footer.language file in the current directory.
#hitcount#	The (language dependend) text indicating the number of visits to the webpage. The replacement text for #hitcount# is the numeric value for the visit counter appended with the weaveweb.conf variable HitCountText seperated by a single space.
#lastupdate#	The (language dependend) text indicating the date of last update of the document. The replacement text for #lastupdate# is a date string preceded by the LastUpdateText variable from the weaveweb.conf file seperated by a single space.
#topicon1# #topicon2# #topicon1href# #topicon2href#	Are replaced with the values in TopIcon1, TopIcon2, TopIcon1Href and TopIcon2Href from the configuration file. The icon and its associated href value are output in an IMG tag.
#topmenu#	Is replaced with the parameters found in the topmenu file in each of the directories in the web directory tree.

The layout file is best made using TABLE tags with the BORDER set to 1 and   inside the TD table cells (this is a trick to prevent some browsers from completely 'forgetting' to render a table cell).

Once proper alignment for all elements is achieved, replace the   placeholders with the WeaveWeb keywords.

A very simple layout file, using only the document title, a navigation menu on the left and the document contents on the right would be:

<HTML>
<HEAD>
<!--
    This file is generated. DO NOT EDIT.
    Edit weaveweb.conf, then rerun "#scriptname#".
-->
<TITLE>#documenttitle#</TITLE>
</HEAD>
<BODY>
<TABLE BORDER="0" CELLSPACING="0" CELLPADDING="0">
  <TR>
    <TD WIDTH="140">#menu#</TD>
    <TD WIDTH="660">#document#</TD>
  </TR>
</TABLE>
</BODY>
</HTML>

Revision History

Version	Date	Issue
3.9	2001 April	Generate URI's i.s.o. URL's whenever possible to support SSL http (https). Add variable UseRootTitle.
3.4	2001 April	Sorting in the sitemap works identical to sorting for menus.
3.2	2001 March	Support for MenuOrder variable
3.1	2001 March	force running in ~/public_html when Site variable is ~username
3.0	2001 February	add ~user support, private styles
2.7	2001 February	fixups to remove unneeded extra slashes in generated uri's
2.6	2001 January	bug fixes
2.5	2001 January	language dependend layout; configurable search (also on every generated page); php script support
2.2	2000 March	added hierarchical menus
1.11	2000 February	bug fixes
1.10	2000 February	bug fixes
1.9	1999 November	added background support
1.8	1999 July	fixed trailing / error in generated urls; added .noweave feature
1.7	1999 July	fix sitemap problem in symlinks.
1.6	1999 July	fixed symlink bug in siteindex generation
1.5	1999 July	bug fixes
1.4	1999 June	added write error messages and chmod's
1.3	1999 June	changed case sensitivity of variable
1.2	1999 June	added configuration file reading
1.1	1999 June	Initial revision