Using variables in templates

It is possible to call Option and Style Property values and settings directly in templates.

In order to identify the option or style property name, debug mode must be enabled.
To do that, edit the library/config.php file and add this at the very bottom:

PHP:

$config['debug'] = true;

Note: Once debug mode is no longer required, it is recommended that it is disabled. Debug mode should not be enabled on a production site and it can also result in the inadvertent editing of the master settings, templates, and phrases.


Options
With debug mode enabled, a spanner (wrench for those of you who don't speak correct English ) icon appears alongside each option. Hovering over it or clicking it will reveal the option name.

For example, for the Board Title, it is, unsurprisingly, boardTitle:

Once you have the option name, it can be used in templates using:

Rich (BB code):

{$xenOptions.optionName}

With optionName being the actual name of the option.

In the case of the Board Title it would be:

Rich (BB code):

{$xenOptions.boardTitle}

Some options have sub-options, which are referenced like so:

Rich (BB code):

{$xenOptions.optionName.option}

One example of that is the AddThis option:

That would be called like this:

Rich (BB code):

{$xenOptions.addThis.enabled}

An example of using that in a template, would be if you wanted to check if AddThis was enabled, which you can do so using:

Code:

<xen:if is="{$xenOptions.addThis.enabled}">
    //Action to take if AddThis is enabled
</xen:if>

Any code within the conditional statement would only be executed if the option was enabled.


Style Properties
For non-CSS properties, the name is available in various places.

The first is under the style property title and if available (it is not present for some style properties), it is present in all styles.
In this example, it is maxResponsiveWideWidth:

If it is not present there, it is necessary to check in the Master Style and either hover over or click the icon:

Style properties are called in templates using:

Rich (BB code):

@stylePropertyName

In this example it would be:

Code:

@maxResponsiveWideWidth

That could then be used in a CSS template in a media query, for example:

Code:

@media (max-width:@maxResponsiveWideWidth)
{
    .myClass
    {
        display: block;
    }
}

For CSS properties, the name can be seen by hovering over the name or clicking the Edit Definition link (available in the Master Style only):

Again, they are called in templates in the same way but in addition, specific properties can also be referenced.
In the case of the section property, the top margin for example can be called directly using:

Code:

@section.margin-top

That could be used in a calculation for other CSS which may depend on that value, for example:

Code:

.myClass
{
    margin-top: {xen:calc '@section.margin-top + 10'}px;
}

If a variable is available in a template, you can use it in a phrase which is included in that template.
The benefit over just adding the phrase(s) and variable(s) to the template separately is that only a single phrase is required no matter how many variables are called or where they are inserted in the phrase.


The phrase title and text take the form:
Title

Rich (BB code):

lorem_ipsum_dolor_sit_amet_x

The x in the title is commonly used to substitute the variable name in the text, although any character(s) can be used.

Phrase Text

Rich (BB code):

Lorem ipsum dolor sit amet {variable}.

The variable is the name you assign to the actual variable which will be called.


The phrase and variable are then called in the template like so:

Rich (BB code):

{xen:phrase lorem_ipsum_dolor_sit_amet_x, 'variable={$variable}'}

The phrase name must match the phrase title, the variable name the assigned name in the phrase text, and the variable the actual variable being called.


Let's look at a couple of examples using real variables and values, which will hopefully make things clearer.

This first example uses a single variable.
The first step is to create the phrase:

The phrase title is welcome_x and it references a single variable called name.

The template syntax to call the phrase and variable would be:

Note that the phrase name matches the phrase title, the variable name matches the name assigned in the phrase, and in this case, the variable is the user name of the visitor.


This second example uses two variables.
Each variable must be assigned a unique name:

When calling multiple variables, each one is comma separated, making the template syntax:

Once again, note that the phrase name matches the phrase title, the first variable name matches the name assigned in the phrase, as does the second variable name and in this case, the first variable is the user name of the visitor and the second variable is the board title.

Although a variable may not be natively available in a template, in some cases it is possible to set the value of it in the container using <xen:container>.

The container encompasses the PAGE_CONTAINER template and all templates included by it, such as category_view, pagenode_container, various ad_* templates, etc.

To set a variable in the container, this code must be added to the content template:

Rich (BB code):

<xen:container var="$variableId">{$variable.id}</xen:container>

The variableId is the name you assign which will be used to call the value in the container. Although the name isn't important, you must ensure the name you assign doesn't already exist in the container.
The variable.id is the actual variable which must be available in the content template.

The variable value can then be called in the container using:

Rich (BB code):

{$variableId}

A real world use case would be if categories are set to open in dedicated pages (ACP -> Options -> Node & Forum List: Create Pages for Categories), rather than just act as anchors on the forum index.

With that configuration, the category node ID isn't available in the ad_above_top_breadcrumb template for example, making it impossible to target specific categories using <xen:if is="{$category.node_id} == x">.

Using <xen:container> we can pass the category node ID to the container, making it available to use in the ad template.

To do so we edit the category_view template and add the following line of code at the top of the template:

Rich (BB code):

<xen:container var="$categoryId">{$category.node_id}</xen:container>

The category node ID will then be available to the container and can be called using {$categoryId}, which, when used in an if statement, would be <xen:if is="{$categoryId} == x">.


Another example involves passing the page node ID.

Again you would edit the content template, in this case the pagenode_container template and add this line of code:

Code:

<xen:container var="$pageId">{$page.node_id}</xen:container>

The page node ID can then be referenced using {$pageId}.