WB 2.08.x

show_menu2, version 4.9

replacement for the builtin menu functions. All menu data is retrieved using

a single database query, all types of menu styles (lists, breadcrums, sitemaps)

============

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.

================

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();

PHP code brackets so that it will execute. Like this:

    <?php show_menu2(); ?>

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 <li> tag. Additionally, every menu item with

    li.menu-expand  { font-weight: bold; }

    li.menu-current { background: red; }

element. More elaborate and different menu structures are able to be created by

supplying different parameters to the show_menu2 function call. For example,

    show_menu2(0, SM2_ROOT, SM2_START);

    show_menu2(0, SM2_CURR+1, SM2_CURR+2);

There are many more possible menus that can be generated by show_menu2. See the

COMMON QUESTIONS

================

Q:  How do I create a drop-down menu?

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.

        -> Search Settings -> Header Code and add the following input field

        after the <form> open tag:

        <input type="hidden" name="referrer" value="[REFERRER_ID]" />

        <input type="hidden" name="referrer" value="<?php echo defined('REFERRER_ID')?REFERRER_ID:PAGE_ID;?>" />

Q:  Multilingual? That sounds cool. How do I do that?

Q:  SM2 is generating a warning every time the page is accessed:

    "show_menu2 error: $aOptions is invalid. No flags from group 1 supplied!"

    parameters that you are passing. See the PARAMETERS section below for the

    to do whatever you want.

        Reference this in your CSS like:

        Reference this in your CSS like:

========

The complete call signature and default parameter value for show_menu2 is:

    show_menu2(

        $aMenu          = 0,

        $aStart         = SM2_ROOT,

        $aMaxLevel      = SM2_CURR+1,

        $aItemClose     = '</li>',

        $aMenuOpen      = '[ul]',

        $aMenuClose     = '</ul>',

        $aTopItemOpen   = false,

        $aTopMenuOpen   = false

        )

