Ericsson /// EPL/X/AX  
Polaris
 
Prepared 
EPL/X/AX Gunnar Strand
No. 
Approved  Checked Date 
1998-03-03
Rev 
A
File 

update_menu-HOW-TO

Table of contents

Note: To be able to add/change menu items you only have to read the first three chapters.

Introduction

update_menu.pl is a tool to simplify menu handling on HTML-pages when not using frames. It uses a configuration file to determine how the menu should be constructed and rendered.

How to use the program

The program must be executed when the menu is changed in some way; when a menu item is added, removed or edited. The procedure to do this is simple, just edit the menu configuration file and execute the program.

There are three things you must do to have a menu on a page:

  1. You must have a file which configures the menu. This includes where the top of the www-structure is located, how the menu is rendered and which files are part of the menu. The file is by default called "Menu.txt".
  2. You must run the update program which will create one menu file for each entry in the menu. The menu files will be saved at the same location as the pages which include them.
  3. You must include the menu file in your page.

Running the program

The command line to the program is: By default the program only tests to see if it is able to update the entire menu structure. It is recommended that you always perform a test update at first to make sure everything is allright. Then just add the option "-u" and rerun the program to perform an actual update.

The menu configuration file is a required argument to the program, and in it the option "top_dir" is required, see "Option descriptions" below.

How to add a menu to a file

Add the following HTML code to your file at the position where the menu will be inserted: Then edit the menu configuration file and add the file at the correct position in the menu and execute the update program. Important! Your file's name must have the suffix ".shtml" or the menu will not work.

Example

How the program does its job

The configuration file in this document is called "Menu.txt" but you can name it whatever you like. There also exists files with rendered menus, one for each menu item with a relative path.

When the program is invoked, it opens the configuration file and parses its contents, creating an internal representation of the menu. It then saves all menu files at the same location as the corresponding menu item, rendering the menus as they are saved.

The menu configuration file

The menu configuration file is a text file where each meny item is written on a line by itself. The file may contain any number of lines, but only lines conforming to the following construct are recognised as menu item lines:
<level>
Zero or more plusses ("+"). Determines which level the menu item has, where no plusses is the highest level. Thus, an item with one plus is on a higher level than an item with more than one plus. Restriction: There may only be one more plus on an immediate following menu item, i.e you may only increase levels one step at a time, but you can decrease any number of levels at once.
<menu text>
The menu text must be enclosed by double quotes and may not have double quotes in it. The text is what is displayed in the menu, and is the clickable link. If this is a separator item (see below), the menu text is the HTML code to use as a separator, e.g "<hr>". This might not be true depending on how the update_menu.pl program is internally configured.
<menu item type and path>
There are three different meny item types; relative links, absolute links and separators. All relative links are relative to the top directory of the web structure, and a menu file will be written at the same location as the file. The menu file has the same name as the referring file, with the suffix ".menu" added. An absolute link begins with either "http:", "file:", "ftp:" or "gopher:". No menu file will be written for this item. The last item type is a separator and is inserted using a dash ("-"). The menu text is the HTML-code describing how the separator is rendered.

Example of a configuration file

Here we can see that the item "Organisation" has three sub menues, the item "Documents" has one sub menu which in turn has two sub menues. There are two absolute links, starting with "http:" and there is one separator line, right above the "Erisoft Home Page" entry.

Note that all relative links have their entire path from the top web directory specified.

Stop! This is how far you have to read to be able to add pages to the menu. The rest of the document describes where to put the HTML code which renderes the menu items. There is however a complete example at the end of this document, "Example".


Changing the menu layout

The layout of the menu is statically specified in the executable file itself through options. Any option can be overridden by the configuration file by writing "<option>=<value>" on a line by itself. This is a description of how the options relate to the rendering of the above menu when the second menu item is active (configurable options are written in bold face):
Header
 
Default 
Polaris Main Page
 
DefaultActive 
Organisation 
     
    1 
    Design team
    1 
    Quality team
    1 
    Polaris Main Project
     
 
Default 
Documents
 
DefaultSeparator 

 
Default 
Erisoft Home Page
 
Footer
 

Option descriptions

Remember that all of these options are specified on an option line in the menu configuration file as "option = value". Some options related to the rendering of the menu can be located in the above menu layout.

Options related to the function of the program

These are the options related to the rendering of the menu: This is of course not all. There are special tags which can be used in all of the above options except "Header" and "Footer".

Example

Here is a complete example of a menu configuration file
top_dir = /home/polaris/public/www/www2
Header = <ul>
Footer = </ul>
 
Default = <li><a href="%h">%n</a><ul>%m</ul></li>
DefaultActive = <p><li><font color="#ff0000"><em>%n</em></font><ul>%m</ul><p></li>
DefaultOuter = <li><a href="%h">%n</a><ul>%m</ul></li><p>
DefaultSeparator = %n
 
 
"Polaris ML main page":index.shtml
+"Revision History":revision-information.shtml
"Organisation":organisation/index.shtml
+"Prestudy":organisation/prestudy.shtml
+"Feasibility":organisation/feasibility.shtml
"General Information":general_info/index.shtml
+"CM":cm/index.shtml
+"Q":q/index.shtml
"<hr>":-
"Methods, Tools & Training":methods/index.shtml
+"Templates":methods/templates.shtml
"Configuration Managment":cm/index.shtml
+"Configuration Control Board":cm/ccb_v52ml.html
+"Revision Information":cm/revision.shtml
+"V5.2 ML CR Tool":http://greed.xt.etx.ericsson.se/xt/ChangeRequestII/index.html
+"cvs information":cm/cvsinfo.shtml
"Quality Managment":q/index.shtml
"<hr>":-
"Steering Documents":steering_docs/index.shtml
"Product Documents":prod_docs/index.shtml
+"Requirement Specification":prod_docs/rs.shtml
+"IS":prod_docs/is.shtml
+"Implementation Proposals":prod_docs/ip.shtml
"Other Documents":other_docs/index.shtml
+"Reports":other_docs/reports.shtml
+"Administration Documents":other_docs/admin_docs.shtml
"<hr>":-
"Internal Information":http://www.um.erisoft.se/~polaris/