# Layout templates

The layout templates are used by the web designer to create the HTML of the web page. With Foundry the designer has almost complete control over the HTML. Despite the elements which correspond to HTML 5 elements most other elements which can be used in the templates do not create HTML. A complete list of the elements which can be used in the layout templates can be found in the Template Tags Reference.

Which template is used is decided by Foundry using the definitions in the `conf/templates` file. The top layer of templates which are parsed first are the application layouts. Which layout is used for a application is decided by Foundry using the `application` and `class` attributes of of `bebop:page` element in the data tree. The values of these attributes a set in the Java code or in the JSP templates used.

## Application layout templates

### How Foundry determines which application layout template to use

Which template is used for which application is determined using the `applications` section in the `conf/templates.xml` file. The `applications` element may contain any number of `application` elements. Each application element can have three attributes:

`name` (mandatatory)
  The name of the application which is the value of the `application` attribute from the data tree. To associate applications which do not set the `application` attribute in the data tree the value `none` can be used.
`class` (optional)
  The class of the application page shown. This is the value of the `class` attribute from the data tree.
`origin` (optional)
  The origin of the template. In the default theme this is used to associate the backend applications which like the content center with the internal `admin-layout.xml` template provided by Foundry. It can also be used to associate an application with an layout template from the parent theme.

The `applications` element in the `conf/templates.xml` file should also contain a single single default element which defines which layout template should be used when no other matches.

Foundry tries to find the layout template to use as follows:

- If there an `application` element where both `name` and `class` match the values from the data tree this template is used.
- Otherwise Foundry checks if there is an `application` element without a `class` attribute where value of the `name` attribute matches the value from the data tree.
- If this also fails and there is a `default` element the template from the `default` element is used.
- If there is no `default` element the internal default layout template is used.

### The structure of a application layout template

An layout template is a normal XML file. The root element is the `page-layout` element. The first child should be a head element. The `head` element is equivalent of the HTML head element. Inside the `head` element the title of (the string shown as title of the browser window) can be determined using the `title` element. Also the `head` is the place to load the CSS and JavaScript files and where to put meta informations.

After the `head` there should be a `body` element. Inside the `body` element the HTML structure is defined. At some point you may want to insert the content of a content item or of a Portlet. This is done using elements like `content-item` element or `portal-grid-workspace-column-portlets`. The layout of the individual content item or Portlet is defined in separate templates.

## Content Item layout templates

The content layout templates which are found in the `templates/content-items` folder are used to create the HTML for content items in the list, link and detail views. Which template is used for which content item is determined using the `content-items` section in the `conf/templates.xml` file.

### Selecting the Content Item layout template to use

The `content-items` element in the `conf/templates.xml` file has three sub elements: `detail`, `link` and `list`. The `content-item` elements in these elements are determining which template is used for which content type. There are several attributes for selecting the template. For a description of the available attributes please refer to the documentation of the `content-item` tag.

### Structure of a Content Item layout template

Like the application layout templates a content item layout template is a XML file. The root element is the `content-item-layout` element. Inside this element all HTML producing elements can be used. For some content types there are special elements for outputting special properties. For example the for news item there is an elements `news-date` which outputs the date of a news. This element also provides an interface for designer to customise the format in which the date is shown. There is is also an general tag `show-property` which can be used to create a basic template for an unsupported content type.

## Portlet templates

For Portlets the system is similar to the system for content items. Which template is used for a specific Portlet is determined using the child elements of the `portlets` element in the `conf/templates.xml` file. The `portlet` elements which contain the path of the template to use can have two child elements:

class
  The class name of the Portlet.
workspace
  The name of the workspace in which the Portlet is shown.

Foundry first tries to find a match for both `class` and `workspace`. If there is no matching `portlet` element in `conf/templates.xml` Foundry tries to find a match for the class name only. If this also fails it used the templates defined in `portlets/default` in the `conf/templates.xml` file.

The root element of a Portlet layout template is the `portlet-layout` element. Inside this element all HTML elements can be used. For each Portlet type there will be least on specific element which outputs the content of the Portlet.