Fetch-Aliase #

fetch_alias() ruft eine Fetch-Funktion über einen Kurznamen auf, der in der fetchalias.ini definiert ist; einige ihrer Parameter sind dabei fest vorgegeben, andere umbenannt. {fetch_alias( 'children', hash( 'parent_node_id', 89 ) )} entspricht {fetch( 'content', 'list', hash( 'parent_node_id', 89, ... ) )} mit den Einstellungen des Alias. Der Operator gehört zu eZTemplateExecuteOperator (lib/eztemplate/classes/eztemplateexecuteoperator.php, dieselbe Klasse wie fetch), und die Arbeit erledigt eZFunctionHandler::executeAlias() (lib/ezutils/classes/ezfunctionhandler.php).

Inhalt #

1. Syntax
2. fetchalias.ini
3. Wie Parameter und Konstanten zusammenwirken
4. Die definierten Aliase
5. Einen eigenen Alias anlegen
6. Einen vorhandenen Alias ändern
7. Wann sich ein Alias lohnt

Syntax #

{fetch_alias( alias_name, hash( key, value, ... ) )}

Er nimmt keine Eingabe über die Pipe und gibt zurück, was die Fetch-Funktion zurückgibt (null, wenn der Alias nicht existiert).

fetchalias.ini #

Jeder Alias ist ein Abschnitt. Die settings/fetchalias.ini des Kernels dokumentiert die Schlüssel:

# [<parameter>]         # name of first parameter in fetch_alias
# Module=          # which module to use
# FunctionName=    # name of function defined in kernel/<module>/function_definition.php
# Parameter[key]=<value>  # key is the name of the parameter defined for the function in kernel/<module>/function_definition.php
#                         # value is the key of the hash entry in fetch_alias
# Constant[key]=<value>   # key is the name of the parameter defined for the function in kernel/<module>/function_definition.php
#                         # value is a constant defined in this ini file. use ; to separate elements if the value is supposed to be an array

• Module und FunctionName benennen die Fetch-Funktion, genau wie die ersten beiden Argumente von fetch().
• Parameter[<Funktionsparameter>]=<Alias-Schlüssel> nimmt den Wert von <Alias-Schlüssel> aus dem übergebenen Hash und gibt ihn an <Funktionsparameter> weiter. Meist sind beide Namen gleich, ein Alias kann sie aber umbenennen: [object] bildet den Funktionsparameter object_id auf den Schlüssel id ab.
• Constant[<Funktionsparameter>]=<Wert> legt einen Wert fest. Ist der Funktionsparameter in der function_definition.php des Moduls vom Typ array, wird der Wert an ; aufgeteilt (schreiben Sie \; für ein Semikolon innerhalb eines Elements; leere Elemente entfallen, eZFunctionHandler::constantList()): Aus Constant[sort_by]=published;0 wird array( 'published', '0' ).

Wie Parameter und Konstanten zusammenwirken #

eZFunctionHandler::executeAlias() stellt die Parameter der Fetch-Funktion in dieser Reihenfolge zusammen:

1. jeder Parameter[]-Eintrag: der Wert seines Alias-Schlüssels aus Ihrem Hash oder null, wenn Sie ihn nicht übergeben haben (ein Parameter mit null erhält dann den Standardwert der Funktion);
2. jeder Constant[]-Eintrag, es sei denn, Ihr Hash enthält einen Schlüssel mit dem Namen des Funktionsparameters, der dann Vorrang vor der Konstanten hat;
3. jeder weitere Schlüssel Ihres Hashs, unverändert unter seinem eigenen Namen weitergereicht.

Sie können einem Alias also jeden Parameter der Fetch-Funktion übergeben, auch solche, die der Alias nicht nennt, und seine Konstanten überschreiben. Der Alias subtree sortiert nach priority;0; ein sort_by im Hash ersetzt das:

{* subtree has Constant[sort_by]=priority;0 - a sort_by given to the alias replaces it *}
{foreach fetch_alias( 'subtree', hash( 'parent_node_id', 144, 'limit', 3, 'sort_by', array( 'name', true() ) ) ) as $item}
- {$item.name|wash}

{/foreach}

Ausgabe:

- Almond French Toast
- Avocado Kale Pesto Grilled Cheese
- Gluten-Free Shrimp Pad Thai with Tofu

Kompilierte Templates nehmen für fetch_alias-Aufrufe, deren Aliasname eine Konstante ist, einen anderen Weg (eZTemplateExecuteOperator::fetchTransform()): Der Aufruf wird beim Kompilieren anhand der Parameterliste der Funktion in PHP umgewandelt. Alle Beispiele auf dieser Seite lieferten auf einer Entwicklungsinstallation interpretiert und kompiliert dasselbe Ergebnis. Halten Sie sich an die dokumentierte Verwendung (Alias-Schlüssel aus Parameter[], Namen der Funktionsparameter für alles andere), dann stimmen beide Wege überein.

Die definierten Aliase #

