1
|
// $Id: README 827 2008-04-14 18:54:58Z doc $
|
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
|
|
474
|
|