Project

General

Profile

1 827 doc
// $Id$
2
3
show_menu2, version 4.5
4
=======================
5
A code snippet for the Website Baker CMS software. It provides a complete
6
replacement for the builtin menu functions. All menu data is retrieved using
7
a single database query, all types of menu styles (lists, breadcrums, sitemaps)
8
can be generated with extensive customisation of the resulting HTML.
9
10
11
INSTALLATION
12
============
13
1. Download the latest version from http://code.jellycan.com/show_menu2/
14
2. Log into your WebsiteBaker installation
15
3. Go to Addons -> Modules
16
4. If a previous version of show_menu2 is already installed, select it from
17
   the "Uninstall Module" list and choose the "Uninstall" button.
18
5. In the "Install Module" section, enter the path to the show_menu2 zip file
19
   that you downloaded in step 1, and choose the "Install" button.
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 parameters to the show_menu2 function call. For example, to show only
51
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
FUNCTION
64
========
65
66
The complete call signature and default parameter value for show_menu2 is:
67
68
    show_menu2(
69
        $aMenu          = 0,
70
        $aStart         = SM2_ROOT,
71
        $aMaxLevel      = SM2_CURR+1,
72
        $aFlags         = SM2_TRIM,
73
        $aItemOpen      = '[li][a][menu_title]</a>',
74
        $aItemClose     = '</li>',
75
        $aMenuOpen      = '[ul]',
76
        $aMenuClose     = '</ul>',
77
        $aTopItemOpen   = false,
78
        $aTopMenuOpen   = false
79
        )
80
81
See the "Parameters" section for detailed descriptions of each parameter.
82
Note that every parameter from $aItemOpen onwards can be supplied as false
83
in order to get the default value, this allows (for example) a numbered list
84
to be used while still using the the default menu parameters for the items.
85
Note that all parameters up to $aFlags need to be explicitly supplied.
86
For example:
87
88
show_menu2(0, SM2_ROOT, SM2_ALL, SM2_ALL, false, false, '<ol>', '</ol>');
89
90
91
OUTPUT
92
======
93
The menu is output differently depending on what parameters have been
94
supplied to the function, however in general the following classes are used
95
for each menu. Note that items will have multiple classes when relevant.
96
97
    CLASS           ATTACHED TO
98
    ------------    -------------------------------------------------------
99
    menu-top        First menu tag only
100
    menu-parent     Every parent menu item of the current page.
101
    menu-current    Only the menu item for the current page.
102
    menu-sibling    Every sibling of the current page.
103
    menu-child      Every sub-menu of the current page.
104
    menu-expand     Every menu item with children.
105
    menu-first      First item in any menu or sub-menu.
106
    menu-last       Last item in any menu or sub-menu.
107
108
    The following classes are added only if SM2_NUMCLASS flag has been used.
109
110
    menu-N          Every menu item. The N is replaced with the ABSOLUTE
111
                    menu depth of the item starting with 0. The root level
112
                    menu is always menu-0, the next level is menu-1, etc.
113
    menu-child-N    Every sub-menu of the current page, the N is replaced
114
                    with the relative depth of the submenu starting at 0.
115
116
117
<ul class="menu-top menu-0">
118
  <li class="menu-0 menu-first">  ... </li>
119
  <li class="menu-0 menu-expand menu-parent">  ...
120
  <ul class="menu-1">
121
    <li class="menu-1 menu-expand menu-first">  ...
122
    <ul class="menu-2">
123
      <li class="menu-2 menu-first">  ...
124
      <li class="menu-2 menu-last">  ...
125
    </ul>
126
    </li>
127
    <li class="menu-1 menu-expand menu-parent">  ...
128
    <ul class="menu-2">
129
      <li class="menu-2 menu-expand menu-current menu-first">  ...      ** CURRENT PAGE **
130
      <ul class="menu-3">
131
        <li class="menu-3 menu-child menu-child-0 menu-first">  ...
132
        <ul class="menu-4">
133
          <li class="menu-4 menu-child menu-child-1 menu-first">  ... </li>
134
          <li class="menu-4 menu-child menu-child-1 menu-last">  ... </li>
135
        </ul>
136
        </li>
137
        <li class="menu-3 menu-child menu-child-0 menu-last">  ... </li>
138
      </ul>
139
      </li>
140
      <li class="menu-2 menu-sibling menu-last">  ... </li>
141
    </ul>
142
    </li>
143
    <li class="menu-1">  ... </li>
144
    <li class="menu-1 menu-expand menu-last">  ...
145
    <ul class="menu-2">
