Adding a template

In Sulu a template consists of multiple content types, whereby a content type describes the way the data is stored in the database and how to enter them in the administration interface. Pages in the Sulu content section will be based on one of these templates.

On this page there are the available content types described, how to define these values in our template configuration file, what you should consider when creating the HTML templates, and finally how to connect the data from Sulu to the HTML template.

Available content types

The following list shows the content types delivered by a standard sulu installation. The first column shows the key, which acts as an unique identifier. The second one describeds the appearance in the administration interface, and the last one how the content is returned to the HTML template.

Key Appearance Value
text_line simple text line text
text_area text area text
text_editor text editor with formatting capabalities formatted text
color color picker text
date date picker text
time text line with a time validation text
url text line with an URL validation text
email text line with an email validation text
password password field text
phone text line for a phone number text
internal_links widget for adding links to other pages resolved pages as defined in parameters
single_internal_link widget for selecting a single internal link resolved page as defined in parameters
smart_content widget for configuring smart contents, a content type for aggregating multiple pages resolved pages as defined in parameters
resource_locator widget for entering the URL for the page text
tag_list autocomplete field for entering and adding tags array of texts
media_selection widget for adding media (images, documents) to the page array containing another array with urls for every format

Add a template definition

To add a new template to your Sulu installation, you just create a new xml file in app/Resources/pages named by a unique template key. See the following file for an example of a template definition:

<?xml version="1.0" ?>
<template xmlns="http://schemas.sulu.io/template/template"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://schemas.sulu.io/template/template http://schemas.sulu.io/template/template-1.0.xsd">
    <key>default</key>

    <view>ClientWebsiteBundle:templates:default</view>
    <controller>SuluWebsiteBundle:Default:index</controller>
    <cacheLifetime>2400</cacheLifetime>

    <meta>
        <title lang="en">Default</title>
    </meta>

    <properties>
        <property name="title" type="text_line" mandatory="true">
            <meta>
                <title lang="en">Title</title>
            </meta>

            <tag name="sulu.rlp.part"/>
        </property>

        <property name="url" type="resource_locator" mandatory="true">
            <meta>
                <title lang="en">Resourcelocator</title>
            </meta>

            <tag name="sulu.rlp"/>
        </property>

        <property name="images" type="media_selection">
            <meta>
                <title lang="en">Images</title>
            </meta>
        </property>

        <property name="article" type="text_editor">
            <meta>
                <title lang="de">Artikel</title>
                <title lang="en">Article</title>
            </meta>

            <params>
                <param name="godMode" value="true"/>
                <param name="links" value="true"/>
                <param name="tables" value="true"/>
            </params>
        </property>
    </properties>
</template>

The root element of this xml file is template, which first child element is a key, which has to match the filename without the file extension (e.g. the file default.xml has the key default).

The next xml tags contains some information about rendering the template. This includes the view, which is the reference to the twig template, and the controller-tag references the controller, which is used to render the given template. For standard templates you don’t have to define your own controllers, because you can use the index-action of the DefaultController in the SuluwebsiteBundle. Both the template and controller have to be referenced as described in the Template Naming and Locations (with the addition of the LiipThemeBundle) and Controller Naming Pattern in the Symfony documentation.

The meta-tag consists of another title-tag for each available language, which will be displayed in the template selection of the Sulu administration interface.

The next tag is for all the properties in this template. A property is the instance of one of the previous listed content types. The property’s type attribute is the key from the list above, and the name identifies this particular property. The first child element is another meta-tag containing the title for each language, which will be displayed in the content management form in the Sulu administration. Depending on the content type you can/must add some more parameters, as for the article-property in the example above. The example is enabling the godMode, the icon for adding links and the icon for adding tables.

Note

Every template has to define a property named title, because it is used internally for generating URLs and storing.

Build the HTML template

We recommend to build the HTML templates in a first draft with plain HTML and some dummy texts. That means absolutely no placeholders for template engines. This ensures that your HTML is working across all browsers (at least if you test it correctly), and it is easier to test, since there are guaranteed no errors caused by the some wrong template variables.

Please make also sure that your HTML is valid, and use HTML tags in a semantic way, so that your website will achieve the best results in terms of search engine optimization.

Create the data connection