Project

General

Profile

1
show_menu2, version 4.8
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
    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 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
    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
    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/pages/templates.php
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://help.websitebaker.org/pages/en/advanced-docu.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
    SM2_ALLINFO     Load all fields from the page table of the database.
333
                    This will result in quite a lot of memory being used
334
                    and is not recommended, however it will make keywords,
335
                    descriptions, and other fields available. This data
336
                    is not loaded by default.
337
                    NOTE: This flag must be used on the *FIRST* call to
338
                    show_menu2 *for this menu ID*, or in combination with
339
                    SM2_NOCACHE otherwise it will have no effect.
340
    SM2_NOCACHE     Do not reuse or store the data read from the database
341
                    between calls to show_menu2. 
342
    SM2_PRETTY      Pretty print the menu HTML with spacing and newlines
343
                    for debugging purposes.
344
    SM2_BUFFER      Do not output the menu HTML but instead buffer it 
345
                    internally and return it as a string from show_menu2.
346
    SM2_CURRTREE    Exclude all other top level menus from being considered. 
347
                    Only items in the current menu tree will be output.
348
                    This can be combined with any of the Group 1 flags as
349
                    necessary.
350
    SM2_ESCAPE      Call htmlspecialchars on the menu strings. This may be
351
                    required with older installations of WB. By escaping the
352
                    raw database strings, it permits menus to have HTML 
353
                    formatting in them that would cause otherwise cause
354
                    pages to fail validation. 
355
    SM2_NOESCAPE    Default behaviour. Exists only for backwards compatibility.                    
356

    
357
    This parameter also has an extended mode where an associative array of 
358
    options is supplied. See the EXTENDED OPTIONS section for details. 
359
    Most users will NOT need to use this.
360

    
361
$aItemOpen
362
    Format string to use for creating each individual menu item entry.
363
    A different format string may be used for the very first entry by 
364
    supplying a different format string for $aTopItemOpen. When set to 
365
    false, it uses the default of '[li][a][menu_title]</a>' to maintain
366
    compatibility with show_menu(). Note however that CSS formatting is
367
    often easier if the classes are added to the <a> tag. Use the format
368
    string of '<li>[ac][menu_title]</a>' for this style of tag.
369

    
370
    This parameter may also be specified as an instance of a formatting 
371
    class for the menu. See the section "Formatter" below for details of
372
    the API this class must expose. When a formatter is supplied, all 
373
    arguments after $aItemOpen are ignored.
374

    
375
$aItemClose
376
    String used to close each item. Note that this is not a format
377
    string and no keywords will be replaced. When set to false, it uses 
378
    the default of '</li>'.
379

    
380
$aMenuOpen
381
    Format string to use for opening a list of menu item entries. A 
382
    different format string may be used for the very first menu by 
383
    supplying a different format string for $aTopMenuOpen. When set to 
384
    false, it uses the default of '[ul]'.
385

    
386
$aMenuClose
387
    String used to close each menu. Note that this is not a format
388
    string and no keywords will be replaced. When set to false, it uses 
389
    the default of '</ul>'.
390

    
391
$aTopItemOpen
392
    Format string for the first item. When set to false, it uses the same 
393
    format as $aItemOpen.
394

    
395
$aTopMenuOpen 
396
    Format string for the first menu. When set to false, it uses the same 
397
    format as $aMenuOpen.
398

    
399

    
400

    
401
EXTENDED OPTIONS
402
================
403
The $aOptions parameter is a dual mode parameter. For most users, only the
404
SM2_* flags will be sufficient. However, to access the extra options, it 
405
must be supplied as an associative array. Note that the SM2_* flags are
406
still required and must be supplied as 'flags'.
407

    
408
    'flags'     **REQUIRED** These are the flags described in PARAMETERS
409
                above for the $aOptions parameter. 
410

    
411
    'notrim'    Specify a number of levels relative to the menu level of 
412
                $aStart that will always be displayed. This will cause the
413
                SM2_TRIM flag to be ignored for these levels.
414
                        
415
To supply one of these options in addition to the flags, the option array 
416
should be created and passed as the $aOptions parameter:
417

    
418
    $options = array('flags' => (SM2_TRIM|...), 'notrim' => 1);
419
    show_menu2(0, SM2_ROOT, SM2_CURR+1, $options);
420
    
421
    
422
    
423
FORMAT STRINGS
424
==============
425
The following tags may be included in the format strings for $aItemOpen and 
426
$aMenuOpen and will be replaced with the appropriate text.
427

    
428
[a]             <a> tag (no class):         '<a href="[url]" target="[target]">'
429
[ac]            <a> tag including class:    '<a href="[url]" target="[target]" class="[class]">'
430
[li]            <li> tag including class:   '<li class="[class]">'
431
[ul]            <ul> tag including class:   '<ul class="[class]">'
432
[class]         List of classes for that page
433
[menu_title]    Menu title text (HTML entity escaped unless SM2_NOESCAPE flag is used)
434
[page_title]    Page title text (HTML entity escaped unless SM2_NOESCAPE flag is used)
435
[url]           Page URL for the <a> tag
436
[target]        Page target for the <a> tag
437
[page_id]       Page ID of the current menu item
438
[parent]        Page ID of the parent menu item
439
[level]         Page level, the same number as is used for the "menu-N" CSS tag.
440
[sib]           Current menu sibling number
441
[sibCount]      Total number of siblings in this menu
442
[if]            Conditional test (see section CONDITIONAL FORMATTING)
443

    
444
The following tags are only available when the SM2_ALLINFO flag is used.
445

    
446
[description]   Page description
447
[keywords]      Page keywords
448

    
449

    
450

    
451
CONDITIONAL FORMATTING
452
======================
453
The conditional formatting directive takes one of the following forms:
454

    
455
    [if(A){B}]