146
      <li class="menu-2 menu-first menu-last">  ... </li>
147
    </ul>
148
    </li>
149
  </ul>
150
  </li>
151
  <li class="menu-0 menu-last">  ... </li>
152
</ul>
153
154
155
156
PARAMETERS
157
==========
158
$aMenu
159
    Menu number to use. This is useful when you are using multiple menus.
160
    Supplying a menu number of 0 will use the default menu for the current
161
    page. Supplying SM2_ALLMENU will return all menus in the system.
162
163
$aStart
164
    Specify where the menu generation should start from. This is most
165
    times the parent item of the menu to display. It must be one of the
166
    following values:
167
        SM2_ROOT+N  Start N levels down from the root. e.g.
168
                      SM2_ROOT      Starting at the root menu
169
                      SM2_ROOT+1    Start 1 level below the root
170
                      SM2_ROOT+2    Start 2 levels below the root
171
        SM2_CURR+N  Start N levels down from the current page level. e.g.
172
                      SM2_CURR      Starts at the current page level. All
173
                                    sibling menus to the current page.
174
                      SM2_CURR+1    Starts 1 level down from the current
175
                                    page with the children menus.
176
        page_id     Display using the specific page as the parent. All
177
                    child menus of that page will be displayed. The
178
                    page_id can be found by editing the page in WB admin
179
                    interface. The page_id is included in the URL like:
180
                        http://SITE/admin/pages/modify.php?page_id=35
181
182
$aMaxLevel
183
    Maximum menu level to display. Menus are displayed from the start
184
    level down to this level.
185
        SM2_ALL     No limit, all levels are displayed
186
        SM2_CURR+N  Always show to the current page + N levels.
187
                      SM2_CURR      Current (no children)
188
                      SM2_CURR+3    All parents + current + 3 children
189
        SM2_START+N Always show from the starting level + N levels. The
190
                    levels of menu will always be displayed regardless of
191
                    what level the current page is.
192
                      SM2_START     Single level of menus from starting level
193
                      SM2_START+1   Starting level and 1 level down
194
        SM2_MAX+N   Show at most N levels from the starting level. Levels
195
                    won't be shown if they are below the current level.
196
                      SM2_MAX       Starting level only (same as SM2_START)
197
                      SM2_MAX+1     Maximum of starting level and 1 level.
198
199
$aFlags
200
    Specify flags for different generation options for the menu. The flags
201
    may be combined together using bitwise OR (|). For example, to specify
202
    both TRIM and PRETTY you should use, SM2_TRIM|SM2_PRETTY.
203
204
    GROUP 1
205
    -------
206
    Exactly one flag from this group must always be supplied. These flags
207
    affect how the siblings in the tree are removed from the output.
208
209
    SM2_ALL         Show all branches of the menu tree
210
                        A-1 -> B-1
211
                            -> B-2 -> C-1
212
                                   -> C-2 (CURRENT)
213
                                          -> D-1
214
                                          -> D-2
215
                                   -> C-3
216
                        A-2 -> B-3
217
                            -> B-4
218
    SM2_TRIM        Show all sibling menus of pages on the current path.
219
                    All sub-menus of elements that are not on the path
220
                    are removed.
221
                        A-1 -> B-1
222
                            -> B-2 -> C-1
223
                                   -> C-2 (CURRENT)
224
                                          -> D-1
225
                                          -> D-2
226
                                   -> C-3
227
                        A-2
228
    SM2_CRUMB       Show only the breadcrumb trail, i.e. the current
229
                    menu and all of it's ancestor menus.
230
                        A-1 -> B-2 -> C-2 (CURRENT)
231
    SM2_SIBLING     The same as SM2_TRIM however only sibling menus of
232
                    the current page are displayed. All other menus are
233
                    trimmed to show only the path.
234
                        A-1 -> B-2 -> C-1
235
                                   -> C-2 (CURRENT)
236
                                          -> D-1
237
                                          -> D-2
238
                                   -> C-3
239
240
    GROUP 2
241
    -------
242
    All of these flags are optional. Any number of them may be combined.
243
244
    SM2_NUMCLASS    Add the numbered menu classes to the menu. If this
245
                    flag is supplied, the "menu-N" and "menu-child-N"
246
                    classes will be added.
247
    SM2_ALLINFO     Load all fields from the page table of the database.
248
                    This will result in quite a lot of memory being used
249
                    and is not recommended, however it will make keywords,
250
                    descriptions, and other fields available. This data
251
                    is not loaded by default.
