The "render" parameter

Updated on 20-October-2016 at 10:16 AM

Business Catalyst End of life announcement - find out more details.

The background

Similar to the traditional BC tags that belong to a particular layout, each Layout has a set of associated output tags.

In this article we will go over a basic Liquid usage scenario that involves replacing the legacy BC tags with the new Liquid ones.

The "render" parameter indicates whether the contents of the layout used to render the module should be interpreted as a single item or a collection.

The collection is a new concept, it simply represents the group of items outputted by a module.

Note: if the render parameter is missing or has a value other than item or collection the default render method used will be item.

render="item"

This is the classic scenario any "list" type module uses, the contents of the layout will be repeated as blocks and represent a single item.

For example, let's consider module_webapps below that is rendered using the Webapp list layout.

On a page we'll insert this code:

<!DOCTYPE html>
<html>
    <head>
        <title>Webapp listing</title>
        <meta name="description" content="" />
    </head>
    <body>
        <table>
            <thead>
                <th>Make</th>
                <th>Engine size (L)</th>
                <th>Engine layout</th>
                <th>Performance</th>
            </thead>
            <tbody>{module_webapps render="item" id="35209" filter="all"}</tbody>
        </table>
    </body>
</html>

Notice how the module itself is wrapped in table markup.

Now let's edit the webapp list layout. Open it up and paste this code:

<tr> <td>{{this.name}}</td>
        <td>{{this.['engine size']}}</td>
        <td>{{this.['engine layout']}}</td>
        <td>{{this.performance}}</td> </tr>{%
        endraw %}

Warning: if you need to access a liquid tag that has a space in its name, for example tag_large image_value use this syntax: {{this.["large image_value"]}} - Liquid does not allow for the name of its output tags to contain spaces. In this particular example the tag that contains a space needs to be wrapped in square brackets and quotes.

This represents each row that will be repeated inside the table wrapper. Now save the layout and take a look at how the module is rendered in the front-end:

render="collection"

When using this method, the contents of its layout as a whole rather than the repeating code that represents an individual item.

The main advantage using this method is you are able to control the wrapper. For example if you render a photo gallery using render="item" you will get the photo gallery items wrapped in a table. Using render="collection" you can wrap the individual items in a ul or div element.

Warning: this render method does not support legacy tags. Your layout must only contain Liquid output tags.

Using this technique BC creates a collection named items and makes it available in the layout context. We can now use the more complex capabilities of the Liquid rendering engine to iterate through the items collection and further process the data before rendering it.

Note: To see what the collection looks like and what fields are available in the items collection, insert the code below on the layout:

<pre>
{{items | json }}
</pre>

Refresh the page where you have inserted the module.

To better illustrate how to use this feature let's consider the same webapp setup used above and a page that contains the module_webapps listing:

<!DOCTYPE html>
<html>
    <head>
        <title>Collection demo</title>
        <meta name="description" content="" />
    </head>
    <body>
        {module_webapps render="collection" template="/layouts/custom/car_collection.tpl" id="35209" filter="all"}
    </body>
</html>

On the /layouts/custom/car_collection.tpl layout insert the code below:

<table> <thead> 
<th>Make</th> 
<th>Engine size (L)</th> 
<th>Engine layout</th> 
<th>Performance</th>
</thead> 
<tbody> {% for item in items %} 
<tr>
<td>{{item.name}}</td> 
<td>{{item.['engine  size']}}</td> 
<td>{{item.['engine layout']}}</td> 
<td>{{item.performance}}</td>
</tr> {%endfor%} 
</tbody>
</table>

For more code samples on filtering and looping with Liquid please take a look at the How to section.

The front-end will end up looking like this:

What's next? Liquid collections

In the following articles, let's take a look at another rendering method using Liquid collections .