Writing your own fetch function #

This page is for application creators who want templates to read their data with fetch( 'expdemo', 'items', hash( ... ) ). A fetch function is declared in the module's function_definition.php and implemented by a static method that returns array( 'result' => ... ).

Contents #

1. The declaration
2. The implementation
3. Using it
4. Rules

The declaration #

extension/expdemo/modules/expdemo/function_definition.php, in the same directory as module.php:

<?php
$FunctionList = array();
// fetch( 'expdemo', 'items', hash( 'limit', 5, 'offset', 0 ) )
$FunctionList['items'] = array(
    'name' => 'items',
    'operation_types' => array( 'read' ),
    'call_method' => array( 'class' => 'expDemoFunctionCollection',
                            'method' => 'fetchItems' ),
    'parameter_type' => 'standard',
    'parameters' => array(
        array( 'name' => 'limit',  'type' => 'integer', 'required' => false, 'default' => 10 ),
        array( 'name' => 'offset', 'type' => 'integer', 'required' => false, 'default' => 0 ) ) );

The kernel's own files follow the same shape (kernel/exphelp/function_definition.php, kernel/content/function_definition.php).

The implementation #

extension/expdemo/classes/expdemofunctioncollection.php:

<?php
class expDemoFunctionCollection
{
    public static function fetchItems( $limit = 10, $offset = 0 )
    {
        $limit = max( 1, min( 100, (int)$limit ) );
        $offset = max( 0, (int)$offset );
        $access = eZUser::currentUser()->hasAccessTo( 'expdemo', 'read' );
        if ( $access['accessWord'] === 'no' )
            return array( 'result' => array() );
        return array( 'result' => expDemoItem::fetchList( $limit, $offset ) );
    }
}

Return array( 'result' => $value ) on success. Regenerate the autoloads and clear the caches afterwards.

Using it #

{def $items = fetch( 'expdemo', 'items', hash( 'limit', 5 ) )}
{foreach $items as $item}<li>{$item.title|wash}</li>{/foreach}
{undef $items}

Objects you return should be eZPersistentObjects or offer attribute() and hasAttribute(), so templates can read $item.title (Persistent objects and custom tables).

Rules #

• Check permissions inside the function; templates can be called from anywhere.
• Bound every limit.
• Keep the method thin: call a service class your views and commands use too.
• Name parameters as the content fetches do (limit, offset, sort_by), so template authors guess right.
• Test the static method with PHPUnit like any class (DB-less PHPUnit tests).

Related pages #

• Fetch functions: reading data in templates
• Fetch function pattern
• Writing template operators
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.