252
                    NOTE: This flag must be used on the *FIRST* call to
253
                    show_menu2 *for this menu ID*, or in combination with
254
                    SM2_NOCACHE otherwise it will have no effect.
255
    SM2_NOCACHE     Do not reuse or store the data read from the database
256
                    between calls to show_menu2.
257
    SM2_PRETTY      Pretty print the menu HTML with spacing and newlines
258
                    for debugging purposes.
259
    SM2_BUFFER      Do not output the menu HTML but instead buffer it
260
                    internally and return it as a string from show_menu2.
261
    SM2_CURRTREE    Exclude all other top level menus from being considered.
262
                    Only items in the current menu tree will be output.
263
                    This can be combined with any of the Group 1 flags as
264
                    necessary.
265
    SM2_ESCAPE      Call htmlspecialchars on the menu strings. This may be
266
                    required with older installations of WB. By escaping the
267
                    raw database strings, it permits menus to have HTML
268
                    formatting in them that would cause otherwise cause
269
                    pages to fail validation.
270
    SM2_NOESCAPE    Default behaviour. Exists only for backwards compatibility.
271
272
273
$aItemOpen
274
    Format string to use for creating each individual menu item entry.
275
    A different format string may be used for the very first entry by
276
    supplying a different format string for $aTopItemOpen. When set to
277
    false, it uses the default of '[li][a][menu_title]</a>' to maintain
278
    compatibility with show_menu(). Note however that CSS formatting is
279
    often easier if the classes are added to the <a> tag. Use the format
280
    string of '<li>[ac][menu_title]</a>' for this style of tag.
281
282
    This parameter may also be specified as an instance of a formatting
283
    class for the menu. See the section "Formatter" below for details of
284
    the API this class must expose. When a formatter is supplied, all
285
    arguments after $aItemOpen are ignored.
286
287
$aItemClose
288
    String used to close each item. Note that this is not a format
289
    string and no keywords will be replaced. When set to false, it uses
290
    the default of '</li>'.
291
292
$aMenuOpen
293
    Format string to use for opening a list of menu item entries. A
294
    different format string may be used for the very first menu by
295
    supplying a different format string for $aTopMenuOpen. When set to
296
    false, it uses the default of '[ul]'.
297
298
$aMenuClose
299
    String used to close each menu. Note that this is not a format
300
    string and no keywords will be replaced. When set to false, it uses
301
    the default of '</ul>'.
302
303
$aTopItemOpen
304
    Format string for the first item. When set to false, it uses the same
305
    format as $aItemOpen.
306
307
$aTopMenuOpen
308
    Format string for the first menu. When set to false, it uses the same
309
    format as $aMenuOpen.
310
311
312
313
FORMAT STRINGS
314
==============
315
The following tags may be included in the format strings for $aItemOpen and
316
$aMenuOpen and will be replaced with the appropriate text.
317
318
[a]             <a> tag (no class):         '<a href="[url]" target="[target]">'
319
[ac]            <a> tag including class:    '<a href="[url]" target="[target]" class="[class]">'
320
[li]            <li> tag including class:   '<li class="[class]">'
321
[ul]            <ul> tag including class:   '<ul class="[class]">'
322
[class]         List of classes for that page
323
[menu_title]    Menu title text (HTML entity escaped unless SM2_NOESCAPE flag is used)
324
[page_title]    Page title text (HTML entity escaped unless SM2_NOESCAPE flag is used)
325
[url]           Page URL for the <a> tag
326
[target]        Page target for the <a> tag
327
[page_id]       Page ID of the current menu item
328
[parent]        Page ID of the parent menu item
329
[level]         Page level, the same number as is used for the "menu-N" CSS tag.
330
[sib]           Current menu sibling number
331
[sibCount]      Total number of siblings in this menu
332
[if]            Conditional test (see section CONDITIONAL FORMATTING)
333
334
The following tags are only available when the SM2_ALLINFO flag is used.
335
336
[description]   Page description
337
[keywords]      Page keywords
338
339
340
CONDITIONAL FORMATTING
341
======================
342
The conditional formatting directive takes one of the following forms:
343
344
    [if(A){B}]
345
    [if(A){B}else{C}]
346
347
    A   Conditional test. See below for more details.
348
349
    B   Expression emitted when the if-test is true. This may be any string
350
        that does NOT include the '}' character. It may include any of the
351
        format strings described in the section FORMAT STRINGS with the
352
        exception of the conditional test (because '}' is not permitted).
353
354
    C   Expression emitted when the if-test is false. This may be any string
355
        that does NOT include the '}' character. It may include any of the