Der Siteaccess site einer Entwicklungsinstallation hat die acht Aliase aus der settings/fetchalias.ini des Kernels und zwei aus der Erweiterung xrowextract (extension/xrowextract/settings/fetchalias.ini.append.php).

Die Parameter der Fetch-Funktionen sind unter den Fetch-Funktionen von content dokumentiert.

object #

{def $node = fetch( 'content', 'node', hash( 'node_id', 89 ) )
     $object = fetch_alias( 'object', hash( 'id', $node.contentobject_id ) )}
{$object.id}: {$object.name|wash} ({$object.class_identifier})

Ausgabe:

87: Fit & Healthy (ng_frontpage)

children und children_count #

{def $children = fetch_alias( 'children', hash( 'parent_node_id', 89,
                                                 'sort_by', array( 'name', true() ),
                                                 'limit', 5 ) )}
{fetch_alias( 'children_count', hash( 'parent_node_id', 89 ) )} children, the first {$children|count} by name:
{foreach $children as $child}
- {$child.name|wash} ({$child.class_identifier})

{/foreach}

Ausgabe:

16 children, the first 5 by name:- Authors (ng_container)
- Contact (ng_contact_form)
- Cookie Policy (ng_article)
- Fit & Healthy site info - [SITEINFO] (ng_site_info)
- Fitness (ng_landing_page)

subtree #

Knoten 144 ist die Kategorie Recipes; subtree geht beliebig tief und sortiert nach Priorität:

{def $page = fetch_alias( 'subtree', hash( 'parent_node_id', 144, 'offset', 0, 'limit', 4 ) )}
{foreach $page as $item}
- {$item.name|wash} (depth {$item.depth})

{/foreach}

Ausgabe:

- Gluten-Free Shrimp Pad Thai with Tofu (depth 4)
- Vegan Granola with Almonds, Walnuts, Cranberries, and Goji Berries (depth 4)
- Zucchini Zoodles with Ground Turkey Tomato Sauce (depth 4)
- Kale Salad (depth 4)

news_list #

Bei news_list ist die ganze Abfrage fest vorgegeben: Artikel der Klasse 2 unterhalb von Knoten 2. Auf einer Entwicklungsinstallation existiert die Klasse 2, die Artikel der Website sind aber von der Klasse ng_article, daher findet der Alias nichts. Er ist ein Beispiel aus den ursprünglichen Kernel-Einstellungen, auf das Sie sich nicht verlassen sollten; definieren Sie stattdessen einen eigenen (siehe unten).

{def $class = fetch( 'content', 'class', hash( 'class_id', 2 ) )
     $news = fetch_alias( 'news_list' )}
Class 2 is "{$class.identifier}"; news_list returned {$news|count} item(s).
{foreach $news as $item}
- {$item.name|wash}

{/foreach}

Ausgabe:

Class 2 is "article"; news_list returned 0 item(s).

by_identifier #

content/object_by_attribute (eZContentFunctionCollection::fetchObjectByAttribute()) gibt über eZContentObjectAttribute::fetchByIdentifier() das Objekt zurück, das ein Textzeilen-Attribut (ezstring) hat, dessen Sortierschlüssel dem Wert entspricht. Der Sortierschlüssel einer Textzeile ist ihr Text in Kleinbuchstaben:

{def $node = fetch( 'content', 'node', hash( 'node_id', 90 ) )
     $found = fetch_alias( 'by_identifier', hash( 'attr_id', $node.name|downcase ) )}
Looked up "{$node.name|downcase|wash}": {if $found}object {$found.id}, {$found.name|wash}{else}nothing{/if}

Ausgabe:

Looked up "privacy policy": object 72, Privacy policy

Passen mehrere Objekte, gibt er eines davon zurück. Er durchsucht alle Textzeilen-Attribute aller Klassen; verwenden Sie ihn daher nur mit Werten, von denen Sie wissen, dass sie eindeutig sind.

comments und reviews #

Beide listen die Unterelemente einer Klasse (comment, review), die neuesten zuerst. Auf einer Entwicklungsinstallation wird keine der beiden Klassen unterhalb von Knoten 89 verwendet:

{def $comments = fetch_alias( 'comments', hash( 'parent_node_id', 89 ) )
     $reviews = fetch_alias( 'reviews', hash( 'parent_node_id', 89 ) )}
comments: {$comments|count}, reviews: {$reviews|count}

Ausgabe:

comments: 0, reviews: 0

xrowextract_recent_content und xrowextract_by_section #

Von der Erweiterung xrowextract für ihre Exportansicht definiert und in jedem Template der Siteaccesses verwendbar, in denen die Erweiterung aktiv ist:

{def $recent = fetch_alias( 'xrowextract_recent_content', hash( 'parent_node_id', 144, 'limit', 3 ) )}
{foreach $recent as $item}
- {$item.name|wash}

{/foreach}

Ausgabe:

- Zucchini Zoodles with Ground Turkey Tomato Sauce
- Vibrant Guacamole
- Vegan Granola with Almonds, Walnuts, Cranberries, and Goji Berries

Ein Alias, der nicht existiert #

