show_menu2, version 4.9
=======================
A code snippet for the Website Baker CMS software. It provides a complete
replacement for the builtin menu functions. All menu data is retrieved using
a single database query, all types of menu styles (lists, breadcrums, sitemaps)
can be generated with extensive customisation of the resulting HTML.
INSTALLATION
============
1. Download the latest version from http://code.jellycan.com/show_menu2/
2. Log into your WebsiteBaker installation
3. Go to Addons -> Modules
4. If a previous version of show_menu2 is already installed, select it from
the "Uninstall Module" list and choose the "Uninstall" button.
5. In the "Install Module" section, enter the path to the show_menu2 zip file
that you downloaded in step 1, and choose the "Install" button.
USING SHOW_MENU2
================
You need to modify the PHP files of your template to call show_menu2 where you
wish to have the menu displayed. Remember when you replace calls to the old
menu functions to use the new parameters that show_menu2 requires.
Often times the default menu generated by show_menu2 is all that you need.
This menu shows the current page and children of the current page. It is
generated by just calling show_menu2 with no parameters. For example:
show_menu2();
Note that the call to show_menu2 is PHP, so you usually need to wrap it in the
PHP code brackets so that it will execute. Like this:
This default menu generates a complete list based menu with many classes that
allow easy CSS styling. For example, the current menu item will have the
"menu-current" class added to the tag. Additionally, every menu item with
a sub-menu will have the "menu-expand" class added to the tag. This allows
you to create CSS rules to style those menu items differently. For example:
li.menu-expand { font-weight: bold; }
li.menu-current { background: red; }
See the "Output" section for details of exactly what classes are added to each
element. More elaborate and different menu structures are able to be created by
supplying different parameters to the show_menu2 function call. For example,
to show only menu items from the top level of the menu you use:
show_menu2(0, SM2_ROOT, SM2_START);
Alternatively, to show up to two levels of the child menus of the current page:
show_menu2(0, SM2_CURR+1, SM2_CURR+2);
There are many more possible menus that can be generated by show_menu2. See the
demonstration website at http://code.jellycan.com/sm2test/ for more examples.
COMMON QUESTIONS
================
Q: I'm not a programmer. Do you have simpler documentation?
A: Nup. This is it. Go hard. Gambarre.
Q: How do I create a drop-down menu?
A: This is unrelated to show_menu2. You need to change the template CSS code
to display the menu as a drop-down. Try the "allcss2" template from the WB
addon repository. http://addons.websitebaker.org/pages/templates.php
Q: Why does the menu disappear after I do a search on my multilingual WB site?
A: You're missing some required lines in your template.
1. Log into WB administration, and go to Settings -> Show advanced settings
-> Search Settings -> Header Code and add the following input field
after the '.
$aMenuOpen
Format string to use for opening a list of menu item entries. A
different format string may be used for the very first menu by
supplying a different format string for $aTopMenuOpen. When set to
false, it uses the default of '[ul]'.
$aMenuClose
String used to close each menu. Note that this is not a format
string and no keywords will be replaced. When set to false, it uses
the default of ''.
$aTopItemOpen
Format string for the first item. When set to false, it uses the same
format as $aItemOpen.
$aTopMenuOpen
Format string for the first menu. When set to false, it uses the same
format as $aMenuOpen.
EXTENDED OPTIONS
================
The $aOptions parameter is a dual mode parameter. For most users, only the
SM2_* flags will be sufficient. However, to access the extra options, it
must be supplied as an associative array. Note that the SM2_* flags are
still required and must be supplied as 'flags'.
'flags' **REQUIRED** These are the flags described in PARAMETERS
above for the $aOptions parameter.
'notrim' Specify a number of levels relative to the menu level of
$aStart that will always be displayed. This will cause the
SM2_TRIM flag to be ignored for these levels.
To supply one of these options in addition to the flags, the option array
should be created and passed as the $aOptions parameter:
$options = array('flags' => (SM2_TRIM|...), 'notrim' => 1);
show_menu2(0, SM2_ROOT, SM2_CURR+1, $options);
FORMAT STRINGS
==============
The following tags may be included in the format strings for $aItemOpen and
$aMenuOpen and will be replaced with the appropriate text.
[a] tag (no class): ''
[ac] tag including class: ''
[li] tag including class: ''
[ul] tag including class: ''
[class] List of classes for that page
[menu_title] Menu title text (HTML entity escaped unless SM2_NOESCAPE flag is used)
[page_title] Page title text (HTML entity escaped unless SM2_NOESCAPE flag is used)
[url] Page URL for the tag
[target] Page target for the tag
[page_id] Page ID of the current menu item
[parent] Page ID of the parent menu item
[level] Page level, the same number as is used for the "menu-N" CSS tag.
[sib] Current menu sibling number
[sibCount] Total number of siblings in this menu
[if] Conditional test (see section CONDITIONAL FORMATTING)
The following tags are only available when the SM2_ALLINFO flag is used.
[description] Page description
[keywords] Page keywords
CONDITIONAL FORMATTING
======================
The conditional formatting directive takes one of the following forms:
[if(A){B}]
[if(A){B}else{C}]
A Conditional test. See below for more details.
B Expression emitted when the if-test is true. This may be any string
that does NOT include the '}' character. It may include any of the
format strings described in the section FORMAT STRINGS with the
exception of the conditional test (because '}' is not permitted).
C Expression emitted when the if-test is false. This may be any string
that does NOT include the '}' character. It may include any of the
format strings described in the section FORMAT STRINGS with the
exception of the conditional test (because '}' is not permitted).
The conditional test is a combination of one or more boolean tests.
If more than one test is supplied, it must be combined with other tests
using either || (boolean OR) or && (boolean AND).
A single test is made up of the left operand, operator and right operand.
e.g. X == Y where X is the left operand, == is the operator and Y is the
right operand.
Left operand. It must be one of the following keywords:
class Test for existence of one of the classes. Only the
"==" and "!=" operators are permitted. In this case
these operators have the meaning of "includes"
instead of "equals".
level Test against the page level.
sib Test against the current page sibling number.
sibCount Test against the number of siblings in the menu.
id Test against the page id.
Operator. It must be one of the following:
< Less Than
<= Less Than Equals
== Equals
!= Not Equal
>= Greater Than Equals
> Greater Than
Right operand. The type of this operand depends on the keyword used
for the left operand:
class One of the "menu-*" class names as listed in the
section "OUTPUT".
level Test the page level against the following values:
absolute page level
root the root page level
granny the grand-parent page level
parent the parent page level
current the current page level
child the child page level
id Test the page id against the following values:
absolute page id
parent the parent page id
current the current page id
sib A positive integer, or "sibCount" to test against
the count of siblings in this menu.
sibCount A positive integer.
For example, valid tests are expression "exp" is emitted only when the menu item:
[if(class==menu-expand){exp}] has a sub-menu
[if(class==menu-first){exp}] is first item in a menu
[if(class!=menu-first){exp}] is NOT first item in a menu
[if(class==menu-last){exp}] is last item in a menu
[if(level==0){exp}] is at the root
[if(level>0){exp}] is not at the root
[if(sib==2){exp}] is the second item in a menu
[if(sibCount>1){exp}] is in a menu with more than 1 entry
[if(sibCount!=2){exp}] is in a menu which doesn't have exactly
[if(level>parent){exp}] is in a sibling menu or child of a sibling
[if(id==parent){exp}] is the parent of the current page
If an else-clause was added, then the expression for the else would be
emitted in all other cases. For example the expression "foo" is emitted
whenever the if-test is false, so therefore:
[if(sib==2){exp}else{foo}] is NOT the second item in a menu
[if(sibCount>2){exp}else{foo}] is NOT in a menu with more than 2 entries
For multiple tests, the expression "exp" is emitted only when the menu item:
[if(sib == 1 || sib > 3){exp}]
[is the first item] OR [is the 4th or larger item] in the menu
[if(id == current && class == menu-expand){exp}
[is the current item] AND [it has children]
Note that all tests are evaluated in the order listed because:
* there is no short-circuit evaluation (all individual tests are always evaluated)
* there is no grouping of tests (i.e. no support for parenthesis)
* both || and && are considered the same level
FORMATTER
=========
Note: This is an advanced and rarely needed feature!
If you are capable of extensive PHP programming, it is possible to replace the
predefined menu formatter that show_menu2 is uses with a custom module. See the
include.php file of show_menu2 for an example of how the menu formatter must be
written. The API it must use is:
class SM2_Formatter
{
// called once before any menu is processed to allow object initialization
function initialize() { }
// called to open the menu list
function startList($aPage, $aUrl) { }
// called to open the menu item
function startItem($aPage, $aUrl, $aCurrSib, $aSibCount) { }
// called to close the menu item
function finishItem() { }
// called to close the menu list
function finishList() { }
// called once after all menu has been processed to allow object finalization
function finalize() { }
// called once after finalize() if the SM2_NOOUTPUT flag is used
function getOutput() { }
};