Adding a template¶
After defining a webspace creating a template file is the next step towards a Sulu website. We’ll learn about Content types and how a template definition should look like.
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 describes 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 capabilities |
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 |
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 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.
Using XInclude¶
A template can be composed of various components using XInclude. To use Xinclude you first have to add the proper namespace (xmlns:xi=”http://www.w3.org/2001/XInclude”-attribute).
<?xml version="1.0" ?>
<template xmlns="http://schemas.sulu.io/template/template"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xi="http://www.w3.org/2001/XInclude"
xsi:schemaLocation="http://schemas.sulu.io/template/template http://schemas.sulu.io/template/template-1.0.xsd">
Now you can add a part of the template including another file. The path in the href-attribute is relative to the template file.
<xi:include href='blocks/main-block.xml'/>
You can even add a part of another xml file or another template using an xpointer.
<xi:include href='other-template.xml' xpointer="xmlns(sulu=http://schemas.sulu.io/template/template)xpointer(/sulu:template/sulu:properties)"/>
Warning
XInclude currently does not work on Windows.
Note
Every template has to define a property named title, because it is used internally for generating URLs and storing.
We’ve learned how to define the template. The next step is to write corresponding theme.
Warning
The template does not appear in the dropdown of the page form, unless there is also a HTML twig template available. This will be explained in Creating a Twig Template.