#Building templates

Templates define the placement of a templated content item's elements, parts, and fields on the page. A content item can take advantage of templates if its content type has the TemplatedItemPart content part. A template is built on top of a layout.

The template management screen

Clicking on the "Templates" admin menu entry takes the user to the template management screen.

From this screen, you can see the list of existing templates (templates are displayed as a title for the moment, but soon a preview of the layout will be visible instead). You can also delete a template from this screen.

Clicking on the title of one of the templates, or on the "Create New Template" button takes you to the template editor.

The template editor

The template editor is partitioned into two zones: a tree representation of the elements of the template on the left (1), and a preview of the template on the right (2):

On the right side of the tree (1), you can find the toolbox of available elements (3). Available elements by default for templates are part, field, image, text, link, and container (see detailed descriptions below).

On the bottom of the tree (1) are three tabs (4) that enable the user to switch from the default "Elements" representation to the global properties of the template (Template tab), or to the XML representation of the template (XML tab).

The tree and XML views of the template are both editable, and all changes will be instantly reflected by the preview (2).

###Template properties

The templates properties tab should be the first thing users access when creating a new template, because it is where the layout for the template is selected. Immediately after having given a title to the new template, the user should click the "Template" tab and choose the base layout for the template. Of course, at least one layout must have been defined before this can be done. Once the layout has been selected, the user must save the template in order for the layout to be applied. Doing it later would lose any changes already made, so it's important to select the layout first, then save.

The template properties tab also enables the user to select a stylesheet among the ones available in the active themes. This is useful if the template you are building has custom styles that need to be applied.

This tab also has settings for global CSS classes, width and height for the template. Setting a top-level CSS class is usually a good idea, in particular in conjunction with the choice of a custom stylesheet. Setting the width and height is not recommended however.

The tree

The tree view of the template gives a visual representation of its hierarchy of elements within the rows and columns of its layout. Elements can enter edit mode when the user clicks their representations either in the tree or in the preview.

It is also possible to view the editors for all elements at once by clicking the '+' icon in the toolbox. To revert back to the default view where at most one editor is open at a time, click the '-' icon that replaced the '+' when you clicked it.

Elements can be deleted by selecting them, then clicking "Delete" on the top-right of the editor, then clicking "Confirm".

Elements can be moved around the tree using simple drag and drop gestures. The tree being a hierarchical structure, you may have in some cases to drag an element to the left or right in order to put it under the right parent.

If you encounter difficulties in getting the exact result you're after, you can always switch to the XML tab and edit the XML representation of the template directly:

##Preview

The template preview is a visualization of the template that is updated as you perform changes in the element tree.

The preview can be zoomed into using the scale that is on the bottom left. It can also be dragged around, which is mostly useful when zooming. The two buttons on the bottom right can be used to restore the zoom level to 100%, and to fit the view to the window.

The preview is extremely useful as visualization, but it is also a great selection tool. On complex templates, it can be tricky to find the element you're looking for in the tree, and clicking on the representation of the element in the preview is often much easier and faster. Selecting an element on the preview will open its editor in the tree, and will scroll it into view if necessary.

##Available elements

• Part: the part element enables the rendering of a content part anywhere on the template. Be careful to select a part that really exists on the content items that will be displayed by this template. Also make sure that the placement.info for the content type(s) being displayed does not already send that part to statically-defined zones as this would result in double rendering of the part. If it does, make sure you replace it with a "-". Talk to your theme designer if this doesn't make sense to you, but you're seeing your part appear twice.
• Field: the field element enables the rendering of a content field anywhere on the template. Be careful to select a field that really exists on the content items that will be displayed by this template. Also make sure that the placement.info for the content type(s) being displayed does not already send that field to statically-defined zones as this would result in double rendering of the field. If it does, make sure you replace it with a "-". Talk to your theme designer if this doesn't make sense to you, but you're seeing your field appear twice.
• Image: an image that is specific to the template (as opposed to a media library field that belongs to the content type), but that will be defined per content item. An image element can have a default URL.
• Text: a text that is specific to the template (as opposed to a text field or body part that belongs to the content type), but that will be defined per content item. A text element can have a default value.
• Link: a link that is specific to the template (as opposed to a link field), but that will be defined per content item. A link element can have a default URL and text.
• Container: the container element is extremely useful, for example to build complex buttons from more than just text, or to build panels that resize dynamically, with an image background, or a link. A container can have any element under itself, including other containers. The container element has settings to automatically center the contents, add a link or an image background. It also has a setting to set the context of the contents of the container. The context is the content item from which parts and fields will be taken. This way, you can display parts and fields from other content items that are selected for each templated content item. This is an advanced scenario.