Fetch-Funktionen #

Teil 3, Kapitel 14. fetch( 'content', 'list', ... ) ist eine Fetch-Funktion des Moduls content. Ihr Modul kann eigene anbieten: fetch( 'hello', 'newest', hash( 'class_identifier', 'article' ) ). Fetch-Funktionen sind der richtige Weg, Templates Daten zu geben, die PHP brauchen, ohne Logik in Templates zu legen. Die Engine sind eZFunctionHandler und eZModuleFunctionInfo (lib/ezutils/classes/).

Wo sie liegt #

Eine Fetch-Funktion gehört zu einem Modul, daher braucht Ihre Erweiterung einen Modulordner, der mit ExtensionRepositories[] registriert ist (Module und Views). Das Modul darf überhaupt keine Views haben; dann existiert es nur für seine Fetch-Funktionen.

extension/mysite_hello/
    modules/hello/function_definition.php
    classes/mysitehellofunctioncollection.php

function_definition.php #

<?php
$FunctionList = array();

$FunctionList['newest'] = array(
    'name' => 'newest',
    'call_method' => array( 'class' => 'mysiteHelloFunctionCollection',
                            'method' => 'fetchNewest' ),
    'parameters' => array(
        array( 'name' => 'class_identifier', 'type' => 'string', 'required' => true ),
        array( 'name' => 'parent_node_id', 'type' => 'integer', 'required' => false, 'default' => 2 ),
        array( 'name' => 'limit', 'type' => 'integer', 'required' => false, 'default' => 5 )
    )
);

Die Parameter werden der Methode in der aufgeführten Reihenfolge übergeben, über den Namen aus dem hash() des Templates zugeordnet; fehlende optionale Parameter erhalten ihren default. Die Datei modules/tags/function_definition.php der Erweiterung eztags ist ein größeres echtes Beispiel.

Die Collection-Klasse #

<?php
/**
 * Fetch functions of the module "hello":
 *   fetch( 'hello', 'newest', hash( 'class_identifier', 'article', 'limit', 3 ) )
 */
class mysiteHelloFunctionCollection
{
    public static function fetchNewest( $classIdentifier, $parentNodeID = 2, $limit = 5 )
    {
        $limit = max( 1, min( (int)$limit, 50 ) );
        $nodes = eZContentObjectTreeNode::subTreeByNodeID(
            array( 'ClassFilterType' => 'include',
                   'ClassFilterArray' => array( (string)$classIdentifier ),
                   'SortBy' => array( 'published', false ),
                   'Limit' => $limit ),
            (int)$parentNodeID
        );
        return array( 'result' => is_array( $nodes ) ? $nodes : array() );
    }
}

Die Methode gibt ein Array mit dem Schlüssel result zurück; die Engine reicht result an das Template weiter (eZModuleFunctionInfo::execute(): Fehlt der Schlüssel result, wird "did not return a result value" gemeldet). Geben Sie array( 'result' => false ) für "nichts gefunden" zurück, die Konvention, die die Collection von eztags verwendet. Bei geladenem Kernel mit Beispielinhalten aufgerufen, gab die Methode oben die drei neuesten Knoten der übergebenen Klasse zurück.

subTreeByNodeID() wendet die Leserechte des aktuellen Benutzers an, wie jede Inhaltsabfrage; damit tut das auch Ihre Funktion.

Verwendung #

{def $newest = fetch( 'hello', 'newest', hash( 'class_identifier', 'article', 'limit', 3 ) )}
{foreach $newest as $node}
    {node_view_gui content_node=$node view='line'}
{/foreach}
{undef $newest}

Fetch-Aliase #

fetchalias.ini gibt einem Fetch mit festen Parametern einen kurzen Namen, der mit fetch_alias() verwendet wird:

[newest_articles]
Module=hello
FunctionName=newest
Constant[class_identifier]=article
Constant[limit]=3

{def $newest = fetch_alias( 'newest_articles', hash() )}

Die Datei settings/fetchalias.ini des Kernels dokumentiert das Format und bringt Beispiele mit ([object], [news_list]).

Erweiterte Attributfilter #

Manchmal sind die Inhaltsabfragen (list, tree) die richtigen, brauchen aber eine zusätzliche SQL-Bedingung, zum Beispiel einen Join mit Ihrer eigenen Tabelle. Ein erweiterter Attributfilter fügt ihnen Tabellen, Joins und Spalten hinzu:

# extension/mysite_hello/settings/extendedattributefilter.ini.append.php
[MysiteRatedFilter]
ExtensionName=mysite_hello
FileName=classes/mysiteratedfilter.php
ClassName=mysiteRatedFilter
MethodName=createSqlParts

<?php
class mysiteRatedFilter
{
    public function createSqlParts( $params )
    {
        $minimum = isset( $params['minimum'] ) ? (int)$params['minimum'] : 0;
        return array(
            'tables' => ', mysite_rating r',
            'joins'  => " r.contentobject_id = ezcontentobject.id AND r.score >= $minimum AND ",
            'columns' => ''
        );
    }
}

{fetch( 'content', 'list', hash( 'parent_node_id', 2,
                                  'extended_attribute_filter', hash( 'id', 'MysiteRatedFilter',
                                                                     'params', hash( 'minimum', 4 ) ) ) )}

Der Kernel ruft createSqlParts( $params ) auf und fügt tables, joins und columns in seine Abfrage ein (createExtendedAttributeFilterSQLStrings() in kernel/classes/ezcontentobjecttreenode.php). Alles, was Sie in das SQL schreiben, muss sicher sein: Wandeln Sie Zahlen um, maskieren Sie Strings mit eZDB::instance()->escapeString().

RAD #

Template extension (/setup/templateoperator) schreibt Fetch-Funktionen mit ihrer Definition und Collection-Klasse; siehe Mit RAD: ein Template-Operator in fünf Minuten.

Verwandte Seiten #

• Zurück: Template-Operatoren
• Weiter: Template-Funktionen
• Von Hand: eine Fetch-Funktion
• Inhalte in Templates abrufen
• Freie Dokumentation: Diese Seite darf unter der GNU FDL 1.3 frei kopiert, übersetzt und verbessert werden.