 |
EPL/X/AX
Polaris |
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:
-
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".
-
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.
-
You must include the menu file in your page.
Running the program
The command line to the program is:
update_menu.pl [-u] <menu configuration file>
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:
<!--#include file="<filename>.menu"-->
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>"<menu text>":<menu item type and path>
-
<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
"Polaris Main Page":index.shtml
"Organisation":organisation/index.shtml
+"Design Team":organisation/design.shtml
+"Quality Team":organisation/quality.shtml
+"Polaris main project":http://www.ericsson.se/~polaris/organistion/
"Documents":docs/index.shtml
+"IP":docs/ip/index.shtml
++"First rev":docs/ip/first.shtml
++"Second rev":docs/ip/second.shtml
"<hr>":-
"Erisoft Home Page":http://www.epl.ericsson.se/
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):
|
|
Default
Polaris Main Page |
|
DefaultActive
Organisation
1
Design team |
1
Quality team |
1
Polaris Main Project |
|
|
|
|
|
|
Default
Erisoft Home Page |
|
|
|
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
-
top_dir
-
The root directory of the www structure. All links in the menu configuration
file are specified relative to this directory.
-
menu_file
-
The menu configuration file. This option is ignored if present in the configuration
file.
These are the options related to the rendering of the menu:
-
Header
-
Written before any item in the menu is rendered.
-
Footer
-
Written after all menu items have been rendered.
-
Default
-
Default rendering of any inactive menu item. Overridden by a level number,
as below.
-
DefaultActive
-
Default rendering of active menu items. Overridden by a level number, as
below.
-
DefaultOuter
-
Default rendering of items containing an active menu, e.g used for rendering
a level 1 item which contains an active level 2 (or higher) item. Overridden
by a level number, as below.
-
DefaultSeparator
-
Default rendering of the separators. Overridden by a level number, as below.
-
n
-
Rendering of a menu at specified level number n, where zero is the
outermost menu. Overrides "Default".
-
nActive
-
Rendering of active menus at specified level. Overrides "DefaultActive".
-
nOuter
-
Rendering of a menu item at specified level which contains an active menu.
Overrides "DefaultOuter".
-
nSeparator
-
Rendering of a separator at the specified level. Overrides "DefaultSeparator".
This is of course not all. There are special tags which can be used in
all of the above options except "Header" and "Footer".
-
%h
-
Replaced with the html reference at the end of the line in the configuration
file.
-
%n
-
Replaced with the menu item text string (the one inclosed in double quotes).
-
%m
-
Replaced with the rendered submenu if the active item is somewhere in it.
-
%R
-
Any path prefixed by %R and enclosed in double quotes is relativized compared
to the value of %n, if %n is relative. This is useful when you would like
a picture in the menu item and the picture is residing in a common directory
(often at the top of the web structure). The path should be written relative
to the top directory of the structure.
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/