show_menu2, version 4.9
=======================
Ist ein Code-Snippet für das CMS Website Baker. Es stellt einen kompletten
Ersatz für die eingebaute Menüfuntionalität zur Verfügung. Alle, für die
Erzeugung des Menüs erforderlichen Daten, werden durch eine einzige
Datenbankabfrage erzeugt. Durch umfangreiche Anpassungsmöglichkeiten des
erzeugten HTML-Code können alle möglichen Menüarten (Listen, Breadcrumbs,
Sitemaps, usw.) erzeugt werden.
---
Deutsche Übersetzung von BerndJM. Dies ist eine weitgehend direkte Übersetzung
des englischen Originals. Bei Übersetzungs- oder Interpretationsfehlern, bitte
eine Email an bjm@wwnw.de.
---
INSTALLATION
============
1. Die aktuelle Version von http://code.jellycan.com/show_menu2/ herunterladen.
2. In das Admin-Backend der Website Baker Installation einlogen.
3. Erweiterungen -> Module aufrufen.
4. Wenn bereits eine frühere Version von show_menu2 installiert ist, diese über
"Modul deinstallieren" auswählen und deinstallieren.
5. Im Abschnitt "Modul installieren" das im Schritt 1 heruntergeladene zip-File
auswählen und installieren.
BENUTZUNG VON SHOW_MENU2
========================
Um show_menu2 zu benutzen muss das verwendete Template an den Stellen
modifiziert werden, an denen das Menü erscheinen soll. Bitte beachten: Wenn alte
Menüaufrufe ersetzt werden, müssen unbedingt auch die entsprechenden neuen
Parameter verwendet werden die show_menu2 benötigt.
In den meisten Fällen genügt bereits der Standardaufruf ohne weitere Parameter
von show_menu2. In diesem Fall werden die Vorgabewerte verwendet, dies erzeugt
ein Menü das die aktuelle Seite und die Unterseiten der aktuellen Seite anzeigt:
$sMenu = show_menu2();
Bitte beachten: der Aufruf von show_menu2 ist PHP und muss normalerweise in PHP-
Codezeichen eingeschlossen werden (ausser der Aufruf erfolgt bereits innerhalb
von PHP Code):
Dieses Vorgabe Menü erzeugt bereits ein komplettes Menü auf Listenbasis mit
etlichen Klassen, die eine leichte Formatierung mittels CSS ermöglichen. Es wird
z.B. die Klasse "menu-current" zu dem tag des aktuellen Menüpunktes
hinzugefügt. Zusätzlich erhält jeder Menüpunkt der Unterpunkte enthält die
Klasse "menu-expand". Das erlaubt es sehr differenzierte CSS Regeln für die
einzelnen Menüpunkte aufzustellen.
Zum Beispiel:
li.menu-expand { font-weight: bold; }
li.menu-current { background: red; }
Im Abschnitt "HTML-Ausgabe" findet sich eine detaillierte Beschreibung welche
Klassen welchem Element zugeordnet werden. Durch die Verwendung von
verschiedenen Parametern bei dem show_menu2 Funktionsaufruf lassen sich auch
recht umfangreiche und unterschiedliche Menüstrukturen erzeugen. Um
beispielsweise nur Menüpunkte aus der obersten Ebene der Menüstruktur
darzustellen, könnte man folgenden Aufruf verwenden:
$sMenu = show_menu2(0, SM2_ROOT, SM2_START);
Oder um beispielsweise bis zu zwei Unterebenen der aktuellen Seite anzuzeigen:
$sMenu = show_menu2(0, SM2_CURR+1, SM2_CURR+2);
Es gibt jede Menge Möglichkeiten, um die unterschiedlichsten Menüstrukturen zu
erzeugen. Zahlreiche Beispiele dazu findet man auf der Demo-Website: http://
code.jellycan.com/sm2test/
HÄUFIGE FRAGEN
==============
Q: Ich bin kein Programmierer. Gibt es keine einfachere Dokumentation?
A: Nein, denn dies hier ist bereits die einfache Dokumentation.
Q: Wie kann ich ein sogenanntes Drop-Down Menü erstellen?
A: Dies hat nichts mit show_menu2 zu tun. Um ein Drop-Down Menü zu erzeugen muß
lediglich der CSS-Code des jeweiligen Templates angepaßt werden. Die nötigen
Anpassungen findet man z.B. im "allcss2" Template aus dem WB Addon
Repository -> http://addons.websitebaker.org/
Q: Warum verschwindet das Menü nachdem ich in einer mehrsprachigen WB-Site die
Suchfunktion benutzt habe?
A: Im verwendeten Template fehlen die notwendigen Zeilen:
1. Im WB Admin Backend: Optionen -> Erweiterte Optionen anzeigen ->
Suchoptionen -> Kopfzeile - hier direkt nach dem öffnenden ' verwendet.
$aMenuOpen
Mit diesem Formatstring wird eine Liste von Menüeinträgen geöffnet. Für das erste
Menü kann mittels $aTopMenuOpen ein davon abweichender Formatstring definiert
werden.
Wenn dieser Parameter auf false gesetzt ist wird der Vorgabewert '[ul]'
verwendet.
$aMenuClose
Dieser String schließt jedes Menü ab.
Bitte beachten: dies ist kein Formatstring und es werden keine Schlüsselworte
ersetzt!
Wenn dieser Parameter auf false gesetzt ist, wird die Vorgabe '' verwendet.
$aTopItemOpen
Der Formatstring für den allerersten Menüpunkt. Wenn dieser Parameter auf false
gesetzt wird, wird der selbe Formatstring wie bei $aItemOpen verwendet.
$aTopMenuOpen
Der Formatstring für das erste Menü. Wenn dieser Parameter auf false
gesetzt wird, wird der selbe Formatstring wie bei $aMenuOpen verwendet.
ERWEITERTE OPTIONEN
===================
Der Parameter $aOptions kann auf zweierlei Arten verwendet werden. Zum einen, wie oben
im Abschnitt PARAMETER beschrieben, diese Art sollte für die allermeisten
Anwendungsfälle ausreichen. Um allerdings in speziellen Fällen die Sonderoptionen
ansprechen zu können, müssen die erforderlichen Werte als assoziatives Array
bereitgestellt werden.
Bitte beachten: Die SM2_* Flags sind auch hierbei erforderlich und müßen als 'flags'
übergeben werden.
'flags' **ZWINGEND ERFORDELICH** Dies sind die Flags die oben im Abschnitt
PARAMETER unter $aOptions beschrieben wurden.
'notrim' Hiermit wird eine Anzahl von Ebenen festegelegt, die relativ bezogen
auf die in $aStart festgelegte Menüebene, immer angezeigt werden. Dies
bewirkt, daß für diese Ebenen das SM2_TRIM Flag ignoriert wird.
Um dieses Array zu verwenden, empfiehlt es sich es erst anzulegen und dann den
$aOptions parameter mit dem angelegten Array zu beliefern:
$options = array('flags' => (SM2_TRIM|...), 'notrim' => 1);
$sMenu = show_menu2(0, SM2_ROOT, SM2_CURR+1, $options);
FORMAT STRINGS
==============
Die folgenden Tags können in den Formatstrings für $aItemOpen und $aMenuOpen
verwendet werden und sollen durch den entsprechenden Text ersetzt werden.
[a] tag ohne Klasse: ''
[ac] tag mit Klasse: ''
[li] tag mit Klasse: ''
[ul] tag mit Klasse: ''
[class] Liste der Klassen für diese Seite
[menu_title] Text des Menütitel
(HTML entity escaped ausser das SM2_NOESCAPE Flag ist gesetzt)
[menu_icon_0] die URL zu einer Bilddatei mit normal - Darstellung (ab WB2.8.4)
[menu_icon_1] die URL zu einer Bilddatei mit active/hover - Darstellung (ab WB2.8.4)
[page_title] text des Seitentitel
(HTML entity escaped ausser das SM2_NOESCAPE Flag ist gesetzt)
[page_icon] die URL zu einer seitenbezogenen Bilddatei (ab WB2.8.4)
[tooltip] Tooltip-Text, der normal im title-Attribut der Links ausgegeben wird (ab WB2.8.4)
[url] die URL der Seiten für den tag
[target] das Seitenziel für den tag
[page_id] die Page ID des aktuellen Menüpunktes.
[parent] die Page ID des übergeordneten Menüpunktes.
[level] die Seitenebene,
dies ist die gleiche Zahl die im "menu-N" CSS tag verwendet wird.
[sib] Anzahl der Geschwister des aktuellen Menüpunktes.
[sibCount] Anzahl aller Geschwister in diesem Menü.
[if] Bedingung (Details hierzu im Abschnitt "Bedingte Formatierung')
Folgende tags sind NUR verfügbar, wenn das SM2_ALLINFO Flag gesetzt ist.
[description] Seitenbeschreibung
[keywords] Schlüsselworte der Seite
BEDINGTE FORMATIERUNG
=====================
Die Anweisung für eine bedingte Formatierung kann eine der folgenden Formen haben:
[if(A){B}]
[if(A){B}else{C}]
A Die Bedingung. Details dazu, siehe unten.
B Der Ausdruck der verwendet wird, wenn die Bedingung erfüllt ist.
Dies kann ein beliebiger String sein, der jedoch nicht das Zeichen '}'
enthalten darf. Er kann jeden beliebigen Formatstring aus dem Abschnitt
'Format Strings' enthalten, jedoch keinen weiteren Bedingungstest (da das
Zeichen '}' nicht erlaubt ist).
C Der Ausdruck der verwendet wird, wenn die Bedingung nicht erfüllt ist.
Dies kann ein beliebiger String sein, der jedoch nicht das Zeichen '}'
enthalten darf. Er kann jeden beliebigen Formatstring aus dem Abschnitt
'Format Strings' enthalten, jedoch keinen weiteren Bedingungstest (da das
Zeichen '}' nicht erlaubt ist).
Die Bedingung ist eine Kombination von einem oder mehreren boolschen Vergleichen.
Wenn mehr als ein Vergleich erforderlich ist, so muss dieser mit den anderen Vergleichen
mittels || (boolsches oder - OR) oder && (boolsches und - AND) verknüpft werden.
Ein einzelner Vergleich besteht aus dem linken Operanden, dem Operator und dem rechten
Operanden.
z.B. X == Y - hierbei ist X der linke Operand, == der Operator und Y der rechte Operand.
Linker Operand. Muss eines der folgende Schlüsselworte sein:
class Überprüfung ob diese Klasse existiert. Es sind nur die
"==" and "!=" Operatoren erlaubt. In diesem Fall haben die Operatoren
die Bedeutung von "enthält" bzw. "enthält nicht" an Stelle von
"ist gleich" bzw. "ist nicht gleich"
level Überprüfung der Seitenebene.
sib Überprüfung der Geschwisteranzahl der aktuellen Seite.
sibCount Überprüfung der Geamtanzahl der Geschwister im aktuellen Menü.
id Überprüfung der page id.
target Überprüfung der Target-Angabe
Operator. Muss einer der folgenden sein:
< Kleiner als
<= Kleiner oder gleich als
== Gleich
!= Nicht gleich
>= Grössr oder gleich als
> Grösser als
Rechter Operand. Die Art dieses Operanden hängt von dem, für den linken Operanden
verwendeten Schlüsselwort ab.
class einer der "menu-*" Klassennamen wie sie im Abschnitt "Ausgabe"
spezifiziert sind.
level Überprüfung der Seitenebene gegen folgende Werte:
die absolute Seitenebene
root die oberste Seitenebene
granny die Seitenebene über der übergeordneten Seitenebene
parent die übergeordnete Seitenebene
current die aktuelle Seitenebene
child die untergeornete Seitenebene
id Überprüfung der page id gegen folgende Werte:
die absolute page id
parent die übergeordnete page id
current die aktuelle page id
sib Eine positive Integerzahl, oder "sibCount" um die Anzahl der
Geschwister in diesem Menü zu überprüfen
sibCount Eine positive Integerzahl
target Ein String, der eine mögliche Targetangabe darstellt
Folgende Beispiele ergeben "wahr" und der Ausdruck {exp} wird ausgeführt, wenn zutrifft:
[if(class==menu-expand){exp}] hat ein Untermenü
[if(class==menu-first){exp}] ist der erste Eintrag in einem Menü
[if(class!=menu-first){exp}] ist NICHT der erste Eintrag in einem Menü
[if(class==menu-last){exp}] ist der letzte Eintrag in einem Menü
[if(level==0){exp}] befindet sich auf der obersten Ebene
[if(level>0){exp}] befindet sich NICHT auf der obersten Ebene
[if(sib==2){exp}] ist der zweite Eintrag in einem Menü
[if(sibCount>1){exp}] ist in einem Menü mit mehr als einem Eintrag
[if(sibCount!=2){exp}] ist in einem Menü, das nicht genau 2 Einträge hat
[if(level>parent){exp}] ist in einem Geschwistermenü oder dem Untermenü eines
Geschwistermenüs
[if(id==parent){exp}] ist der übergeordnete Punkt der aktuellen id
[if(target==_self){exp}] im Target-Attribut ist der String '_self' enthalten
Wenn eine sonst-Klausel (else) hinzugefügt wird, so wird diese in allen anderen Fällen
ausgeführt.
Zum Beispiel wird "foo" immer dann ausgeführt, wenn die if Überprüfung falsch ergibt, also:
[if(sib==2){exp}else{foo}] ist NICHT der zweite Eintrag im Menü
[if(sibCount>2){exp}else{foo}] ist NICHT in einem Menü mit mehr als zwei Einträgen
Bei mehrfach Vergleichen wird der Ausdruck "exp" nur ausgeführt, wenn:
[if(sib == 1 || sib > 3){exp}] ist der erste Eintrag ODER ist der vierte oder höhere
Eintrag im Menü
[if(id == current && class == menu-expand){exp} ist der aktuelle Eintrag UND hat
Untermenüs
Bitte beachten:
Alle Überprüfungen werden in der Reihenfolge ausgeführt, in der sie notiert sind, denn:
* es findet keine Überprüfung auf evtl. Schleifen statt (alle Überprüfungen werden immer ausgeführt)
* Überprüfungen werden nicht gruppiert (eine Klammerung von Überprüfungen wird nicht unterstützt)
* sowohl || als auch && haben die gleiche Wertigkeit
FORMATTER
=========
Achtung: dies ist ein fortgeschrittenes und äusserst selten benötigtes Feature!
Mit umfangreichen Kenntnissen in der PHP Programmierung ist es möglich den vordefinierten
Formatierer von show_menu2 mit einem eigenen zu ersetzen.
In der include.php von show_menu2 sieht man wie der Formatierer geschreiben werden muss.
Die API, die verwendet werden muss, sieht wie folgt aus:
(Anmerkung des Übersetzers: Kommentare sind nicht übersetzt, wer sich so weit vorwagt, sollte
damit keine Probleme haben ;-)
class SM2_Formatter
{
// called once before any menu is processed to allow object initialization
function initialize() { }
// called to open the menu list
function startList($aPage, $aUrl) { }
// called to open the menu item
function startItem($aPage, $aUrl, $aCurrSib, $aSibCount) { }
// called to close the menu item
function finishItem() { }
// called to close the menu list
function finishList() { }
// called once after all menu has been processed to allow object finalization
function finalize() { }
// called once after finalize() if the SM2_NOOUTPUT flag is used
function getOutput() { }
};