Menu-Bench V2.1 - Dokumentation

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Inhaltsverzeichnis

Einleitung
Funktionsweise
1. Navigationsstruktur
2. Ausgabe der Navigationselemente
Demo
Änderungen zu Vorversionen
Kontakt

1 Einleitung

Menu-Bench ist ein in PHP geschriebenes Skript zum automatischen Erzeugen von Menüs und Navigationsleisten. Die Navigationsstruktur wird an zentraler Stelle in einem als Baum organisierten Array abgelegt. Darin sind die auszugebenen Beschriftungen, die URLs der einzelnen Seiten und die Eltern-Kind-Beziehungen der Seiten zueinander gespeichert. Die folgenden Navigationselemente werden zur Zeit unterstützt:

Menüs und Menüleisten
Eltern-/Kind-Navigation
Vor-/Zurück-Navigation

Das Aussehen der Elemente wird durch Templates bestimmt und läßt sich daher leicht an eigene Bedürfnisse anpassen. Außerdem können die oft vernachlässigten LINK-Elemente im HEAD eines Dokuments generiert werden.

Das Archiv enthält folgende Dateien:

LICENSE: Eine Kopie der GNU Lesser General Public License V2.1, unter der dieses Skript lizensiert ist
LIESMICH.html: Die Datei, die Sie gerade lesen
menu-bench.php: Menu-Bench-Bibliothek
menu-bench-config.php: Konfigurations-Datei für die Demo
menu-bench-demo.css: Stylesheet der Demo
menu-bench-demo.php: Die Demo

Bei der vorliegenden Fassung handelt es sich um Version 2.1 vom 19.11.2006. Die jeweils aktuelle Version können Sie auf der Menu-Bench-Homepage herunterladen. Es wird PHP >= 4.1.0 benötigt. Das Skript wurde unter PHP 4.3.3 und PHP 5.1.4 mit den Laufzeit-Optionen register_globals off und allow_call_time_pass_reference off erfolgreich getestet.

2 Funktionsweise

Die Funktionalität läßt sich grob in zwei Bereiche aufteilen: Der Navigationsstruktur und der Ausgabe der Navigationselemente. Im Folgenden werden für jedes Konzept zunächst die zugrundeliegenden Datenstrukturen besprochen, im Anschluß daran werden die entsprechenden Bibliotheksfunktionen vorgestellt.

Die Funktionen sind in der Datei 'menu-bench.php' enthalten. Um diese zu nutzen, kopieren Sie die Datei in ein Verzeichnis innerhalb Ihres include-Pfades und binden Sie sie mittels include_once 'menu-bench.php'; ein.

2.1 Navigationsstruktur

Die Navigationsstruktur wird als Baum organisiert. Die darin enthaltenen Knoten (engl. nodes) entsprechen den einzelnen Seiten. Knoten sind als Arrays implementiert, eine einfache Seite enthält die folgenden Schlüssel-Wert-Paare:

'url': Die URL des Dokuments.
'label': Die Beschriftung des Menüpunktes.
'title': Der Titel des Links.

Sollen einem Knoten weitere Seiten untergeordnet werden, so werden diese unter dem Schlüssel 'children' als Array abgelegt. Die folgenden optionalen Elemente dienen zur Organisation der Kind-Knoten:

'children': Das Array enthält weitere Knoten, welche die Unterseiten des Dokuments repräsentieren. Die Schlüssel können dabei frei gewählt werden. Ein solches Array wird im folgenden als Container bezeichnet.
'groups': Mit diesem optionalen Array lassen sich einzelne Menüpunkte innerhalb eines Menüs gruppieren. Das Array speichert unter Gruppenschlüsseln weitere Arrays, die alle zu einer Gruppe gehörenden Knotenschlüssel als Werte enthalten.
'groups_labels': In dem optionalen Array sind die Zwischenüberschriften zu den einzelnen Menügruppen unter dem Gruppenschlüssel als String abgelegt.

