Identifying and using variables in templates, advertising positions, navigation entries, and widgets

[FateKid]

What are variables?​

In simple terms, variables are names which hold values.
These values are stored in the database and are used in templates to evaluate and present the content and data.

Using variables in templates opens up a lot of possibilities for customising and modifying the look and behaviour of an XF installation.

Most of you are probably already aware of using variables in some way or another, via conditional statements for example - <xf:if is="$xf.visitor.user_id">, or widget display conditions - $xf.reply.containerKey == 'node-1'.

However, there are many more uses for variables, once you know how to identify and utilise them.

This guide aims to explain how to do that.

Checking the available variables in a template​

The first step is to dump the variables in the template you wish to access them in.

If you don't know the name of the variable or want to check all of the variables available to a particular template, that is done by adding the following code to the template:
HTML:

{{ dump(vars()) }}


For example, for the thread_view template, you would edit the template like so:
HTML:
{{ dump(vars()) }}

<xf:title page="{$page}">{{ prefix('thread', $thread, 'escaped') }}{$thread.title}</xf:title>
<xf:h1>{{ prefix('thread', $thread) }}{$thread.title}</xf:h1>

<xf:if is="!$thread.isSearchEngineIndexable()">
<xf:head option="metaNoindex"><meta name="robots" content="noindex" /></xf:head>
</xf:if>

Identifying a specific variable​

When navigating to a thread, a code block will be present at the top of the thread, which contains all of the variables available to the template.





If you are interested in a specific variable you can then drill down to see the exact syntax.

Any entry with a #value and/or ▶ in the brackets indicates that it can be expanded to see the array contents.



As the tooltip explains, pressing CTRL+click will expand everything in one go.


In this example we want to see if there are any thread author variables and what the format is.
So first we expand thread:




Then _values, which gives us:




So now we can see that the keys related to the thread author are user_id and username.




Which makes the variables $thread.user_id and $thread.username.

We can confirm that by dumping those exact variables in the template, like so:




If the variables are valid, they will return values which correspond to those variables, in this case a user ID of 1 and the member's user name, Test.




If the variables are invalid, for example if we try to dump thread.userid (note the lack of the _ between user and id), then null will be returned.




Additionally, if you have debug or development mode enabled, which no-one has on their production site, right? Right!?
Then there will be an error message displayed relating to the invalid variable.

Utilising a variable​

All of that is all well and good, but what use is it and how can it be utilised?
Well let's see, shall we?

For the purpose of this guide, now that we have the thread author variables, we can use those to identify and highlight the author's posts in a thread.

Looking further down the thread template we can see that posts are output using the following code:
HTML:

<xf:foreach loop="$posts" value="$post">

<xf:extension name="messages_block_body_before_post"></xf:extension>

<xf:if is="$post.message_state == 'deleted'">
<xf:macro name="{{ $templateOverrides.post_deleted_macro ?: 'post_macros::post_deleted' }}"
arg-post="{$post}"
arg-thread="{$thread}"
args="{$templateOverrides.post_deleted_macro_args}" />
<xf:else />
<xf:macro name="{{ $templateOverrides.post_macro ?: 'post_macros::post' }}"
arg-post="{$post}"
arg-thread="{$thread}"
arg-highlightedPosts="{$highlightedPosts}"
args="{$templateOverrides.post_macro_args}" />
</xf:if>

<xf:extension name="messages_block_body_after_post"></xf:extension>

</xf:foreach>

As before, we can dump the variables which apply to this section of the template and as we're interested in posts, we can assume that $post.user_id is one of them, so we do:



To make things clearer, you can also add some text for each variable you are dumping.

The result of that is we can now see the thread author ID and the individual post author IDs.





Now we can edit the thread_view template with a conditional statement to evaluate the post user ID against the thread user ID, like this:




The result of which is Thread Author is displayed above every post made by the thread starter.





Obviously this is just for the purposes of this guide and it wouldn't actually be implemented in that way.
It does though hopefully explain how to access and utilise variables in templates.


If you found this tutorial useful, donations of positive emojis are gladly received.