Persistent template variables

About

You usually require a persistent_variable when you need to pass a value from a (module result) template context into the pagelayout template context (outside of module result context).

Checking to ensure your persistent variable name is not already in use

Remember that another extension may already use the variable name you wish to use, so it may be important to search your templates to ensure the variable name is not already used previously as this helps ensure you do not overwrite existing variables.

Background

It can take a user of eZ Publish quite some time of learning before finding out how to use the persistent_variable template variables.

This article should help even the average user quickly understand how to work with the persistent_variable within the contexts of templates and even within the context of PHP!

This documentation was inspired by another user who shared in the forum thread, "Persistent variable unveiled"

Use case

You need to pass a variable from a module result template context into a pagelayout template context.

Examples

Modifying a variable in a module result template context (TPL)

When the 'persistent_variable' is of variable type 'hash' it is simple to modify it's contents within a module result template context using the set template function and the merge operator.

{set scope=global $persistent_variable=$#persistent_variable|merge( hash( 'key', 'value' ) )}

The above template code merges into the hash a new key/value pair.

Remember it is very important to use the set parameter 'scope=global' and '$#' to access the existing value within the in global template variable scope.

Also note the quotes around the examples are not actually part of the examples in the last sentence containing 'scope=global' and '$#'.

Accessing a variable in a pagelayout template context (TPL)

Now that you are modifying the persistent variable and adding a new key/value pair you can try to use this information within the pagelayout context (cache issues aside *)

{$module_result.content_info.persistent_variable.key}

Accessing a variable in a template operator context (PHP)

If you are creating an eZ Publish template operator in PHP code you can also access and modify this persistent variable within a module result template context.

$persistent_variable = array();

if( $tpl->hasVariable( 'persistent_variable' ) )
{
    $persistent_variable = $tpl->variable( 'persistent_variable' );
    $persistent_variable[ 'key' ] = 'value';
    $tpl->setVariable( 'persistent_variable', $persistent_variable );
}

Accessing a variable in a pagelayout template context from module result template context (TPL)

Now that you are modifying the persistent variable and adding a new key/value pair you can try to use this information within the pagelayout context

$module_result = $tpl->variable( 'module_result' );

$persistent_variable = array();

if( isset( $module_result['content_info']['persistent_variable'] ) )
{
    $persistent_variable = $module_result['content_info']['persistent_variable'];
}

Closing

If you wish to learn more please read this excellent blog on the subject, "eZ-Publish CMS persistent variables"

References

• Blog: eZ-Publish CMS persistent variables
• Doc: Template function set
• Doc: Snippet: Template Variable Scope / Passing Variables to Template
• Forum: Persistent variable unveiled