---

Planning a Website

Gavin Wraith continues his series

In part 1 I described two general principles that I wanted to apply to the website for which I had been commissioned: Accessibility and Orthogonality. The first effectively means keeping it simple, the second keeping it flexible, with content editable separately from furniture (my term for the overall structure, the means of navigation within the site and any overall theme or style). There is a compromise that any forward planning must settle on, between too little preparation, that can give trouble when unforeseen events require rapid responses, and too much, that leads to wasted effort when plans have to change, say when the commissioners of the project want structural changes. When I was taught to fly gliders, half a century ago, I remember the instructor telling me to keep my eyes on the horizon when we came in to land, and not to focus on particular objects round the runway, and to gauge the craft's attitude out of the corners of my eyes. Coming in to land with a design project is much the same; do not focus on the details obsessively but stay alert.

For my first meeting with the organizers I would need something to show them. Without any content provided yet, all I could do was produce a skeleton. The problem would be that most of its critics would see only the surface appearance, and would not be able to appreciate the necessary work that had gone into the underlying structure. RISCWorld readers, on the other hand, will, I hope, be able to grasp the broader picture. Let me now describe an elementary aspect of planning, often overlooked, which can have a big impact on the real work later on: exploiting the filing system.

I first decided to make the website flat. By this I mean putting all the HTML files into one directory, together with a directory, images, for containing graphics files, and a directory Data for containing all the files from which the HTML files and the graphics files would be constructed. The reason for this choice was that it eliminated a frequent source of bugs - breaking the links to graphics files when files are moved to another directory. When it comes to uploading the site to the server, only the HTML files and the images directory are uploaded - the part indicated within the red oval in the picture above.

The Data directory contained a directory Pages with one high level description file, of type Weave (official filetype number &18d - more about that later) for the contents of each HTML file. My convention was that each Weave file foo created an HTML file foo/html. The furniture for the website was defined in the two text files defs and menus. These files are consulted by the Weave files. Each Weave file can be run separately by double clicking on its icon. The effect is to create the corresponding HTML file. They can all be run simultaneously by double clicking the Obey file Update! which simply contains the line:

do repeat filer_run <Obey$dir>.Pages -type 18d

This updates the whole site after any changes made in the high level description. With this scheme all the website contents go in the directory Pages and all the furniture in defs and menus. Thus is orthogonality achieved.

The scheme that I outline here is about the simplest one can contemplate. To add another webpage means putting another file into Pages and editing menus, which describes a navigation bar. In fact even that could be automated, were it not that labels for navigation buttons are not always best described by filenames. It is also good for a framed version of the website. In that case each Weave file foo should create two HTML files, foo/html and foo0/html, for the framed and unframed versions of the page. It is easiest to construct the HTML file defining the actual framesets by hand, because these are not in the form that Weave assumes as default for webpages. One also needs Weave files for each of the furniture frames. These could all go in their own directory to preserve the barrier between furniture and content. The unframed version of a page will use a table mimicking the framesets and all the furniture entries of the table will be filled in by data from defs and menus. It is important to understand that the Weave files defining the content remain exactly the same, because the differences between the framed and unframed versions can all be hidden in functions defined in defs.

You often see websites with fancy buttons for navigation. Indeed, there are button-factories out there on the internet that provide a bewildering variety of styles and colours. I did not see how I could use these and still retain the flexibility I needed for being able to update with new pages at the drop of a hat. I did a little experimenting with making my own buttons and swiftly came to the conclusion that I lacked the requisite graphics software to do the task satisfactorily. The simplest, easiest and most boring solution is just to click on text. I decided in the end to go for a compromise and have navigation bars resembling lists where each item consists of a graphic followed by text. The graphic would have two forms, open for the current page and closed for the rest, like directory icons.

Now, is this construction actually going to deliver the goods? Much as I had anticipated, when it came to showing off my initial efforts to the sponsors, the only feedback I got concerned the visible details. This taught me that it is probably better to keep mum about the underlying structure. After all, it is what is visible that is the end product, and burdening people with what they do not need to know is not a good idea. What I lacked now was some content, and in particular some appropriate graphics. The only graphic that I had constructed, as decoration for my skeleton, would, I was assured, induce apoplexy in certain quarters, so I hastened to remove it. At least I did get some useful advice about the diverse parts that the website should comprise. However, this brought home to me the realization that putting all the webpages in one directory might turn out to be a bad idea. In the absence of useful content from the sponsors, my only recourse was to experiment with another website that already had plenty of that, but which needed a fundamental restructuring - my own.

So, was it to be back to the drawing board, or could I extend my ideas for orthogonality to non-flat websites? One aspect of the design above that I did not like was having the Data directory inside the directory holding the webpages. It would have been better to have it outside so that all the material to be ftped to the server was in one directory. In fact, I found it fairly straightforward to modify the structure described above to work for a hierarchically structured website, so long as I adopted the following conventions:

• All the webpages in a given subdirectory should share the same furniture.
• Each subdirectory of webpages is ordered by the position of objects in the common navigation bar for it. The bottom item in the navigation bar leads back to the top item in the parent directory, if there is one.

So the new structure would consist of two directories at the same level. Data holds the Weave source for the website and site holds the website itself:

The directory structure inside site should be mirrored by a similar structure inside Data, and each corresponding subdirectory in Data should have the standard equipment that we have seen before.

This scheme provides a compromise between simplicity and flexibility. It keeps the part to be uploaded to the server separate from the machinery that creates it, and allows the furniture to vary according to the subdirectory. Each subdirectory of the website can be updated as a whole by doubleclicking the corresponding Update! obeyfile.

So far I have avoided giving any details about the Weave webpage-description language. They will have to wait for the next instalment, but in preparation let me point out that an HTML document can be viewed as a sort of tree. For example:

The names in red denote text that you fill in, those in black are HTML tags. The corresponding Weave expression is:

    { 
     DOCTYPE;
     HTML {
           HEAD(TITLE(titletext));
           BODY {
                 H1(heading);
                 P;
                 text1;
                 UL {
                     LI; text2;
                     LI; text3;
                    } ; -- UL
                }; -- BODY
         }; -- HTML
    };

Note that the red names correspond to variables, in lower case. Sequences are enclosed in braces and items are separated by semicolons. The -- symbol just denotes a comment. The HTML tags DOCTYPE, P and LI are just constants while HTML, HEAD, TITLE, BODY, H1 and UL are functions; this is because they have corresponding end-tags. What comes between the start-tag and end-tag is the argument, which could be some complicated expression. The parentheses round the function argument can be omitted when the argument is an explicit sequence. But the point about Weave as opposed to HTML is not the different syntax but the fact that you can use variables and functions. In fact Weave provides one or two other keywords (always in capitals to distinguish them from variables in lower case) in addition to HTML tags which means that you do not have to bother with DOCTYPE, HTML, HEAD, TITLE or BODY - a standard template is set up for you.

For the purposes of understanding how the separation of content from furniture is achieved, I will mention here just one of the extra keywords, the function DOFILE. This takes a file's pathname as argument, and calling the function causes the Weave statements in the file to be executed. So common definitions can be used by putting them in separate files and then using DOFILE. Its use is like that of #include in C. The defs and menus files in the scheme outlined above are incorporated into the individual Weave scripts in the Pages directory this way. Because Weave is a higher-order language than HTML we are able to modularize the construction of webpages in ways that are impossible using HTML alone.

Gavin Wraith