356
        format strings described in the section FORMAT STRINGS with the
357
        exception of the conditional test (because '}' is not permitted).
358
359
The conditional test is a combination of one or more boolean tests.
360
If more than one test is supplied, it must be combined with other tests
361
using either || (boolean OR) or && (boolean AND).
362
363
A single test is made up of the left operand, operator and right operand.
364
e.g. X == Y where X is the left operand, == is the operator and Y is the
365
right operand.
366
367
    Left operand. It must be one of the following keywords:
368
        class       Test for existence of one of the classes. Only the
369
                    "==" and "!=" operators are permitted. In this case
370
                    these operators have the meaning of "includes"
371
                    instead of "equals".
372
        level       Test against the page level.
373
        sib         Test against the current page sibling number.
374
        sibCount    Test against the number of siblings in the menu.
375
        id          Test against the page id.
376
377
    Operator. It must be one of the following:
378
        <           Less Than
379
        <=          Less Than Equals
380
        ==          Equals
381
        !=          Not Equal
382
        >=          Greater Than Equals
383
        >           Greater Than
384
385
    Right operand. The type of this operand depends on the keyword used
386
    for the left operand:
387
        class       One of the "menu-*" class names as listed in the
388
                    section "OUTPUT".
389
        level       Test the page level against the following values:
390
                      <number>  absolute page level
391
                      root      the root page level
392
                      granny    the grand-parent page level
393
                      parent    the parent page level
394
                      current   the current page level
395
                      child     the child page level
396
        id          Test the page id against the following values:
397
                      <number>  absolute page id
398
                      parent    the parent page id
399
                      current   the current page id
400
        sib         A positive integer, or "sibCount" to test against
401
                    the count of siblings in this menu.
402
        sibCount    A positive integer.
403
404
For example, valid tests are expression "exp" is emitted only when the menu item:
405
406
    [if(class==menu-expand){exp}]   has a sub-menu
407
    [if(class==menu-first){exp}]    is first item in a menu
408
    [if(class!=menu-first){exp}]    is NOT first item in a menu
409
    [if(class==menu-last){exp}]     is last item in a menu
410
    [if(level==0){exp}]             is at the root
411
    [if(level>0){exp}]              is not at the root
412
    [if(sib==2){exp}]               is the second item in a menu
413
    [if(sibCount>1){exp}]           is in a menu with more than 1 entry
414
    [if(sibCount!=2){exp}]          is in a menu which doesn't have exactly
415
    [if(level>parent){exp}]         is in a sibling menu or child of a sibling
416
    [if(id==parent){exp}]           is the parent of the current page
417
418
If an else-clause was added, then the expression for the else would be
419
emitted in all other cases. For example the expression "foo" is emitted
420
whenever the if-test is false, so therefore:
421
422
    [if(sib==2){exp}else{foo}]          is NOT the second item in a menu
423
    [if(sibCount>2){exp}else{foo}]      is NOT in a menu with more than 2 entries
424
425
For multiple tests, the expression "exp" is emitted only when the menu item:
426
427
    [if(sib == 1 || sib > 3){exp}]
428
        [is the first item] OR [is the 4th or larger item] in the menu
429
430
    [if(id == current && class == menu-expand){exp}
431
        [is the current item] AND [it has children]
432
433
Note that all tests are evaluated in the order listed because:
434
 * there is no short-circuit evaluation (all individual tests are always evaluated)
435
 * there is no grouping of tests (i.e. no support for parenthesis)
436
 * both || and && are considered the same level
437
438
439
440
FORMATTER
441
=========
442
Note: This is an advanced and rarely needed feature!
443
444
If you are capable of extensive PHP programming, it is possible to replace the
445
predefined menu formatter that show_menu2 is uses with a custom module. See the
446
include.php file of show_menu2 for an example of how the menu formatter must be
447
written. The API it must use is:
448
449
class SM2_Formatter
450
{
451
    // called once before any menu is processed to allow object initialization
452
    function initialize() { }
453
454
    // called to open the menu list
455
    function startList($aPage, $aUrl) { }
456
457
    // called to open the menu item
458
    function startItem($aPage, $aUrl, $aCurrSib, $aSibCount) { }
459
460
    // called to close the menu item
461
    function finishItem() { }
462
463
    // called to close the menu list
464
    function finishList() { }
465
466
    // called once after all menu has been processed to allow object finalization
467
    function finalize() { }
468
469
    // called once after finalize() if the SM2_NOOUTPUT flag is used
470
    function getOutput() { }
471
};
472
473