Die Wurzel des Baums entspricht einem Knoten, der nur dazu dient, die Seiten der Hauptebene aufzunehmen. Die weiter oben beschriebenen Elemente 'url', 'label' und 'title' sind hier deshalb überflüssig.

In Version 2.0 wurde als Wurzel direkt ein Container-Array verwendet, die erweiterten Grupperierungsfunktionen in Version 2.1 erfordern nun jedoch wie beschrieben einen Knoten. Nähere Informationen zum Update finden sind in dem Abschnitt Änderungen zu Vorversionen.

Ein Beispiel:

$root_node = array(
'children' => array(
	'start' => array(
		'url'		=> 'index.php',
		'label'		=> 'Startseite',
		'title'		=> 'Startseite der Homepage'
	),
	'hesse' => array(
		'url'		=> 'hesse.php',
		'label'		=> 'Hermann Hesse',
		'title'		=> 'Die besten Bücher von Hermann Hesse',
		'children'	=> array(
			'steppenwolf' => array(
				'url'		=> 'steppenwolf.php',
				'label'		=> 'Der Steppenwolf',
				'title'		=> 'Nur für Verrückte'),
			'narziss' => array(
				'url'		=> 'narziss.php',
				'label'		=> 'Narziß & Goldmund',
				'title'		=> 'Eine Reise im Mittelalter')
		)
	),
	'links' => array(
		'url'		=> 'links.php',
		'label'		=> 'Links',
		'title'		=> 'Weiterführende Links'
	)
)	// 'children'-Array wird geschlossen
);

Das Beispiel definert drei Seiten auf der Hauptebene: Startseite, Hermann Hesse und Links. Die Seite Hermann Hesse enthält außerdem die Unterseiten Der Steppenwolf und Narziß & Goldmund.

Um bestimmte Seiten innerhalb des Baums zu spezifizieren, werden Pfade (engl. pathes) benutzt. Diese sind als Arrays angelegt und enthalten die entsprechenden Knotenschlüssel von der Wurzel an aufwärts als Werte. Der Pfad zur Seite Steppenwolf sieht beispielsweise so aus:

array('hesse', 'steppenwolf')

Knoten auffinden

Um bestimmte Knoten der Navigationsstruktur zu finden, kann die Funktion menubench_find_node_ex() benutzt werden:

function &menubench_find_node_ex($path, &$rootnode)

Dieser werden der Pfad und der Wurzelknoten übergeben. Die Funktion liefert eine Referenz auf den entsprechenden Knoten zurück, oder NULL falls kein solcher vorhanden ist. Wird als Pfad ein leeres Array übergeben, wird der Wurzelknoten zurückgegeben.

Zur Abwärtskompatibilität sind zusätzlich noch die folgenden Funktionen enthalten, welche als Wurzel einen Container anstatt eines Knotens verwenden. Diese sollten in neueren Programmen jedoch nicht mehr benutzt werden.

function &menubench_find_node($path, &$container);: Liefert den benannten Knoten.
function &menubench_find_container($path, &$container);: Gibt zu dem benannten Knoten den Container mit den Kind-Knoten zurück.

2.2 Ausgabe der Navigationselemente

Die Ausgabe der Navigationselemente wird durch Templates gesteuert. Dabei handelt es sich um Arrays, in denen unter bestimmten Schlüsseln auszugebende Strings abgelegt sind. Für Menüs, Eltern-/Kind-Navigation und Vor-/Zurück-Navigation werden zum Teil verschiedene Elemente verwendet, die folgenden sind allen Templates gemein:

'prefix': String, der dem Navigationsbereich vorangestellt wird, z.B. ein öffnendes HTML-Element.
'postfix': String, der dem Navigationsbereich angehängt wird, z.B. ein schließendes HTML-Element.
'separator': String, der zwischen einzelnen Navigationselementen ausgegeben wird.

