Project

General

Profile

1
show_menu2, version 4.9
2
=======================
3
A code snippet for the Website Baker CMS software. It provides a complete
4
replacement for the builtin menu functions. All menu data is retrieved using
5
a single database query, all types of menu styles (lists, breadcrums, sitemaps)
6
can be generated with extensive customisation of the resulting HTML.
7

    
8

    
9

    
10
INSTALLATION
11
============
12
1. Download the latest version from http://code.jellycan.com/show_menu2/
13
2. Log into your WebsiteBaker installation
14
3. Go to Addons -> Modules
15
4. If a previous version of show_menu2 is already installed, select it from
16
   the "Uninstall Module" list and choose the "Uninstall" button.
17
5. In the "Install Module" section, enter the path to the show_menu2 zip file
18
   that you downloaded in step 1, and choose the "Install" button.
19

    
20

    
21

    
22
USING SHOW_MENU2
23
================
24
You need to modify the PHP files of your template to call show_menu2 where you
25
wish to have the menu displayed. Remember when you replace calls to the old
26
menu functions to use the new parameters that show_menu2 requires.
27

    
28
Often times the default menu generated by show_menu2 is all that you need.
29
This menu shows the current page and children of the current page. It is
30
generated by just calling show_menu2 with no parameters. For example:
31

    
32
    $sMenu = show_menu2();
33

    
34
Note that the call to show_menu2 is PHP, so you usually need to wrap it in the
35
PHP code brackets so that it will execute. Like this:
36

    
37
    <?php echo show_menu2(); ?>
38

    
39
This default menu generates a complete list based menu with many classes that
40
allow easy CSS styling. For example, the current menu item will have the
41
"menu-current" class added to the <li> tag. Additionally, every menu item with
42
a sub-menu will have the "menu-expand" class added to the <li> tag. This allows
43
you to create CSS rules to style those menu items differently. For example:
44

    
45
    li.menu-expand  { font-weight: bold; }
46
    li.menu-current { background: red; }
47

    
48
See the "Output" section for details of exactly what classes are added to each
49
element. More elaborate and different menu structures are able to be created by
50
supplying different parameters to the show_menu2 function call. For example,
51
to show only menu items from the top level of the menu you use:
52

    
53
    $sMenu = show_menu2(0, SM2_ROOT, SM2_START);
54

    
55
Alternatively, to show up to two levels of the child menus of the current page:
56

    
57
    $sMenu = show_menu2(0, SM2_CURR+1, SM2_CURR+2);
58

    
59
There are many more possible menus that can be generated by show_menu2. See the
60
demonstration website at http://code.jellycan.com/sm2test/ for more examples.
61

    
62

    
63

    
64
COMMON QUESTIONS
65
================
66

    
67
Q:  I'm not a programmer. Do you have simpler documentation?
68
A:  Nup. This is it. Go hard. Gambarre.
69

    
70

    
71
Q:  How do I create a drop-down menu?
72
A:  This is unrelated to show_menu2. You need to change the template CSS code
73
    to display the menu as a drop-down. Try the "allcss2" template from the WB
74
    addon repository. http://addons.websitebaker.org/
75

    
76

    
77
Q:  Why does the menu disappear after I do a search on my multilingual WB site?
78
A:  You're missing some required lines in your template.
79

    
80
    1.  Log into WB administration, and go to Settings -> Show advanced settings
81
        -> Search Settings -> Header Code and add the following input field
82
        after the <form> open tag:
83

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

    
86

    
87
    2.  In the index.php of your template, add the following input field
88
        immediately following the search <form> open tag.
89

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

    
92

    
93
Q:  Multilingual? That sounds cool. How do I do that?
94
A:  http://www.websitebaker2.org/en/help/designer-guide/multilingual-websites.php
95

    
96

    
97
Q:  SM2 is generating a warning every time the page is accessed:
98
    "show_menu2 error: $aOptions is invalid. No flags from group 1 supplied!"
99
A:  You are passing the wrong values to the function. Have a closer look at the
100
    parameters that you are passing. See the PARAMETERS section below for the
101
    correct flag values to pass for the $aOptions parameter.
