Menu template files

From phpCMS

Jump to: navigation, search

Contents

[edit] Using menu templates

[edit] Structure of a Menu Template

One important file within the project's menu system is the menu template. In this file the layout of the menus is defined. The file suffix can also be chosen arbitrarily, but .mtpl is mostly used.

Different from the menu file you can use comments in the template. These are prefaced with a semicolon. Comments only will be recognized as those if they are placed at the beginning of a line. Additionally, Whitespaces and Tabs are ignored. All the menu layouts of one project are combined in this file.

A menu layout can contain six different layout blocks, whose responsibility can be recognized from their names. To define a layout block for one menu name you need to enter the menu-name, followed by a dot and then a keyword for the definition block - all surrounded by the phpCMS delimiters. The keywords have to be written in uppercase.

general format: {menu-name.keyword}

The meanings of the keywords are:

PRE 
This keyword instructs the parser to place the following code before the remaining menu code.
For example you could define a table or an <ul> here.
NORMAL 
The code defined by this keyword is used if a menu entry is inactive, which means is in normal case.
For example there could be table cells or a <li> defined.
ACTIVE 
With an active entry or active subentry this defined code instead of the normal case is used.
For example there could be a <li class="active">.
SELF 
This code is used, if the active entry is the content file which is currently processed. Thus you are able to emphasize the current entry more than the possible above entries.
For example there could be a <li class="self">.
IMPORTANT: If this keyword isn't defined, the ACTIVE code is used.
BETWEEN 
(since Version 1.2.1) This code will be displayed between the single menu entries.
PAST 
The code defined by this keyword will be displayed after the entire menu code.
For example you can enter the closing tags for a table or the closing </ul> here.

Within the code blocks defined above you can also use the field names which are defined in the menu file below the according menuname. Of course this isn't possible in PRE and PAST, as these are used for the entire menu and not only for one single entry like the other keywords. example: <li><a href="{LINK}">{MNAME}</a></li>

[edit] Examples Of Menu Templates

The following examples aren't illustrating all the opportunities of phpCMS yet. phpCMS is a huge flexible system, so it's not possible to make examples for each feature.


[edit] Basic sample

Firstly we will create a template for the menu names MAIN and SUB. These will be knowingly very simple to show the general structure more easily. The structure of the menu is meant to be that the main menu entries shall be displayed one below the other and the sub menu entries side by side at another place. To include this kind of menu in the template you need to call the menu at two places.

; MAIN - vertical menu by unordered list (this line is a comment)
;
{MAIN.PRE}
<ul>
{MAIN.NORMAL}
<li><a href="{LINK}">{MNAME}</a></li>
{MAIN.ACTIVE}
<li><strong><a href="{LINK}">{MNAME}</a><strong></li>
{MAIN.SELF}
<li><strong><em><a href="{LINK}">{MNAME}</a></em></strong></li>
{MAIN.PAST}
</ul>

; SUB - horizontal menu separated by vertical lines
;
{SUB.PRE}
|
{SUB.NORMAL}
<a href="{LINK}">{MNAME}</a> | 
{SUB.ACTIVE}
<strong><a href="{LINK}">{MNAME}</a></strong> | 
{SUB.SELF}
<strong><em><a href="{LINK}">{MNAME}</a></em></strong> | 
{SUB.PAST}

The above code already creates a very simple menu. This doesn't look very nice yet, but we'll only demonstrate the possibilities of phpCMS.


[edit] Picture instead of text

In the next step we'll also create a menu template for SUB2 where a picture will be displayed instead of text.

{SUB2.PRE}
::
{SUB2.NORMAL}
<a href="{LINK}"><img src="{PICTURE}" alt="{MNAME}"></a> :: 
{SUB2.ACTIVE}
<img src="pfeil.png" alt="->"><a href="{LINK}"><img src="{PICTURE}" alt="{MNAME}"></a></b> :: 
{SUB2.PAST}

The example above looks fine, but it doesn't show yet all the incredible possibilities phpCMS provides for menus.


[edit] Cascading menu

For this reason the following example will outline a function used on many websites: cascading menus. The intention is, that a submenu expands only when the top entry has been activated. We take the same menu file as before as base.

