## Templates in Amaya

### What is a template?

Templates are used to produce multiple documents of the same type. A template is a skeleton representing a given type of document, expressed in the format of the final documents to be produced (XHTML, for instance). The format of the final documents is called the target language and must be an XML language.

In a template, the skeleton document contains some statements, expressed in the XTiger (eXtensible Templates for Interactive Guided Editing of Resources) language, that specify how this minimal document can evolve and grow, while keeping in line with the intended type of the final document. Documents produced from this skeleton following the XTiger statements are called instances of the template. Some parts of the template may be frozen, if they have to appear in document instances as they are. Some parts may be changed when producing an instance document, some others may be added either freely or under some constraints.

The file containing a template must have a `.xtd` extension.

A template comes often with a set of accompanying resources (images, style sheets, scripts). A template is a web resource, that can be stored in the local file system or shared on a remote web server.

### Selecting templates

You can create your own templates, using the XTiger language. However, in the current version of Amaya, no specific support is provided for creating or updating templates. You can also use the templates available on the Amaya web site at http://www.w3.org/Amaya/Templates/

You are free to store templates anywhere, in your local file system or remotely.

To ease selection among your favorite templates, there is a Templates section in the Preferences dialogue (Edit > Preferences). Use it to register the templates that Amaya will propose when you create a new document. When registering a local template, you can call a file browser with the browse button to locate and select the files to be added to the list. You can also enter the URI of remote templates in the input area below the list. Use the buttons on the right side of the list to remove a template or to change the order of templates in the list.

Registering templates in this list is not mandatory. When you create a new document instance, you can also choose a template that is not in that list.

### Creating a document instance

To create a new document instance from a template, use entry New > From template in the File menu. It displays a dialogue box where you can select:

- The template, either by selecting in the list of registered templates or by typing the URI or file name of a template that is not in the list
- The URI or file name of the document instance you want to create
- Where to open the new document (Replace current, In new tab, In new window)
- The Title of the new document (this is mandatory)

### Visualizing template elements

When a document instance is displayed, Amaya shows the XTiger elements under the form of colored frames that enclose XHTML elements.

- A `use` element is shown as a dashed blue box
- A `bag` element is shown as a dashed green box
- A `repeat` element is shown as a dashed purple box
- An `option` element is shown as a dashed yellow box
- The `attribute` element is not displayed in the main view, as it only impacts the Attributes menu.

The XTiger elements can also be seen in the structure view. Open this view with the Show structure entry of the View menu. In the structure view, XTiger elements are displayed in green, while the XHTML elements are in blue. XTiger elements are also shown in the Source view, but with no special color.

Another way to understand the nesting of XTiger elements with XHTML elements is the selection path displayed in the status bar or the window (at the bottom of the document window). There, you can see the list of all elements in the structure of the document from the root element to the current selection. It is updated every time the selection is changed. In this path, XTiger elements are displayed in green and XHTML elements in black. For XTiger elements, it is not the name of the element that is displayed there (use, bag, repeat, option) but the label of these elements, as declared in the template.

### Editing a document instance

Editing is allowed only inside the repeat, option, use, and bag elements, i.e. within the colored dashed boxes. The rest of the document is the fixed part of the template and can not be modified.

#### Editing in a `repeat` element

In a `repeat` box (purple), you can create a new instance of the repeated structure or you can delete one. This is controlled by the template, which may impose a minimum and/or a maximum number of occurrences of the repeated structure. When creating new occurrences of the repeated structure is allowed, click one of the purple '+' icons to create a new occurrence at that location. You get a pop up menu that tells you what can be inserted at that position. By clicking in that pop-up menu, you create a new occurrence of the corresponding type. In some cases the template offers only one type of occurrence. The pop-up menu then contains a single entry, to clearly state what will be created. If you click outside the menu, nothing is created.

Another way to create new occurrences of the repeated structure is to select an existing occurrence, or to put the caret at the end of an occurrence, and to press the `Enter` key. A new occurrence of the repeated structure is then created, provided the maximum number of occurrences is not reached. The type of the new occurrence is then the same as the one that was selected when pressing the `Enter` key.

When an existing occurrence is empty or fully selected and the `Backspace` or `Delete` key is pressed, the element is deleted, provided the minimum number of occurrences is not reached.

#### Editing in an `option` element

`option` boxes (yellow) display a 'tick' icon in the top left corner. If the box is empty, clicking this icon creates the optional structure. If the optional structure is already present, this removes it.

#### Editing in a `use` element

Most `use` elements (blue) allow you just to enter free text or to freely replace/edit existing text. Other `use` elements offer a choice between different types of elements that can be inserted at that position. In that case, a triangle icon is displayed in the top left corner of the box. By clicking this icon, you can select one of the allowed types through a pop-up menu. When you have chosen a type, the corresponding structure is generated and you can freely edit its content.

#### Editing in a `bag` element

In a `bag` box (green), you can insert any number of elements of the types specified by the template. When you want to insert a XHTML element, do it the usual way provided this type is allowed by the template. It may happen that some elements are not allowed by the template. These elements are greyed out in the menus (in the current version, this feature is not implemented, but prohibited elements are not created).

Templates introduce new structures (called components) built from XHTML elements. The XML elements panel lists them and allows you to insert them in bags (green boxes). For inserting a component at the current position, select its name in the panel and click the Apply button at the bottom of the panel. You can also double-click its name.