Die weiter unten angegebenen Zeichenketten für Menüpunkte etc. enthalten Formatierungsanweisungen in einer sprintf()-kompatibelen Syntax. Diese Formatierungsanweisungen dienen als Platzhalter, die beispielsweise durch die Beschriftung eines Menüpunktes ersetzt werden. Standardmäßig werden die folgenden Platzhalter durch die in den Knoten angegebenen Werte ersetzt:

%1$s: Wird durch den im Knoten unter 'url' abgelegten String ersetzt.
%2$s: Wird durch den String unter 'title' ersetzt.
%3$s: Wird durch den String unter 'label' ersetzt.

Sollen bestimmte Navigationselemente nicht ausgegeben werden, wie z.B. die "Anfang"- und "Ende"-Links oder der Menüpunkt des aktuellen Dokuments, so kann das entsprechende Template-Element einfach auf einen leeren String gesetzt werden.

Eine Sonderrolle nimmt das Template-Element 'html_encode' ein. Dabei handelt es sich nicht um eine auszugebende Zeichenkette, sondern um eine Anweisung, die Werte der Knoten vor der Ausgabe zu kodieren. Dabei werden die Zeichen &, < und > durch die HTML-Entity-Referenzen &, < und > ersetzt um eine gültige HTML-Ausgabe zu erzeugen. Als Wert für dieses Element muß die verwendete Zeichenkodierung als String angegeben werden. Ist es nicht gesetzt, wird keine Kodierung vorgenommen. Dieser Mechanismus wurde in Version 2.1 hinzugefügt.

Menüs

Templates für Menüs verwenden neben 'prefix', 'postfix', 'separator' und 'html_encode' diese zusätzlichen Elemente:

'item': Format-String für Menüpunkte mit den oben beschriebenen Platzhaltern.
'current_item': Format-String für den Menüpunkt des aktuellen Dokuments
'parent_item': Format-String für einen aktiven Menüpunkt einer höheren Hierarchie-Ebene
'group_prefix': Optionaler Format-String, der Menügruppen vorangestellt wird. Als einziger Platzhalter wird hier %1$s durch die Gruppenüberschrift ersetzt, die in dem Knoten unter 'group_labels' abgelegt ist. Ist keine Überschrift gegeben oder dieses Element nicht gesetzt, wird stattdessen 'prefix' verwendet.
'group_postfix': Wie 'group_prefix', jedoch wird der Format-String den Menügruppen angehängt.
'group_separator': Der optionale String wird zwischen Menügruppen eingefügt.

Eine einfache Linkliste kann z.B. mit dem folgenden Template erzeugt werden:

$list_template = array(
	'prefix'	=> '<ul>',
	'postfix'	=> '</ul>',
	'separator'	=> '',
	'item'		=> '<li><a href="%1$s" title="%2$s">%3$s</a></li>',
	'current_item'	=> '<li>%3$s</li>'
	'parent_item'	=> '<li><a href="%1$s" title="%2$s">%3$s</a></li>',
	'html_encode'	=> 'iso-8859-1'
);

Zur Ausgabe von Menüs dient die Funktion menubench_get_node_menu_ex(), die das Menü als String zurückgibt.

function &menubench_get_node_menu_ex($path, $menupath, &$rootnode, &$template)

$path: Der Pfad der aktuellen Seite
$menupath: Der Pfad des Knotens, dessen Unterseiten als Menü ausgegeben werden sollen
$rootnode: Der Wurzelknoten der Navigationsstruktur
$template: Das zu verwendende Template

Weiterhin sind die folgenden Funktionen definiert, welche entweder zur Abwärtskompatibilität enthalten sind oder intern benutzt werden. Diese werden im Normalfall nicht benötigt.