[{fetch_alias( 'latest_news', hash( 'parent_node_id', 89 ) )}]

Ausgabe:

[]

Das Ergebnis ist leer. In einem interpretierten Template schreibt eZFunctionHandler::executeAlias() die Warnung Could not execute. Function latest_news not found. in die Debug-Ausgabe; ein kompiliertes Template protokolliert beim Kompilieren die Template-Warnung Fetch alias 'latest_news' is not defined in fetchalias.ini.

Einen eigenen Alias anlegen #

Legen Sie den Abschnitt in der settings/fetchalias.ini.append.php Ihrer Erweiterung (oder eines Siteaccess) an, niemals in der settings/fetchalias.ini des Kernels:

<?php /* #?ini charset="utf-8"?

[c11_latest_articles]
Module=content
FunctionName=list
Parameter[parent_node_id]=parent
Parameter[limit]=limit
Constant[sort_by]=published;0
Constant[class_filter_type]=include
Constant[class_filter_array]=ng_article

*/ ?>

Die INI-Dateien aller aktiven Erweiterungen werden zusammengeführt, daher existiert der Alias in jedem Siteaccess, in dem die Erweiterung aktiv ist. Leeren Sie danach den INI-Cache (php bin/php/ezcache.php --clear-tag=ini --allow-root-user) und den Template-Cache (kompilierte Templates enthalten die aufgelösten Parameter des Alias):

{foreach fetch_alias( 'c11_latest_articles', hash( 'parent', 89, 'limit', 3 ) ) as $article}
- {$article.name|wash}, published {$article.object.published|l10n( 'shortdate' )}

{/foreach}

Ausgabe:

- Cookie Policy, published 01/25/2023
- Privacy Policy, published 01/25/2023

Auf einer Entwicklungsinstallation nicht mit einer Datei ausgeführt: Das Skript, das dieses Beispiel gerendert hat, fügte den obigen Abschnitt nur im Speicher und nur für seinen eigenen Prozess zur fetchalias.ini hinzu.

Versehen Sie Aliasnamen mit dem Präfix Ihrer Erweiterung: Aliasnamen teilen sich über alle Erweiterungen hinweg einen INI-Namensraum.

Einen vorhandenen Alias ändern #

Eine Append-Datei, die einen vorhandenen Abschnitt nennt, wird Schlüssel für Schlüssel mit ihm zusammengeführt; sie ersetzt den Abschnitt nicht. Um die Sortierreihenfolge des Kernel-Alias children zu ändern, braucht eine Erweiterung nur:

[children]
Constant[sort_by]=name;1

children hat kein eigenes Constant[sort_by] (es nimmt sort_by aus Ihrem Hash), daher gilt die Konstante, wenn das Template kein sort_by übergibt. Ohne die Änderung sortiert content/list ohne sort_by nach dem Pfad der Knoten (path_string aufsteigend, der Standard von eZContentObjectTreeNode::createSortingSQLStrings()):

{foreach fetch_alias( 'children', hash( 'parent_node_id', 89, 'limit', 4 ) ) as $child}
- {$child.name|wash}

{/foreach}

Ausgabe:

- Privacy Policy
- Cookie Policy
- Fitness
- Healthy eating

Mit der Änderung sortiert dasselbe Template nach Namen:

{foreach fetch_alias( 'children', hash( 'parent_node_id', 89, 'limit', 4 ) ) as $child}
- {$child.name|wash}

{/foreach}

Ausgabe:

- Authors
- Contact
- Cookie Policy
- Fit & Healthy site info - [SITEINFO]

(Gerendert mit der Änderung im Speicher, wie im vorigen Beispiel.) Das Risiko ist dasselbe wie bei jeder gemeinsam genutzten Einstellung: Jedes Template des Siteaccess, das children verwendet, erhält nun das neue Verhalten, auch Templates anderer Erweiterungen. Ein Array-Schlüssel (Parameter[...], Constant[...]) lässt sich durch eine Append-Datei nicht entfernen, nur ersetzen; eine Zeile Constant[] mit leeren Klammern würde die ganze Liste leeren. Legen Sie lieber einen neuen Alias mit eigenem Namen an.

Wann sich ein Alias lohnt #

• Für eine Abfrage, die in vielen Templates einer Website verwendet wird: Ihre festen Teile lassen sich an einer Stelle ändern.
• Nicht, um teure Abfragen zu verbergen: Ein Alias führt bei jedem Aufruf genau den Fetch aus, den er nennt (setzen Sie den Aufruf in einen cache-block, wenn sein Ergebnis geteilt werden kann).
• Nicht für eine Abfrage, die nur einmal vorkommt: fetch() mit allen Parametern ist leichter zu lesen.

Verwandte Seiten #

• Wie Fetch-Funktionen arbeiten
• Execute-Operatoren: fetch und fetch_alias als Operatoren
• Grundlagen von fetch
• Die Referenz der Fetch-Funktionen
• Freie Dokumentation: Diese Seite darf unter der GNU FDL 1.3 frei kopiert, übersetzt und verbessert werden.