WASD Hypertext Menu Primer

[next] [previous] [contents] [full-page]

3 - Menus

The purpose of this menuing system is to provide a simple interface to required files.

To allow the easy management of information by users not needing to explore the relative complexities of HTML a simple menuing system makes a clearly presented page available to the client, allowing versatile document retrieval and searching. This is provided through the maintenance of a simple, plain- text file, which may be edited on any platform (PC, VMS, Unix) and then just placed into the appropriate data area.

This plain-text file is essentially made up of a series of lines that comprise a file name followed by a description (series of words to the end of line). Each of these lines is presented to the client as an item in a list that can be selected for access. In its simplest form:

  FILE1.TXT   This is the First File
  FILE2.TXT   This is the Second File
  FILE3.GIF   This is an Image (and the third) File

An online example:

When specifying the file items within a menu the file name may not contain spaces (not unreasonably!). The first space encountered terminates the file name. Spaces between the end of the file name and the next non-space character are ignored. All characters from the first non-space are included in the item description. The description cannot be continued on the following line. It is reported as an error if no description accompanies a file name.


3.1 - Providing a Menu Title

To allow a title to be placed on the menu (large, bold font) the plain-text file may comprise two blank-line separated sections. The first section, which should be only a single line, is interpreted as the title and presented as such. The blank line indicates that the next section of lines represent the list of items (files for access) to be presented to the user. An example would be:

  This is an Example Menu

  FILE1.TXT   This is the First File
  FILE2.TXT   This is the Second File
  FILE3.GIF   This is an Image (and the third) File

An online example:


3.2 - Providing a Menu Description

In addition to a title it is often desirable to provide a brief introduction to, or description of, the menu and its purpose, etc. This may be accomplished by adding another blank-line delimited section. It must follow the title line and precede the menu items, and may comprise as many lines as required. For example:

  This is an Example Menu

  This is an example menu.  It has a fairly
  simple structure, yet provides a elegantly
  presented user menu.

  FILE1.TXT   This is the First File
  FILE2.TXT   This is the Second File
  FILE3.GIF   This is an Image (and the third) File

An online example:


3.3 - File Specification

File are specified using URL syntax. See 2 - Data Organisation.


3.4 - Menu File Requirements

The menu file, being simple plain-text, may be maintained using the text editor of choice on the platform of choice (PC, VMS or Unix), and subsequently placed into the appropriate data area. For instance, a PC Pathworks user may USE to the appropriate VMS data area, then according to preference, copy the file to a local disk, edit it, and copy it back to the data area, or may edit directly on the network drive. The former is probably safer, allowing intermediate editing to be saved locally without affecting the actual online menu.


3.4.1 - Menu File Naming

A menu file may have any name acceptable to VMS, but must have the extension .MENU or .MNU (MS-DOS compliant) for the server to recognise it. It is recommended to name a directory-based menu HOME.MENU (or HOME.MNU) for the following reason.

If the server is given a URL comprising only a directory name it attempts to open a home page for that directory. It tries to open one of four files in the following order:

  1. HOME.HTML
  2. HOME.HTM
  3. HOME.MENU
  4. HOME.MNU
In this way directory access may be transparently supported by either HTML or MENU files. Any directory meant to made accessable to a user need only contain one of these files, and if the client specifies only the directory name a home page will be found. If none of these files can be opened the server returns an error.

The following are example URLs:

  /web/  This one exists (home page for WASD)
  /web/html/  This one does not exist (at least at time of writing!)

The following provides an online demonstration:

Note that the URL directory specification has a final "/". This indicates it is a directory not a file.


3.4.2 - Restrictions

The menu text is interpreted by the browser as HTML. This allows the menu file to contain HTML tags to enrich the presentation if desired. It also means that some characters cannot be used within the text (due to HTML restrictions). These are few and easily substituted:

- NOTE -

Although allowed, extensive HTML markup of a MENU file is counter- productive and is discouraged. If this is desired, then the file is better considered an HTML file and not a MENU file. Rename it to filename.HTML and forget the menuing functionality.

Blank Lines

Please remember the purpose of a blank line within a MENU file file is to separate the functional sections (title, description, items). Arbitrary blank lines cannot be included.


3.4.3 - File Permissions

As the server executes as a normally privileged process, files it accesses must be world-readable, or specifically have the server account granted access in an ACL.

A protected file results in the server returning an error message and aborting the request.


3.5 - Online Menu Example

The first of these links retrieves an larger example menu containing some of the features described in the section on additional functionality, the second is a copy of its plain-text source. There are actually two files with identical content here. As with other similar examples in this document, the reason for the difference in presentation is the first has a .TXT file type (and is treated by the server as plain-text), while the second has a .MENU file type (and is interpreted as a menu).


[next] [previous] [contents] [full-page]