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: $sMenu = 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: $sMenu = show_menu2(0, SM2_ROOT, SM2_START); Alternatively, to show up to two levels of the child menus of the current page: $sMenu = 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/ 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
    open tag: 2. In the index.php of your template, add the following input field immediately following the search open tag. Q: Multilingual? That sounds cool. How do I do that? A: http://www.websitebaker2.org/en/help/designer-guide/multilingual-websites.php Q: SM2 is generating a warning every time the page is accessed: "show_menu2 error: $aOptions is invalid. No flags from group 1 supplied!" A: You are passing the wrong values to the function. Have a closer look at the parameters that you are passing. See the PARAMETERS section below for the correct flag values to pass for the $aOptions parameter. Q: How do I use a different class/picture/color/widget for each entry in a menu? A: Use the [page_id] format string in the $aItemOpen string. Create a unique class or id for each menu item, then reference that item in your CSS or Javascript to do whatever you want. To add a unique class for each menu item (or similar): "
  • [menu_title]" ... creating menu items like ...
  • Top Menu Reference this in your CSS like: a.p45 { color: red; } To add a unique ID for each menu item (or similar): "
  • [menu_title]" ... creating menu items like ...
  • Top Menu Reference this in your CSS like: a#p45 { color: red; } Note that the ID can only be used if that menu is generated and displayed one time only on the page (because HTML ID's must be unique within a page). FUNCTION ======== The complete call signature and default parameter value for show_menu2 is: show_menu2( $aMenu = 0, $aStart = SM2_ROOT, $aMaxLevel = SM2_CURR+1, $aOptions = SM2_TRIM, $aItemOpen = '[li][a][menu_title]', $aItemClose = '
    • ', $aMenuOpen = '[ul]', $aMenuClose = '', $aTopItemOpen = false, $aTopMenuOpen = false ) See the "Parameters" section for detailed descriptions of each parameter. Ensure that you use each parameter correctly. Use the following rules: $aMenu will be 0 for most people. $aStart must be either a page ID or a value starting with "SM2_". $aMaxLevel must be only values that start with "SM2_". $aOptions must be only values that start with "SM2_" (unless you are in a very small minority of users). All other parameters are the HTML tag templates that will be output for menus and menu items. Note that every parameter from $aItemOpen can be supplied as false to get the default value. HTML OUTPUT =========== The menu is output differently depending on what parameters have been supplied to the function, however in general the following classes are used for each menu. Note that items will have multiple classes when relevant. 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-N Every menu item. The N is replaced with the ABSOLUTE menu depth of the item starting with 0. The root level menu is always menu-0, the next level is menu-1, etc. menu-child-N Every sub-menu of the current page, the N is replaced with the relative depth of the submenu starting at 0. PARAMETERS ========== $aMenu 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 page. Supplying SM2_ALLMENU will return all menus in the system. $aStart Specify where the menu generation should start from. This is most times the parent item of the menu to display. It must be one of the following values: SM2_ROOT+N Start N levels down from the root. e.g. SM2_ROOT Starting at the root menu SM2_ROOT+1 Start 1 level below the root 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 child menus of that page will be displayed. The page_id can be found by editing the page in WB admin interface. The page_id is included in the URL like: http://SITE/admin/pages/modify.php?page_id=35 $aMaxLevel Maximum menu level to display. Menus are displayed from the start level down to this level. SM2_ALL No limit, all levels are displayed SM2_CURR+N Always show to the current page + N levels. SM2_CURR Current (no children) 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+N Show at most N levels from the starting level. Levels won't be shown if they are below the current level. SM2_MAX Starting level only (same as SM2_START) SM2_MAX+1 Maximum of starting level and 1 level. $aOptions Specify flags for different generation options for the menu. The flags may be combined together using bitwise OR (|). For example, to specify both TRIM and PRETTY you should use, (SM2_TRIM | SM2_PRETTY). GROUP 1 ------- Exactly one flag from this group must always be supplied. These flags affect how the siblings in the tree are removed from the output. SM2_ALL Show all branches of the menu tree A-1 -> B-1 -> B-2 -> C-1 -> C-2 (CURRENT) -> D-1 -> D-2 -> C-3 A-2 -> B-3 -> B-4 SM2_TRIM Show all sibling menus of pages on the current path. All sub-menus of elements that are not on the path are removed. A-1 -> B-1 -> B-2 -> C-1 -> C-2 (CURRENT) -> D-1 -> D-2 -> C-3 A-2 SM2_CRUMB Show only the breadcrumb trail, i.e. the current menu and all of it's ancestor menus. A-1 -> B-2 -> C-2 (CURRENT) SM2_SIBLING The same as SM2_TRIM however only sibling menus of the current page are displayed. All other menus are trimmed to show only the path. 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. SM2_NUMCLASS Add the numbered menu classes to the menu. If this flag is supplied, the "menu-N" and "menu-child-N" classes will be added. SM2_ALLINFO Load all fields from the page table of the database. 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. SM2_NOCACHE Do not reuse or store the data read from the database between calls to show_menu2. SM2_PRETTY Pretty print the menu HTML with spacing and newlines for debugging purposes. SM2_BUFFER Do not output the menu HTML but instead buffer it internally and return it as a string from show_menu2. SM2_CURRTREE Exclude all other top level menus from being considered. Only items in the current menu tree will be output. This can be combined with any of the Group 1 flags as necessary. SM2_ESCAPE Call htmlspecialchars on the menu strings. This may be required with older installations of WB. By escaping the raw database strings, it permits menus to have HTML formatting in them that would cause otherwise cause pages to fail validation. SM2_SHOWHIDDEN Hidden pages are usually hidden all of the time, including when they are active (i.e. current page or a parent page). 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. SM2_XHTML_STRICT From all links, created by [a] or [ac], the 'target' - 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. This parameter also has an extended mode where an associative array of options is supplied. See the EXTENDED OPTIONS section for details. Most users will NOT need to use this. $aItemOpen Format string to use for creating each individual menu item entry. A different format string may be used for the very first entry by supplying a different format string for $aTopItemOpen. When set to false, it uses the default of '[li][a][menu_title]' to maintain compatibility with show_menu(). Note however that CSS formatting is often easier if the classes are added to the tag. Use the format string of '
  • [ac][menu_title]' for this style of tag. This parameter may also be specified as an instance of a formatting class for the menu. See the section "Formatter" below for details of the API this class must expose. When a formatter is supplied, all arguments after $aItemOpen are ignored. $aItemClose String used to close each item. Note that this is not a format string and no keywords will be replaced. When set to false, it uses the default of '
    • '. $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); $sMenu = 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]