function &menubench_get_node_menu($path, $menupath, &$rootcontainer, &$template): Wie menubench_get_node_menu_ex(), es wird jedoch ein Container anstatt eines Knotens als Wurzel verwendet.
function &menubench_get_menu($current_page_key, &$pages, &$template, $active_template_key = 'current_item'): Gibt ein Menü als String zurück. Anders als bei den vorherigen Funktionen werden hier das Container-Array mit den auszugebenen Knoten und der Schlüssel des aktiven Elements darin direkt übergeben.
function menubench_menu($current_page_key, &$pages, &$template, $active_template_key = 'current_item'): Identisch mit vorangegangener Funktion, außer daß das Menü ausgegeben und nicht als String geliefert wird. Diese Funktion ist zur Rückwärtskompatibilität mit Version 1.0 enthalten.
function &menubench_get_group_menu($current_page_key, &$pages, &$amp;$groups, $grouptitles, &$template, $active_template_key = 'current_item'): Wie menubench_get_menu(), das Menü wird jedoch in Gruppen unterteilt. Die Gruppen und die Zwischenüberschriften werden in $groups und $grouptitles übergeben.

Der Parameter $active_template_key bestimmt, welches Template-Element für den aktiven Menüpunkt ausgegeben werden soll. Dies wird verwendet um z.B. die Hauptseite einer Kategorie in einer Unterseite klickbar zu machen. In diesem Fall würde dort 'parent_item' anstatt 'current_item' angegeben werden.

Eltern-/Kind-Navigation

Bei der Eltern-/Kind-Navigation wird der Pfad des aktuellen Dokuments von der Wurzel aufwärts mit den dazwischen liegenden Knoten ausgegeben. Dies kann, je nach Template, als reiner Text zur Information oder auch als klickbare Navigationsleiste erfolgen.

Neben 'prefix', 'postfix', 'separator' und 'html_encode' werden die Template-Elemente 'current_item' und 'parent_item' verwendet. Die Semantik der Elemente ist mit denen der Menü-Elemente identisch.

function &menubench_get_path_navigation_ex($path, &$rootnode, &$template): Liefert eine druckbare Navigationsleiste für den mit $path bezeichneten Knoten als String zurück
function &menubench_get_path_navigation($path, &$rootcontainer, &$template): Identisch mir vorheriger Funktion, es wird jedoch zur Abwärtskompatibilität ein Wurzelcontainer antstatt eines Wurzelknotens verwendet

Vor-/Zurück-Navigation

Folgende Schlüssel werden neben den Standardelementen 'prefix', 'postfix', 'separator' und 'html_encode' bei der Vor-/Zurück-Navigation verwendet:

'start': Format-String für den "Anfang"-Link
'end': Format-String für den "Ende"-Link
'next': Format-String für den "Weiter"-Link
'prev': Format-String für den "Zurück"-Link

Zur Ausgabe von Vor-/Zurück- und Anfang-/Ende-Links dient diese Funktion:

function &menubench_get_node_navigation_ex($path, &$rootnode, &$template): Liefert die Vor-/Zurück-Navigation für den mit $path angebenen Knoten als String.

Zur Abwärtskompatibilität sind noch die folgenden Funktionen enthalten:

function &menubench_get_node_navigation($path, &$rootcontainer, &$template): Wie menubench_get_node_navigation_ex(), es wird jedoch ein Container anstatt eines Knotens als Wurzelelement verwendet.
function &menubench_get_navigation($current_page_key, &$pages, &$template): Wie die vorangegangene Funktion, außer das hier direkt der Container und der Schlüssel der aktiven Seite übergeben wird.
function menubench_navigation($current_page_key, &$pages, &$template): Ist zur Rückwärtkompatibilität mit Version 1.0 enthalten und gibt die Navigationsleiste mit print aus.

Zusätzliche Knoten-Informationen in Templates verwenden

Um zusätzliche Informationen eines Knotens innerhalb der Templates verfügbar zu machen, können die verwendeten Schlüssel unter 'format_args' als Array abgelegt werden. Sollen z.B. zusätzliche URLs zu Grafiken in den Format-Strings genutzt werden, kann einem entsprechenden Template das Folgende hinzugefügt werden:

$template['format_args'] = array(
	'url',		// Die ersten drei sollten angegeben werden um das
	'title',	// Standardverhalten nachzubilden
	'label',
	'_image_url'	// Knotenwert '_image_url' als Platzhalter %4$s
);