{MAIN.PRE}
<ul>
{MAIN.NORMAL}
<li><a href="{LINK}">{MNAME}</a></li>
{MAIN.ACTIVE}
<li><strong><a href="{LINK}">{MNAME}</a></strong>
{MENU NAME="SUB"}
</li>
{MAIN.PAST}
</ul>

{SUB.PRE}
<ul>
{SUB.NORMAL}
<li><a href="{LINK}">{MNAME}</a></li>
{SUB.ACTIVE}
<li><strong><a href="{LINK}">{MNAME}</a></strong>
{MENU NAME="SUB2"}
</li>
{SUB.PAST}
</ul>

{SUB2.PRE}
<ul>
{SUB2.NORMAL}
<li><a href="{LINK}">{MNAME}</a></li>
{SUB2.ACTIVE}
<li><strong><a href="{LINK}">{MNAME}</a></strong>
</li>
{SUB2.PAST}
</ul>

When using this definition you only need to include the menu MAIN in the template file (main or sub template). The actual trick is, that the ACTIVE definition creates a new call for the sub menu. This makes the menu cascading. You could also use the PICTURE field from SUB2, but we didn't do this to keep it simple. The same applies to the keyword SELF which can be used also.


[edit] Pseudo menu CURRENT

To demonstrate the usage of the pseudo menu CURRENT we assume, that the menus of the website are sorted by categories in some way. With this pseudo menu we'll create a list which is shown on every page and doesn't contain the currently active link. Therefore we define a new menu template with the name CAT.

{CAT.PRE}
more links: 
{CAT.NORMAL}
<a href="{LINK}">{MNAME}</a>
{CAT.ACTIVE}


[edit] Special parameters

[edit] PARENTCLASS

Since phpCMS Version 1.2.0 a new menu parameter has been implemented: PARENTCLASS. If you use a version prior to 1.2.0, you may have a look at this forum topic to read how it can be integrated manually.

So what's the new parameter PARENTCLASS needed for?

Assumed you are using cascading menus like the above mentioned example, phpCMS will only expand the current active submenu. All other submenus won't be displayed. Ok, now you might think to make a menu template like the following:

{MAIN.PRE}
...
{MAIN.NORMAL}
 ....
{MENU NAME="SUB1"}
{MAIN.ACTIVE}
 ....
{MENU NAME="SUB1"}
{MAIN.PAST}
 ....
{SUB1.PRE}
 ....

But this won't work because the parser will always show the active submenu and not the actual submenus belonging to the according main menu entries.

So if you want to make all submenus to be displayed, use the parameter PARENTCLASS. With this additional parameter you can instruct phpCMS not to choose the submenu suiting the menu class of the current content file, but to choose a different menu class.

For example, make a menu template like this:

{MAIN.PRE}
 ....
{MAIN.NORMAL}
 ....
{MENU NAME="SUB1" PARENTCLASS="{CLASS}"}
{MAIN.ACTIVE}
 ....
{MENU NAME="SUB1"}
{MAIN.PAST}
 ....
{SUB1.PRE}
 ....

Then phpCMS first replaces the {CLASS} in the parameter by the menu class of the currently processed menu entry. Afterwards the submenu is called and the parser now knows to choose a different submenu. (Please note: PARENTCLASS does not work, when inserted in the content template file, it must be used in the menu template file.)

[edit] IFNOTEMPTY

To avoid empty lines in cascading menus this parameter IFNOTEMPTY was implemented. Just add it to the included submenu.

{MAIN.PRE}
<ul>
{MAIN.NORMAL}
<li><a href="{LINK}">{MNAME}</a></li>
{MAIN.ACTIVE}
<li><strong><a href="{LINK}">{MNAME}</a></strong>
{MENU NAME="SUB" IFNOTEMPTY}
</li>
{MAIN.PAST}
</ul>

[edit] Synopsis

These examples should be enough to explore further menu possibilities. The above mentioned examples will satisfy most users. But feel free to play around with them and add some more!


Main Page: User Documentation MainPage
« Previous Page: How to work with tag files | Top Page: How to work with phpCMS | Next Page: How to create a site map »

Personal tools