Menu files
From phpCMS
Contents |
[edit] Using menu files
Especially in rather large web projects it is very helpful to use a system for creation of menus. Manual editing of all HTML files of such a project to change just one menu item often will cost hours of work. phpCMS therefore supplies a mature and flexible system to generate menus automatically and thus dynamically.
[edit] Basic Information
The menu system of phpCMS is controlled by two files. The menu file holds the contents of the menus and the layout file describes the visual layouts of the menu levels. Contents and layout are separated consistently, like it is also seen for the page contents and page template files. This will make it possible to change the menu entries quickly as well as the layout itself.
The contents file defines the menu items of the main menus and all submenus. Theoretically an arbitrary number of menu levels is possible. No more than three levels should be used to abide usability for the user. The contents file also defines how menu items and submenus are associated. The submenus will normally be displayed first when the menu entry above is activated. See the parameter PARENTCLASS below or the sitemap feature (How to create a site map) for ways to display all required submenus.
The layout file defines how the menu levels are displayed. Normally you will use the level name from the contents file as layout name and special designations for the parts of the menus. Names of fields defined in the menu file are used as place holders in HTML statements in the layout.
[edit] Construction of a Menu File
On our demo site we use the file extension .mnu and so we will do in this document, but, normally, you may use another extension as well.
A menu file is a list of all menus, their menu items and the contents files that are associated to the menu items. The lists are extended by special entries. No comments are allowed in a menu file! Empty lines, as well as tabs and spaces on begin and end of a string and multiple occurrences of them are ignored, so you may format the entries like you prefer.
The menu file will be processed by the parser from top to bottom. That means that the entries should be sorted in the same sequence in which they will be displayed.
The semicolon normally has the meaning of a separator. This separator character may be globally set, so also other characters are possible. All of the following examples assume that the separator has not been changed globally.
There is a second possibility to change the separator temporarily. For this it is sufficient to place DELIMITER: followed by the separator to be used from here on in the menu file on an own input line. This line may be used several times so you may switch back to another character or back to the semicolon.
[edit] Structure of a Menu File
A menu file consists of several blocks of lines each defining a menu. Every definition of a menu consists of a menu level line, a field definition line and several lines with the menu items.
Example:
MENU: MAIN CLASS; LINK; MNAME 00.01; /demo/index.htm; Homepage 00.02; /demo/page1.htm; Page 1 00.03; /demo/page2.htm; Page 2
The menu class line consists of the keyword MENU: followed by the name of the menu level. As a default the menu level name is also used as name of the menu template to be used in the layout file.
The next line consists of a list of fieldnames that are separated by a delimiter, normally a semicolon. The fieldnames describe the meaning of the values given for each menu item in the next lines. The fieldnames will also be used as place holders for the values in the menu template. In principle an arbitrary number of fields may be defined.
All following lines of a block describe menu items by giving values for the fields. The values are also separated by the delimiter.
A menu block ends with the start of a new menu block (the next MENU:-line) or at the end of the file.
The two fieldnames CLASS and LINK must always be given.
The field CLASS contains the menu number. A menu number always starts with 0. Points will signal that the next number constitutes a submenu. Possibly the numbers have to be written with leading zeros, because the parser does not sort numerically but alphabetically.
The other essential field LINK contains path and filename of the contents file that belongs to the menu item. You may use the variable $home here if it is defined in the project file.
[edit] Examples of Menu Files
First we will create a very simple menu file, where only a main menu exists without any submenus. We here will call the main level MAIN. There will also be a field NAME containing the displayed name of the menu entry beneath the mandatory fields CLASS and LINK.
MENU: MAIN CLASS; LINK; MNAME 00.01; /demo/index.htm; Homepage 00.02; /demo/page1.htm; Page 1 00.03; /demo/page2.htm; Page 2
Next we create a submenu for Page 1. For that purpose we repeat the menu number that is written in the line of Page 1 and extend it by a dot and an additional number. We will call the new menu level SUB
MENU: SUB CLASS; LINK; MNAME 00.02.01; /demo/page1_1.htm; Page 1.1 00.02.02; /demo/page1_2.htm; Page 1.2
In this step we now add another submenu for Page 2. We will name the level of this new submenu also as SUB, because it is on the same level. This also means that the same menu template will be used.
You always have to be careful to define a complete "definition header". It would be totally wrong to insert menu number 00.03.01 after the definition of 00.02.02. To make this clear, we will repeat the formerly created block again.
To illustrate the use of the DELIMITER we will use another delimiter because we want to insert the special character > (>) containing a semicolon into the menu name. The DELIMITER can be set in any line and will remain valid for all subsequent lines.
MENU: SUB CLASS; LINK; MNAME 00.02.01; /demo/page1_1.htm; Page 1.1 00.02.02; /demo/page1_2.htm; Page 1.2 DELIMITER: | MENU: SUB CLASS| LINK| MNAME 00.03.01| /demo/page2_1.htm| Page > 2.1 00.03.02| /demo/page2_2.htm| Page > 2.2
Now we will create another submenu for the submenu with the menu number 00.03.02 and give this new lmenu level the name SUB2. To this menu we will add an additional field named PICTURE. It holds the name of a graphic file that contains a graphical representation of the menu item. This filename will be used as image source for the menu item in the template. We easily may create graphical menus using such a construct.
DELIMITER: ; MENU: SUB2 CLASS; LINK; MNAME; PICTURE 00.03.02.01; /demo/page2_2_1.htm; Page 2.2.1; 2_2_1.png 00.03.02.02; /demo/page2_2_2.htm; Page 2.2.2; 2_2_2.png
[edit] Connect a Content File
You can connect a content file in two ways to a menu item. The first (and older) way is to have a menu number (CLASS) after the {MENU} parameter in the content file. This is the only way to connect a content file to more than one menu item. Disadvantage of this method is that you have to edit two files, content file and menu file, in order to connect a content file to a menu item.
The other method is to omit the menu number in the content file. phpCMS then finds the correct menu number automatically. It compares the path found in the menu file to the path of the content file found (relative to the document root). If they match, this menu number is used for all subsequent accesses. Advantage of this method is that you only have to edit one file when switching a content file to a different menu item.
If you give a menu number, then it will be used.
[edit] Examples for linking of Content Files
For this topic it is not possible to make good examples, but we will try to show some used cases. In the first case we will give a menu number. This number is identical to the number in the above list. The file should get the name page2_2_1.htm.
{PROJECT} template/home.ini
{MENU} 00.03.02.01
...
We will remove the menu number from the content file in the second example, but phpCMS will still find the correct entry in the menu file.
{PROJECT} template/home.ini
...
In the last case we assign another number in the content file than in the menu. Now phpCMS will use the number from the content file instead of the computed one. This leads to marking another entry than the one that has been selected.
{PROJECT} template/home.ini
{MENU} 00.03.02
...
[edit] Including Menus within Templates
It may seem strange, if we explain first, how and where you can include a menu for displaying. But this gives us the possibility better to show following examples.
You can call a menu to be displayed in every template file, including even the menu template itself. Including in the menu template offers further possibilities, i.e. you can create "nested" menus. To show a menu at a specific place within the template, you only need to call:
{MENU NAME="Menuname"}
Therefore Menuname has to be replaced by an existing menu name. Furthermore phpCMS provides the opportunity to use some other menu template than the one defined by NAME for displaying the menu. This enables to show two layout differing menus but with the same content on one page. This doesn't need to be a menu name which has been used in the menu file. It can also be a further name - there only has to be a definition within the menu template.
{MENU NAME="Menuname" MENTEMP="otherMenuname"}
If the Menuname is set to CURRENT, phpCMS grants access to the currently active menu layer. This is always the element which has the same CLASS as the file currently processed. If you use CURRENT you always have to define otherMenuname to make all menu layers using the same template.
