| << Wie sieht das in der Praxis aus? | Übersicht | Nachtrag >> |
Schnittstellen-Definition
Jede Modul-eigene Suchfunktion beginnt mit
function moduleX_search($func_vars) { extract($func_vars, EXTR_PREFIX_ALL, 'func'); ... }
Dabei richtet sich der Funktionsname nach dem Namen mit dem das Modul innerhalb Website Bakers bekannt ist. Das ist der Wert $module_directory aus der zum Modul gehörenden info.php-Datei. Für das wysiwyg-Modul muß die Funktion folglich wysiwyg_search() heißen, für das Downloadgallery-Modul download_gallery_search().
Beim Aufruf der Suchfunktion durch Website Baker wird als Parameter ein Array übergeben, das, nach Aufbrechen mit extract(), die folgenden Variabeln liefert, die innerhalb der Suchfunktion benutzt werden können.
| Variable | Type | Meaning |
|---|---|---|
| $func_database | (resource) | database-handle |
| $func_page_id | (str/int) | page_id der aktuellen Seite (wird seit Umstellung der Suche auf Abschnitte statt Seiten nicht mehr benötigt). |
| $func_section_id | (str/int) | section_id des aktuellen Abschnitts. Wird in allen SQL-Queries benötigt. |
| $func_page_title | (str) | Titel der Seite. Wird bei den Suchergebnissen als anklickbarer Link angezeigt. |
| $func_page_menu_title | (str) | Titel des Menu-Eintrags der Seite. Wird nicht verwendet. |
| $func_page_description | (str) | 'Description' der Seite (aus dem HTML-Meta-Tag). Wird bei den Suchergebnissen angezeigt. Manchmal ist es sinnvoller, einen eigenen String an print_excerpt2() zu übergeben. (Siehe auch: cfg_show_description) |
| $func_page_keywords | (str) | 'Keywords' der Seite (aus dem HTML-Meta-Tag). Wird nicht verwendet. |
| $func_page_link | (str) | WB-interner Link der Seite. Hieraus wird der Link in der Ergebnissliste erzeugt. Je nach Modul ist es besser, stattdessen einen eigenen String zu übergeben. (Entspricht dem Datenbankeintrag 'link' in der Tabelle 'pages') |
| $func_page_modified_when | (str/int) | Wann die Seite zuletzt bearbeitet wurde. Bei Seiten mit “Unterelementen” ist es sinnvoller, stattdessen das Änderungsdatum des Elements zu benutzten. (Enthält das Datum als Timestamp) |
| $func_page_modified_by | (str/int) | Von wem die Seite zuletzt geändert wurde. Siehe auch $func_page_modified_when. (Enthält die User-ID) |
| $func_users | (array) | interner Wert - Liste aller User |
| $func_search_words | (array) | interner Wert - Die vom User eingegebenen Suchbegriffe; grundsätzlich UTF-8 kodiert und für die Benutzung in einem Regulären Ausdruck vorbereitet. |
| $func_search_match | (str) | match-type, mögliche Werte: 'exact', 'any', 'all' |
| $func_search_url_array | (array) | Die vom User eingegebenen Suchbegriffe; grundsätzlich UTF-8 kodiert. ACHTUNG: die Strings in diesem Array sind nicht “gequotet”, sonder genau so, wie im Textfeld der Suche eingegeben. Sie können “aktives” Javascript, HTML oder Code für XSS oder SQL-Injection enthalten. Wenn der match-type=='exact' ist, enthält das Array nur ein Element, bestehend aus dem gesamten Eingabe-String. Der Name $func_search_url_array ist leider in mehrfacher Hinsicht irreführend - wird aber aus Gründen der kompatibilität beibehalten. |
| $func_results_loop_string | (str) | interner Wert |
| $func_default_max_excerpt | (int) | Zentrales Konfigurationselement. Die Anzahl auszugebender Zeilen Textauszug pro Seite. |
| $func_time_limit | (int) | [nur für Suche in externen Daten] Zeitlimit in Sekunden. Nach Überschreiten dieses Wertes soll die Suche abgebrochen werden. |
| $func_search_path | (str) | [nur für Suche in externen Daten] Einschränkung des Such-Pfades. Normalerweise nicht benötigt. |
Die Suchfunktion ruft ihrerseits die Funktion print_excerpt2() auf, und zwar in dieser Form:
print_excerpt2($mod_vars, $func_vars);
Dabei ist der zweite Parameter, $func_vars, das beim Aufruf der Suchfunktion übergebene Array, das unverändert weitergereicht wird. Der erste Parameter, $mod_vars, ist ebenfalls ein Array, das mit folgenden Schlüssel–Werte-Paaren gefüllt werden muß:
|
Key |
Meaning |
|---|---|
|
page_link |
Hieraus wird der Link erstellt, der in der Ergebnisliste zur Seite mit dem Such-Treffer führt. Kann entweder per 'page_link'⇒$func_page_link zugewiesen werden, oder durch einen eigenen Wert, wie z.B.: 'page_link'⇒$res['link'] |
|
page_link_target |
|
|
page_title |
Titel der Seite, in der Ergebnisliste als Link benutzt. Für gewöhnlich per 'page_title'⇒$func_page_title zugewiesen. |
|
page_description |
'description' aus den HTML-Meta-Tags. Wird als Untertitel in der Ergebnisliste benutzt. Für gewöhnlich als 'page_description'⇒$func_page_description zugewiesen. Es kann aber auch ein anderer String zugewiesen werden, wie .z.B. 'page_description'⇒$res['title'] beim News-Modul. Oder beim Event-Modul für das Datum des Events als Untertitel. (Siehe cfg_show_description) |
|
page_modified_when |
Für gewöhnlich per 'page_modified_when'⇒$func_page_modified_when zugewiesen. Bei “Unterelementen” sollte hier das Datum des Unterelements benutzt werden:, z.B.: 'page_modified_when'⇒$res['posted_when'] |
|
page_modified_by |
Für gewöhnlich per 'page_modified_by'⇒$func_page_modified_by zugewiesen. Bei “Unterelementen” sollte hier der User der Unterelement-Änderung benutzt werden:, z.B.: 'page_modified_by'⇒$res['posted_by'] |
|
text |
An diesen Schlüssel wird der gesamte zu durchsuchenden Text zugewiesen. Die Zuweisung geschieht durch anhängen aller Textteile: 'text'⇒$res['title'].$divider.$res['content_short'].$divider Wichtig ist, das die Teile durch $divider getrennt werden. Der Text muß nicht bereinigt werden (strip_tags() oder ähnliches) - darum kümmert sich die Funktion print_excerpt2(). |
|
max_excerpt_num |
Für gewöhnlich per 'max_excerpt_num'⇒$func_default_max_excerpt zugewiesen. |
|
pic_link |
Pfad zu einem bestehenden Thumbnail einer Gallery. Das Bild wird bei Gallery-Modulen als Thumbnail in der Ergebnisliste benutzt. Als Beispiel siehe das Modul “gallery”. Dieser Parameter ist optional. |
|
no_highlight |
'no_highlight' ⇒ true verhindert das highlighting. Optional. Im Normalfall sollte dieser Schlüssel nicht benutzt werden! |
|
ext_charset |
[ab WB2.7.1 / nur bei Abfrage einer externer Datenbank] Charset der externen Datenbank. Zur Zeit ist nur der Wert 'utf-8' möglich! |
Der Rückgabewert der Suchfunktion ergibt sich normalerweise aus dem Rückgabewert der Funktion print_excerpt2(). Ein Rückgabewert von true bedeutet, daß eine Übereinstimmung gefunden wurde, und daß eine Ausgabe auf der Ergebnisseite erfolgt ist. false bedeutet, das keine Übereinstimmung gefunden wurde.