Using smart content

What is smart content?

The smart content is one of our most powerful content types. It allows the content editor to dynamically configure an aggregation of content, whereby content does not only mean pages. This is possible due to the data providers, which can be registered in the system. A data provider defines which options are supported, and is responsible for loading the data. Sulu is already shipped with different data providers, one for pages from the content management section, and another two for contacts and accounts.

The configuration will be resolved to a set of arrays, which can easily be used in a twig template.

Configure a smart content

The smart content is configured in the template definition. The template definition is already described in Creating a Page Template. All that has to be done is to add another property for the smart content. This configuration can look something like the following typical XML fragment:

<property name="pages" type="smart_content">
    <meta>
        <title lang="en">Smart Content</title>
    </meta>

    <params>
        <param name="properties" type="collection">
            <param name="title" value="title"/>
            <param name="description" value="excerpt.description"/>
        </param>
        <param name="present_as" type="collection">
            <param name="one">
                <meta>
                    <title lang="en">One column</title>
                </meta>
            </param>
            <param name="two">
                <meta>
                    <title lang="en">Two column</title>
                </meta>
            </param>
        </param>
    </params>
</property>

In this XML fragment a smart_content property named pages is defined. For pages there is also the possibility to define a properties parameter, as you can see in the previous fragment. In this collection property can be defined which properties of the page should be returned in the array passed to the twig template. The name of the parameter describes how the property will be accessible in the twig template, and the value is the name of the property on the page. Additionally there is the excerpt extension, which can be used as well, there has excerpt. to be prefixed. This extension is available for all pages, so it is a safe bet. The problem with other properties is that you have to make sure or at least check in the twig template if the property exists.

The value of the present_as property is injected into a dropdown, where the content editor can choose between different styles, which have to be implemented by the creator of the twig template. Popular options here are one or two columns with variations like with or without images.

There are also more parameters to tweak the smart content, for a deeper understanding of this there is the reference documentation of the Smart content.

Use the smart content in a twig template

Using the pages that are returned from the smart content in a twig template is very easy. As already described the data is returned as an array in the twig template in the content variable. In the view variable the configuration data of the smart content is stored.

This way it is really simple to display this information using a twig template:

<div property="pages">
{% for page in content.pages %}
    <div class="{{ view.pages.presentAs }}">
        <h2><a href="{{ sulu_content_path(page.url) }}">{{ page.title }}</a></h2>
        <p>{{ page.description|raw }}</p>
    </div>
{% endfor %}
</div>

The pages in content.pages refers to the name of the property in the template definition. Every page being returned by the filter described in the smart content has its own array in this variable, so that we can iterate over it. In the view variable the configuration of the smart content is accessible, which can be used e.g. as a CSS class in this example. This way the one or two column layout can be created by using CSS.

The page loop variable can then be used to access the actual content from the page. A Sulu twig extension provides the sulu_content_path method, which builds the final URL with all the additional information required.

For more and deeper information about twig there is the excellent twig documentation.

The next step is how to add localization to Sulu.