102

    
103

    
104
Q:  How do I use a different class/picture/color/widget for each entry in a menu?
105
A:  Use the [page_id] format string in the $aItemOpen string. Create a unique
106
    class or id for each menu item, then reference that item in your CSS or Javascript
107
    to do whatever you want.
108

    
109
    To add a unique class for each menu item (or similar):
110

    
111
        "<li><a href="[url]" target="[target]" class="[class] p[page_id]">[menu_title]</a>"
112

    
113
        ... creating menu items like ...
114

    
115
        <li><a href="/pages/foo/bar.php" target="_top" class="menu-top p45">Top Menu</a>
116

    
117
        Reference this in your CSS like:
118

    
119
        a.p45 { color: red; }
120

    
121
    To add a unique ID for each menu item (or similar):
122

    
123
        "<li><a id="p[page_id]" href="[url]" target="[target]" class="[class]">[menu_title]</a>"
124

    
125
        ... creating menu items like ...
126

    
127
        <li><a id="p45" href="/pages/foo/bar.php" target="_top" class="menu-top">Top Menu</a>
128

    
129
        Reference this in your CSS like:
130

    
131
        a#p45 { color: red; }
132

    
133
        Note that the ID can only be used if that menu is generated and displayed one time
134
        only on the page (because HTML ID's must be unique within a page).
135

    
136

    
137

    
138
FUNCTION
139
========
140

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

    
143
    show_menu2(
144
        $aMenu          = 0,
145
        $aStart         = SM2_ROOT,
146
        $aMaxLevel      = SM2_CURR+1,
147
        $aOptions       = SM2_TRIM,
148
        $aItemOpen      = '[li][a][menu_title]</a>',
149
        $aItemClose     = '</li>',
150
        $aMenuOpen      = '[ul]',
151
        $aMenuClose     = '</ul>',
152
        $aTopItemOpen   = false,
153
        $aTopMenuOpen   = false
154
        )
155

    
156
See the "Parameters" section for detailed descriptions of each parameter.
157
Ensure that you use each parameter correctly. Use the following rules:
158

    
159
    $aMenu will be 0 for most people.
160

    
161
    $aStart must be either a page ID or a value starting with "SM2_".
162

    
163
    $aMaxLevel must be only values that start with "SM2_".
164

    
165
    $aOptions must be only values that start with "SM2_" (unless you are
166
    in a very small minority of users).
167

    
168
    All other parameters are the HTML tag templates that will be
169
    output for menus and menu items.
170

    
171
Note that every parameter from $aItemOpen can be supplied as false to get
172
the default value.
173

    
174

    
175

    
176
HTML OUTPUT
177
===========
178
The menu is output differently depending on what parameters have been
179
supplied to the function, however in general the following classes are used
180
for each menu. Note that items will have multiple classes when relevant.
181

    
182
    CLASS           ATTACHED TO
183
    ------------    -------------------------------------------------------
184
    menu-top        First menu tag only
185
    menu-parent     Every parent menu item of the current page.
186
    menu-current    Only the menu item for the current page.
187
    menu-sibling    Every sibling of the current page.
188
    menu-child      Every sub-menu of the current page.
189
    menu-expand     Every menu item with children.
190
    menu-first      First item in any menu or sub-menu.
191
    menu-last       Last item in any menu or sub-menu.
192

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

    
195
    menu-N          Every menu item. The N is replaced with the ABSOLUTE
196
                    menu depth of the item starting with 0. The root level
197
                    menu is always menu-0, the next level is menu-1, etc.
198
    menu-child-N    Every sub-menu of the current page, the N is replaced
199
                    with the relative depth of the submenu starting at 0.
200

    
201

    
202
<ul class="menu-top menu-0">
203
  <li class="menu-0 menu-first">  ... </li>
204
  <li class="menu-0 menu-expand menu-parent">  ...
205
  <ul class="menu-1">
206
    <li class="menu-1 menu-expand menu-first">  ...
207
    <ul class="menu-2">
208
      <li class="menu-2 menu-first">  ...
209
      <li class="menu-2 menu-last">  ...
210
    </ul>
211
    </li>
212
    <li class="menu-1 menu-expand menu-parent">  ...
213
    <ul class="menu-2">
214
      <li class="menu-2 menu-expand menu-current menu-first">  ...      ** CURRENT PAGE **
215
      <ul class="menu-3">
216
        <li class="menu-3 menu-child menu-child-0 menu-first">  ...
217
        <ul class="menu-4">
218
          <li class="menu-4 menu-child menu-child-1 menu-first">  ... </li>
219
          <li class="menu-4 menu-child menu-child-1 menu-last">  ... </li>
220
        </ul>
221
        </li>
222
        <li class="menu-3 menu-child menu-child-0 menu-last">  ... </li>
223
      </ul>
224
      </li>
225
      <li class="menu-2 menu-sibling menu-last">  ... </li>
226
    </ul>
227
    </li>
228
    <li class="menu-1">  ... </li>
229
    <li class="menu-1 menu-expand menu-last">  ...
230
    <ul class="menu-2">
231
      <li class="menu-2 menu-first menu-last">  ... </li>
232
    </ul>
233
    </li>
234
  </ul>
235
  </li>
236
  <li class="menu-0 menu-last">  ... </li>
237
</ul>
238

    
239

    
240

    
241
PARAMETERS
242
==========
243
$aMenu
244
    Menu number to use. This is useful when you are using multiple menus.
245
    Supplying a menu number of 0 will use the default menu for the current
246
    page. Supplying SM2_ALLMENU will return all menus in the system.
247

    
248
$aStart
249
    Specify where the menu generation should start from. This is most
250
    times the parent item of the menu to display. It must be one of the
251
    following values:
252
        SM2_ROOT+N  Start N levels down from the root. e.g.
253
                      SM2_ROOT      Starting at the root menu
254
                      SM2_ROOT+1    Start 1 level below the root
255
                      SM2_ROOT+2    Start 2 levels below the root
256
        SM2_CURR+N  Start N levels down from the current page level. e.g.
257
                      SM2_CURR      Starts at the current page level. All
258
                                    sibling menus to the current page.
259
                      SM2_CURR+1    Starts 1 level down from the current
260
                                    page with the children menus.
261
        page_id     Display using the specific page as the parent. All
262
                    child menus of that page will be displayed. The
263
                    page_id can be found by editing the page in WB admin
264
                    interface. The page_id is included in the URL like:
265
                        http://SITE/admin/pages/modify.php?page_id=35
266

    
267
$aMaxLevel
268
    Maximum menu level to display. Menus are displayed from the start
269
    level down to this level.
270
        SM2_ALL     No limit, all levels are displayed
271
        SM2_CURR+N  Always show to the current page + N levels.
272
                      SM2_CURR      Current (no children)
273
                      SM2_CURR+3    All parents + current + 3 children
274
        SM2_START+N Always show from the starting level + N levels. The
275
                    levels of menu will always be displayed regardless of
276
                    what level the current page is.
277
                      SM2_START     Single level of menus from starting level
278
                      SM2_START+1   Starting level and 1 level down
279
        SM2_MAX+N   Show at most N levels from the starting level. Levels
280
                    won't be shown if they are below the current level.
281
                      SM2_MAX       Starting level only (same as SM2_START)
282
                      SM2_MAX+1     Maximum of starting level and 1 level.
283

    
284
$aOptions
285
    Specify flags for different generation options for the menu. The flags
286
    may be combined together using bitwise OR (|). For example, to specify
287
    both TRIM and PRETTY you should use, (SM2_TRIM | SM2_PRETTY).
288

    
289
    GROUP 1
290
    -------
291
    Exactly one flag from this group must always be supplied. These flags
292
    affect how the siblings in the tree are removed from the output.
293

    
294
    SM2_ALL         Show all branches of the menu tree
295
                        A-1 -> B-1
296
                            -> B-2 -> C-1
297
                                   -> C-2 (CURRENT)
298
                                          -> D-1
299
                                          -> D-2
300
                                   -> C-3
301
                        A-2 -> B-3
302
                            -> B-4
303
    SM2_TRIM        Show all sibling menus of pages on the current path.
304
                    All sub-menus of elements that are not on the path
305
                    are removed.
306
                        A-1 -> B-1
307
                            -> B-2 -> C-1
308
                                   -> C-2 (CURRENT)
309
                                          -> D-1
310
                                          -> D-2
311
                                   -> C-3
312
                        A-2
313
    SM2_CRUMB       Show only the breadcrumb trail, i.e. the current
314
                    menu and all of it's ancestor menus.
315
                        A-1 -> B-2 -> C-2 (CURRENT)
316
    SM2_SIBLING     The same as SM2_TRIM however only sibling menus of
317
                    the current page are displayed. All other menus are
318
                    trimmed to show only the path.
319
                        A-1 -> B-2 -> C-1
320
                                   -> C-2 (CURRENT)
321
                                          -> D-1
322
                                          -> D-2
323
                                   -> C-3
324

    
325
    GROUP 2
326
    -------
327
    All of these flags are optional. Any number of them may be combined.
328

    
329
    SM2_NUMCLASS    Add the numbered menu classes to the menu. If this
330
                    flag is supplied, the "menu-N" and "menu-child-N"
331
                    classes will be added.
332

    
333
    SM2_ALLINFO     Load all fields from the page table of the database.
334
                    This will result in quite a lot of memory being used
335
                    and is not recommended, however it will make keywords,
336
                    descriptions, and other fields available. This data
337
                    is not loaded by default.
338
                    NOTE: This flag must be used on the *FIRST* call to
339
                    show_menu2 *for this menu ID*, or in combination with
340
                    SM2_NOCACHE otherwise it will have no effect.
341

    
342
    SM2_NOCACHE     Do not reuse or store the data read from the database
343
                    between calls to show_menu2.
344

    
345
    SM2_PRETTY      Pretty print the menu HTML with spacing and newlines
346
                    for debugging purposes.
347

    
348
    SM2_BUFFER      Do not output the menu HTML but instead buffer it
349
                    internally and return it as a string from show_menu2.
350

    
351
    SM2_CURRTREE    Exclude all other top level menus from being considered.
352
                    Only items in the current menu tree will be output.
353
                    This can be combined with any of the Group 1 flags as
354
                    necessary.
355

    
356
    SM2_ESCAPE      Call htmlspecialchars on the menu strings. This may be
357
                    required with older installations of WB. By escaping the
358
                    raw database strings, it permits menus to have HTML
359
                    formatting in them that would cause otherwise cause
360
                    pages to fail validation.
361

    
362
    SM2_SHOWHIDDEN  Hidden pages are usually hidden all of the time, including
363
                    when they are active (i.e. current page or a parent page).
364
                    Use private pages for time when you want pages to be
365
                    hidden except when active. However for compatibility with
366
                    release 4.8, supply this flag to enable hidden pages to
367
                    become visible when they are active.
368

    
369
    SM2_XHTML_STRICT	From all links, created by [a] or [ac], the 'target' -
370
					attribute will be removed to preserve the XHTML-Compatibility
371

    
372
	SM2_NO_TITLE	Supress the value of the 'title'-attributes on links which
373
					are created by [a] or [ac] formatted links.
374

    
375
    This parameter also has an extended mode where an associative array of
376
    options is supplied. See the EXTENDED OPTIONS section for details.
377
    Most users will NOT need to use this.
378

    
379
$aItemOpen
380
    Format string to use for creating each individual menu item entry.
381
    A different format string may be used for the very first entry by
382
    supplying a different format string for $aTopItemOpen. When set to
383
    false, it uses the default of '[li][a][menu_title]</a>' to maintain
384
    compatibility with show_menu(). Note however that CSS formatting is
385
    often easier if the classes are added to the <a> tag. Use the format
386
    string of '<li>[ac][menu_title]</a>' for this style of tag.
387

    
388
    This parameter may also be specified as an instance of a formatting
389
    class for the menu. See the section "Formatter" below for details of
390
    the API this class must expose. When a formatter is supplied, all
391
    arguments after $aItemOpen are ignored.
392

    
393
$aItemClose
394
    String used to close each item. Note that this is not a format
395
    string and no keywords will be replaced. When set to false, it uses
396
    the default of '</li>'.
397

    
398
$aMenuOpen
399
    Format string to use for opening a list of menu item entries. A
400
    different format string may be used for the very first menu by
401
    supplying a different format string for $aTopMenuOpen. When set to
402
    false, it uses the default of '[ul]'.
403

    
404
$aMenuClose
405
    String used to close each menu. Note that this is not a format
406
    string and no keywords will be replaced. When set to false, it uses
407
    the default of '</ul>'.
408

    
409
$aTopItemOpen
410
    Format string for the first item. When set to false, it uses the same
411
    format as $aItemOpen.
412

    
413
$aTopMenuOpen
414
    Format string for the first menu. When set to false, it uses the same
415
    format as $aMenuOpen.
416

    
417

    
418

    
419
EXTENDED OPTIONS
420
================
421
The $aOptions parameter is a dual mode parameter. For most users, only the
422
SM2_* flags will be sufficient. However, to access the extra options, it
423
must be supplied as an associative array. Note that the SM2_* flags are
424
still required and must be supplied as 'flags'.
425

    
426
    'flags'     **REQUIRED** These are the flags described in PARAMETERS
427
                above for the $aOptions parameter.
428

    
429
    'notrim'    Specify a number of levels relative to the menu level of
430
                $aStart that will always be displayed. This will cause the
431
                SM2_TRIM flag to be ignored for these levels.
432

    
433
To supply one of these options in addition to the flags, the option array
434
should be created and passed as the $aOptions parameter:
435

    
436
    $options = array('flags' => (SM2_TRIM|...), 'notrim' => 1);
437
    $sMenu = show_menu2(0, SM2_ROOT, SM2_CURR+1, $options);
438

    
439

    
440

    
441
FORMAT STRINGS
442
==============
443
The following tags may be included in the format strings for $aItemOpen and
444
$aMenuOpen and will be replaced with the appropriate text.
445

    
446
[a]             <a> tag (no class):         '<a href="[url]" target="[target]">'
447
[ac]            <a> tag including class:    '<a href="[url]" target="[target]" class="[class]">'
448
[li]            <li> tag including class:   '<li class="[class]">'
449
[ul]            <ul> tag including class:   '<ul class="[class]">'
450
[class]         List of classes for that page
451
[menu_title]    Menu title text (HTML entity escaped unless SM2_NOESCAPE flag is used)
452
[menu_icon_0]	URL poining to an image for display normal - status (from WB2.8.4)
453
[menu_icon_1]	URL poining to an image for display active/hover - status (from WB2.8.4)
454
[page_title]    Page title text (HTML entity escaped unless SM2_NOESCAPE flag is used)
455
[page_icon]		URL poining to an image relating to the current page (from WB2.8.4)
456
[tooltip]       Tooltip caption, normaly shown in title-attribute of links (ab WB2.8.4)
457
[url]           Page URL for the <a> tag
458
[target]        Page target for the <a> tag
459
[page_id]       Page ID of the current menu item
460
[parent]        Page ID of the parent menu item
461
[level]         Page level, the same number as is used for the "menu-N" CSS tag.
462
[sib]           Current menu sibling number
463
[sibCount]      Total number of siblings in this menu
464
[if]            Conditional test (see section CONDITIONAL FORMATTING)
465

    
466
The following tags are only available when the SM2_ALLINFO flag is used.
467

    
468
[description]   Page description
469
[keywords]      Page keywords
470

    
471

    
472

    
473
CONDITIONAL FORMATTING
474
======================
475
The conditional formatting directive takes one of the following forms:
476

    
477
    [if(A){B}]
478
    [if(A){B}else{C}]
479

    
480
    A   Conditional test. See below for more details.
481

    
482
    B   Expression emitted when the if-test is true. This may be any string
483
        that does NOT include the '}' character. It may include any of the
484
        format strings described in the section FORMAT STRINGS with the
485
        exception of the conditional test (because '}' is not permitted).
486

    
487
    C   Expression emitted when the if-test is false. This may be any string
488
        that does NOT include the '}' character. It may include any of the
489
        format strings described in the section FORMAT STRINGS with the
490
        exception of the conditional test (because '}' is not permitted).
491

    
492
The conditional test is a combination of one or more boolean tests.
493
If more than one test is supplied, it must be combined with other tests
494
using either || (boolean OR) or && (boolean AND).
495

    
496
A single test is made up of the left operand, operator and right operand.
497
e.g. X == Y where X is the left operand, == is the operator and Y is the
498
right operand.
499

    
500
    Left operand. It must be one of the following keywords:
501
        class       Test for existence of one of the classes. Only the
502
                    "==" and "!=" operators are permitted. In this case
503
                    these operators have the meaning of "includes"
504
                    instead of "equals".
505
        level       Test against the page level.
506
        sib         Test against the current page sibling number.
507
        sibCount    Test against the number of siblings in the menu.
508
        id          Test against the page id.
509
		target		Test against the target attribute
510

    
511
    Operator. It must be one of the following:
512
        <           Less Than
513
        <=          Less Than Equals
514
        ==          Equals
515
        !=          Not Equal
516
        >=          Greater Than Equals
517
        >           Greater Than
518

    
519
    Right operand. The type of this operand depends on the keyword used
520
    for the left operand:
521
        class       One of the "menu-*" class names as listed in the
522
                    section "OUTPUT".
523
        level       Test the page level against the following values:
524
                      <number>  absolute page level
525
                      root      the root page level
526
                      granny    the grand-parent page level
527
                      parent    the parent page level
528
                      current   the current page level
529
                      child     the child page level
530
        id          Test the page id against the following values:
531
                      <number>  absolute page id
532
                      parent    the parent page id
533
                      current   the current page id
534
        sib         A positive integer, or "sibCount" to test against
535
                    the count of siblings in this menu.
536
        sibCount    A positive integer.
537
		target		A string, containing a possible target
538

    
539
For example, valid tests are expression "exp" is emitted only when the menu item:
540

    
541
    [if(class==menu-expand){exp}]   has a sub-menu
542
    [if(class==menu-first){exp}]    is first item in a menu
543
    [if(class!=menu-first){exp}]    is NOT first item in a menu
544
    [if(class==menu-last){exp}]     is last item in a menu
545
    [if(level==0){exp}]             is at the root
546
    [if(level>0){exp}]              is not at the root
547
    [if(sib==2){exp}]               is the second item in a menu
548
    [if(sibCount>1){exp}]           is in a menu with more than 1 entry
549
    [if(sibCount!=2){exp}]          is in a menu which doesn't have exactly
550
    [if(level>parent){exp}]         is in a sibling menu or child of a sibling
551
    [if(id==parent){exp}]           is the parent of the current page
552
	[if(target==_self){exp}]		if value of target-attribute is '_self'
553

    
554
If an else-clause was added, then the expression for the else would be
555
emitted in all other cases. For example the expression "foo" is emitted
556
whenever the if-test is false, so therefore:
557

    
558
    [if(sib==2){exp}else{foo}]          is NOT the second item in a menu
559
    [if(sibCount>2){exp}else{foo}]      is NOT in a menu with more than 2 entries
560

    
561
For multiple tests, the expression "exp" is emitted only when the menu item:
562

    
563
    [if(sib == 1 || sib > 3){exp}]
564
        [is the first item] OR [is the 4th or larger item] in the menu
565

    
566
    [if(id == current && class == menu-expand){exp}
567
        [is the current item] AND [it has children]
568

    
569
Note that all tests are evaluated in the order listed because:
570
 * there is no short-circuit evaluation (all individual tests are always evaluated)
571
 * there is no grouping of tests (i.e. no support for parenthesis)
572
 * both || and && are considered the same level
573

    
574

    
575

    
576
FORMATTER
577
=========
578
Note: This is an advanced and rarely needed feature!
579

    
580
If you are capable of extensive PHP programming, it is possible to replace the
581
predefined menu formatter that show_menu2 is uses with a custom module. See the
582
include.php file of show_menu2 for an example of how the menu formatter must be
583
written. The API it must use is:
584

    
585
class SM2_Formatter
586
{
587
    // called once before any menu is processed to allow object initialization
588
    function initialize() { }
589

    
590
    // called to open the menu list
591
    function startList($aPage, $aUrl) { }
592

    
593
    // called to open the menu item
594
    function startItem($aPage, $aUrl, $aCurrSib, $aSibCount) { }
595

    
596
    // called to close the menu item
597
    function finishItem() { }
598

    
599
    // called to close the menu list
600
    function finishList() { }
601

    
602
    // called once after all menu has been processed to allow object finalization
603
    function finalize() { }
604

    
605
    // called once after finalize() if the SM2_NOOUTPUT flag is used
606
    function getOutput() { }
607
};
(3-3/3)