456
    [if(A){B}else{C}]
457
    
458
    A   Conditional test. See below for more details.
459
    
460
    B   Expression emitted when the if-test is true. This may be any string 
461
        that does NOT include the '}' character. It may include any of the 
462
        format strings described in the section FORMAT STRINGS with the 
463
        exception of the conditional test (because '}' is not permitted).
464
        
465
    C   Expression emitted when the if-test is false. This may be any string 
466
        that does NOT include the '}' character. It may include any of the 
467
        format strings described in the section FORMAT STRINGS with the 
468
        exception of the conditional test (because '}' is not permitted).
469
    
470
The conditional test is a combination of one or more boolean tests.
471
If more than one test is supplied, it must be combined with other tests
472
using either || (boolean OR) or && (boolean AND). 
473

    
474
A single test is made up of the left operand, operator and right operand.
475
e.g. X == Y where X is the left operand, == is the operator and Y is the
476
right operand.
477
    
478
    Left operand. It must be one of the following keywords:
479
        class       Test for existence of one of the classes. Only the
480
                    "==" and "!=" operators are permitted. In this case
481
                    these operators have the meaning of "includes" 
482
                    instead of "equals".
483
        level       Test against the page level.
484
        sib         Test against the current page sibling number.
485
        sibCount    Test against the number of siblings in the menu.
486
        id          Test against the page id.
487
    
488
    Operator. It must be one of the following:
489
        <           Less Than
490
        <=          Less Than Equals
491
        ==          Equals
492
        !=          Not Equal
493
        >=          Greater Than Equals
494
        >           Greater Than
495
    
496
    Right operand. The type of this operand depends on the keyword used
497
    for the left operand:
498
        class       One of the "menu-*" class names as listed in the 
499
                    section "OUTPUT".
500
        level       Test the page level against the following values:
501
                      <number>  absolute page level
502
                      root      the root page level
503
                      granny    the grand-parent page level
504
                      parent    the parent page level
505
                      current   the current page level
506
                      child     the child page level
507
        id          Test the page id against the following values:
508
                      <number>  absolute page id
509
                      parent    the parent page id
510
                      current   the current page id
511
        sib         A positive integer, or "sibCount" to test against
512
                    the count of siblings in this menu.
513
        sibCount    A positive integer.
514
        
515
For example, valid tests are expression "exp" is emitted only when the menu item:
516
    
517
    [if(class==menu-expand){exp}]   has a sub-menu
518
    [if(class==menu-first){exp}]    is first item in a menu
519
    [if(class!=menu-first){exp}]    is NOT first item in a menu
520
    [if(class==menu-last){exp}]     is last item in a menu
521
    [if(level==0){exp}]             is at the root
522
    [if(level>0){exp}]              is not at the root
523
    [if(sib==2){exp}]               is the second item in a menu
524
    [if(sibCount>1){exp}]           is in a menu with more than 1 entry
525
    [if(sibCount!=2){exp}]          is in a menu which doesn't have exactly
526
    [if(level>parent){exp}]         is in a sibling menu or child of a sibling
527
    [if(id==parent){exp}]           is the parent of the current page
528

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

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

    
536
For multiple tests, the expression "exp" is emitted only when the menu item:
537

    
538
    [if(sib == 1 || sib > 3){exp}]      
539
        [is the first item] OR [is the 4th or larger item] in the menu
540
        
541
    [if(id == current && class == menu-expand){exp}
542
        [is the current item] AND [it has children]
543

    
544
Note that all tests are evaluated in the order listed because:
545
 * there is no short-circuit evaluation (all individual tests are always evaluated)
546
 * there is no grouping of tests (i.e. no support for parenthesis)
547
 * both || and && are considered the same level 
548

    
549

    
550

    
551
FORMATTER
552
=========
553
Note: This is an advanced and rarely needed feature!
554

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

    
560
class SM2_Formatter
561
{
562
    // called once before any menu is processed to allow object initialization
563
    function initialize() { }
564
    
565
    // called to open the menu list
566
    function startList($aPage, $aUrl) { }
567
    
568
    // called to open the menu item
569
    function startItem($aPage, $aUrl, $aCurrSib, $aSibCount) { }
570
    
571
    // called to close the menu item
572
    function finishItem() { }
573
    
574
    // called to close the menu list
575
    function finishList() { }
576
    
577
    // called once after all menu has been processed to allow object finalization
578
    function finalize() { }
579
    
580
    // called once after finalize() if the SM2_NOOUTPUT flag is used
581
    function getOutput() { }
582
};
(3-3/7)