See the "Parameters" section for detailed descriptions of each parameter.

    $aOptions must be only values that start with "SM2_" (unless you are

    All other parameters are the HTML tag templates that will be

Note that every parameter from $aItemOpen can be supplied as false to get

===========

supplied to the function, however in general the following classes are used

    CLASS           ATTACHED TO

    ------------    -------------------------------------------------------

    menu-top        First menu tag only

    menu-parent     Every parent menu item of the current page.

    menu-current    Only the menu item for the current page.

    menu-sibling    Every sibling of the current page.

    menu-child      Every sub-menu of the current page.

    menu-expand     Every menu item with children.

    menu-first      First item in any menu or sub-menu.

    menu-last       Last item in any menu or sub-menu.

    The following classes are added only if SM2_NUMCLASS flag has been used.

                    menu depth of the item starting with 0. The root level

<ul class="menu-top menu-0">

  <li class="menu-0 menu-first">  ... </li>

  <li class="menu-0 menu-expand menu-parent">  ...

  <ul class="menu-1">

    <li class="menu-1 menu-expand menu-first">  ...

    <ul class="menu-2">

      <li class="menu-2 menu-first">  ...

      <li class="menu-2 menu-last">  ...

    </ul>

    </li>

    <li class="menu-1 menu-expand menu-parent">  ...

    <ul class="menu-2">

      <li class="menu-2 menu-expand menu-current menu-first">  ...      ** CURRENT PAGE **

      <ul class="menu-3">

        <li class="menu-3 menu-child menu-child-0 menu-first">  ...

        <ul class="menu-4">

          <li class="menu-4 menu-child menu-child-1 menu-first">  ... </li>

          <li class="menu-4 menu-child menu-child-1 menu-last">  ... </li>

        </ul>

        </li>

        <li class="menu-3 menu-child menu-child-0 menu-last">  ... </li>

      </ul>

      </li>

      <li class="menu-2 menu-sibling menu-last">  ... </li>

    </ul>

    </li>

    <li class="menu-1">  ... </li>

    <li class="menu-1 menu-expand menu-last">  ...

    <ul class="menu-2">

      <li class="menu-2 menu-first menu-last">  ... </li>

    </ul>

    </li>

  </ul>

  </li>

  <li class="menu-0 menu-last">  ... </li>

</ul>

PARAMETERS

==========

    Menu number to use. This is useful when you are using multiple menus.

    Supplying a menu number of 0 will use the default menu for the current

        SM2_ROOT+N  Start N levels down from the root. e.g.

                      SM2_ROOT+2    Start 2 levels below the root

        SM2_CURR+N  Start N levels down from the current page level. e.g.

                      SM2_CURR      Starts at the current page level. All

                                    sibling menus to the current page.

                      SM2_CURR+1    Starts 1 level down from the current

                                    page with the children menus.

        page_id     Display using the specific page as the parent. All

                    page_id can be found by editing the page in WB admin

                    interface. The page_id is included in the URL like:

    level down to this level.

        SM2_ALL     No limit, all levels are displayed

                      SM2_CURR+3    All parents + current + 3 children

        SM2_START+N Always show from the starting level + N levels. The

                    levels of menu will always be displayed regardless of

                    what level the current page is.

                      SM2_START     Single level of menus from starting level

                      SM2_START+1   Starting level and 1 level down

                      SM2_MAX       Starting level only (same as SM2_START)

                      SM2_MAX+1     Maximum of starting level and 1 level.

    may be combined together using bitwise OR (|). For example, to specify

    GROUP 1

    -------

    affect how the siblings in the tree are removed from the output.

    SM2_ALL         Show all branches of the menu tree

                                   -> C-2 (CURRENT)

                                          -> D-1

                                          -> D-2

                                   -> C-3

                        A-2 -> B-3

                            -> B-4

                    All sub-menus of elements that are not on the path

                                   -> C-2 (CURRENT)

                                          -> D-1

                                          -> D-2

                                   -> C-3

                    menu and all of it's ancestor menus.

                        A-1 -> B-2 -> C-2 (CURRENT)

                    the current page are displayed. All other menus are

                        A-1 -> B-2 -> C-1

                                   -> C-2 (CURRENT)

                                          -> D-1

                                          -> D-2

                                   -> C-3

    GROUP 2

    -------

    All of these flags are optional. Any number of them may be combined.

                    flag is supplied, the "menu-N" and "menu-child-N"

                    This will result in quite a lot of memory being used

                    and is not recommended, however it will make keywords,

                    descriptions, and other fields available. This data

                    is not loaded by default.

                    NOTE: This flag must be used on the *FIRST* call to

                    show_menu2 *for this menu ID*, or in combination with

                    SM2_NOCACHE otherwise it will have no effect.

                    for debugging purposes.

    SM2_BUFFER      Do not output the menu HTML but instead buffer it

    SM2_CURRTREE    Exclude all other top level menus from being considered.

                    This can be combined with any of the Group 1 flags as

                    necessary.

                    required with older installations of WB. By escaping the

    SM2_SHOWHIDDEN  Hidden pages are usually hidden all of the time, including

                    Use private pages for time when you want pages to be

                    hidden except when active. However for compatibility with

                    release 4.8, supply this flag to enable hidden pages to

                    become visible when they are active.

					attribute will be removed to preserve the XHTML-Compatibility

	SM2_NO_TITLE	Supress the value of the 'title'-attributes on links which

					are created by [a] or [ac] formatted links.

    options is supplied. See the EXTENDED OPTIONS section for details.

$aItemOpen

    Format string to use for creating each individual menu item entry.

    supplying a different format string for $aTopItemOpen. When set to

    compatibility with show_menu(). Note however that CSS formatting is

    often easier if the classes are added to the <a> tag. Use the format

    string of '<li>[ac][menu_title]</a>' for this style of tag.

$aItemClose

    String used to close each item. Note that this is not a format

$aMenuOpen

    different format string may be used for the very first menu by

    supplying a different format string for $aTopMenuOpen. When set to

$aMenuClose

    String used to close each menu. Note that this is not a format

$aTopItemOpen

    Format string for the first menu. When set to false, it uses the same

EXTENDED OPTIONS

================

The $aOptions parameter is a dual mode parameter. For most users, only the

still required and must be supplied as 'flags'.

    'flags'     **REQUIRED** These are the flags described in PARAMETERS

                SM2_TRIM flag to be ignored for these levels.

To supply one of these options in addition to the flags, the option array

    $options = array('flags' => (SM2_TRIM|...), 'notrim' => 1);

    show_menu2(0, SM2_ROOT, SM2_CURR+1, $options);

==============

[a]             <a> tag (no class):         '<a href="[url]" target="[target]">'

[ac]            <a> tag including class:    '<a href="[url]" target="[target]" class="[class]">'

[li]            <li> tag including class:   '<li class="[class]">'

[ul]            <ul> tag including class:   '<ul class="[class]">'

[class]         List of classes for that page

[menu_title]    Menu title text (HTML entity escaped unless SM2_NOESCAPE flag is used)

[menu_icon_1]	URL poining to an image for display active/hover - status (from WB2.8.4)

[tooltip]       Tooltip caption, normaly shown in title-attribute of links (ab WB2.8.4)

[target]        Page target for the <a> 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

======================

The conditional formatting directive takes one of the following forms:

    [if(A){B}]

    [if(A){B}else{C}]

    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

    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

If more than one test is supplied, it must be combined with other tests

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.

        class       Test for existence of one of the classes. Only the

                    "==" and "!=" operators are permitted. In this case

        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.

        <           Less Than

        <=          Less Than Equals

        ==          Equals

        !=          Not Equal

        >=          Greater Than Equals

        >           Greater Than

    for the left operand:

        level       Test the page level against the following values:

                      <number>  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:

                      <number>  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.

    [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

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:

        [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)

FORMATTER

=========

Note: This is an advanced and rarely needed feature!

class SM2_Formatter

{

    // called once before any menu is processed to allow object initialization

    function initialize() { }

    function startList($aPage, $aUrl) { }

    function startItem($aPage, $aUrl, $aCurrSib, $aSibCount) { }

    function finishItem() { }

    function finishList() { }

    function finalize() { }

    function getOutput() { }

};