Auf diese Weise lassen sich z.B. Menüpunkte auch mit Grafiken belegen. Um Namenskollisionen innerhalb der Knoten bei zukünftigen Menu-Bench-Versionen zu vermeiden, können benutzerdefinierte Werte mit einem Unterstrich versehen werden.

3 Demo

Die Datei 'menu-bench-config.php' enthält eine Beispielkonfiguration mit einer Navigationsstruktur sowie mehreren Templates. Die Templates verwenden zum Teil HTML-Klassen, die in dem externen Stylesheet 'menu-bench-demo.css' definiert werden. Die eigentliche Demo 'menu-bench-demo.php' bindet diese Dateien ein und demonstriert die Benutzung der Funktionen. Um die Demo in Aktion zu sehen, passen Sie bitte die Konstante SITE_PREFIX in der Datei 'menu-bench-config.php' an Ihre lokalen Gegebenheiten an. Der Wert wird über die Templates allen URLs vorangestellt. Kopieren Sie anschließend die angegebenen Dateien in ein Verzeichnis Ihres Webservers, und rufen Sie die Datei 'menu-bench-demo.php' auf.

Die Demo- und Config-Dateien können als Grundgerüst für Ihre eigenen Seiten dienen. Viel Spaß mit Menu-Bench!

4 Änderungen zu Vorversionen

Die vorliegende Version ist abwärtskompatibel zu Vorversionen. Für ein Upgrade kann die Datei 'menu-bench.php' einfach über die alte kopiert werden. Dennoch sind einige Änderungen vorhanden:

Version 2.1

Die Funktionen menubench_find_node_ex(), menubench_get_node_navigation_ex(), menubench_get_node_menu_ex(), menubench_get_group_menu() und menubench_get_path_navigation_ex() wurden hinzugefügt.
In Templates kann jetzt in 'html_encode' ein Zeichensatz angegeben werden. Ist dieser gesetzt, werden die Knoten-Werte automatisch mit der Funktion htmlspecialchars() kodiert.
Menü-Templates unterstützen nun die optionalen Elemente 'group_prefix', 'group_postfix' und 'group_separator'.
Die Demo-Templates und das Stylesheet wurden z.T. geändert.

Die neuen Funktionen mit dem Suffix _ex erwarten statt eines Wurzelcontainers einen Wurzelknoten. Um diese mit einer bisherigen Navigationsstruktur zu nutzen kann der Wurzel-Knoten wie folgt angelegt werden:

// bisheriger Wurzel-Container
$pages = array(
	'seite1'	=> // ...
	'seite2'	=> // ...
);

// neuer Wurzel-Knoten
$root_node = array('children' => &$pages);

Version 2.0

In der Navigationsstruktur sind die neuen Schlüssel 'label' und 'children' vorhanden. In Version 1.0 wird der Schlüssel 'title' für die Beschriftungen der Menüpunkte verwendet, in Version 2.0 jedoch 'label'. Werden alte Templates benutzt, wird auch weiterhin 'title' als Beschriftung angezeigt. Bei neuen Templates sollten die Beschriftungen jedoch in 'label' abgelegt werden.
Der Wert NULL sollte für Seitenschlüssel nicht mehr verwendet werden.

5 Kontakt

Aktuelle Informationen finden Sie auf der Menu-Bench-Homepage. Wenn Sie Fragen zu dem Skript stellen, oder einen Kommentar abgeben möchten, können Sie dies im Menu-Bench-Forum tun. Bitte geben Sie bei Problemen immer das Betriebssystem und die verwendeten PHP- und Skript-Versionen an.

Unterstützen Sie die Entwicklung weiterer, frei verfügbarer Skripte durch das Setzen eines Links auf http://www.internalscripts.de/. Vielen Dank!

Anschrift des Autors

Carsten Meier
Under de Diek 19
D-26757 Borkum
Deutschland

E-Mail: [cm at internalscripts dot de]
Fragen zur Benutzung des Skripts bitte im Forum stellen!