Amaya

## Editing with templates

### 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 language (eXtensible Templates for Interactive Guided Editing of Resources), 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.

### Creating a template

You can create your own templates, using the XTiger language. However, Amaya provides a specific support for creating or updating templates.

The proposed approach is to:

- Create first a skeleton of the document instance (.html file) you want to generate.
- Select the Template (Tpl) tab of the Elements tool and click on the first "Create template from current document" entry to generate a template (.xtd file) from that document skeleton.
- You can also create a new empty XTiger library (.xtl file) with the "Create a library" entry.
- When a template document or a XTiger library is selected, several entries of the Template tool are available:

  - The "Create a component" entry generates a `component` that will be displayed in the `head` of the template document.

    If the selection is not empty, the current selected content becomes the content of the component. A `use` element is created at the current position of the document to say that the component is inserted at that position. The selection must be valid (a set of complete elements or a string). The command asks the user for the `component` name. That name must be unique and is used to display the document structure of template instances.

    Note: The content of the component won't be edited in template instances. The user has to insert `use` and/or `bag` elements inside the component to define editable areas. These editable areas can be inserted before or after the creation of the component.

  - The "Create a new types union" entry generates a `union` element which defines a new type as a choice between several basic types (`number`, `string`), or several elements from the target language (div, h1, h2, p, ...) and `component` names. The current selection has no effect. The command asks the user for the `union` name. That name must be unique.

  - The "Import a library" entry generates a `import` element that inserts library declarations at the position.

  - The "Create a text area" entry generates a `use` element that allows one to insert a string in template instances. The command asks the user for a label. That label is free and is used to display the document structure of template instances. The selection must be string that becomes the initial value of the `use` element.

  - The "Use a component or an element" entry generates a new `use` element.

    If the selection is empty, an dialog proposes the list of elements or components that can be inserted at that position and asks the user for the label associated with the `use` element (as the previous entry). A `use` element is generated with an empty content.

    If an element of the target language (div, h1, h2, p, ...) is selected, the `use` element will allow one to insert this element type at that position. The selected element becomes the initial content of the `use` element. The command only asks the user for a label.

  - The "Repeat the current use" entry generates a `repeat` of the current selected `use` element. The command asks the user for a label. That label is free and is used to note the repeat element in the document structure of template instances.

  - The "Create and repeat a component" entry generates at the same times a `use` element inside a `repeat` element.

  - The "Create a free editing box" entry generates a `bag` element. The command asks the user for a label. That label is free and is used to display the document structure of template instances.

    The `bag` element allows several inserts of any element of the target language and components defined in the template (`types="any"`). The user has to edit the `types` attribute with the Attributes panel to modify that default value.

  - The "Create attribute control" entry generates a `attribute` element (not available yet).
- The created template or XTiger library can stored anywhere, in your local file system or remotely.

### Visualizing template elements

When a template is displayed, Amaya shows the XTiger elements under the form of colored frames that surround XHTML elements.

- The `head` element which includes `component`, `union`, and `import` elements is displayed with a grey background.
- The name of `component` and `union` elements is displayed on the top of them.
- A `use` element is displayed is a box a dashed blue frame. When its content is a text, the box has a blue background.
- A `bag` element is a box with a light green background and a dashed green frame.
- A `repeat` element is a box with a icon on the top left.
- The `attribute` element is not displayed in the Formatted view.

XTiger elements can also be seen in the Structure view (open this view with the Show structure entry of the Views menu). In the Structure view, XTiger elements are displayed in gold, 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 of the window (at the bottom of the 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 changes. In this path, XTiger elements are displayed in gold and XHTML elements in black. For XTiger elements, it is not the element name (`use`, `bag`, `repeat`) but the label of these elements, as declared in the template.

### Selecting templates

You can select your own templates, or use the templates available on the Amaya web site at http://www.w3.org/Amaya/Templates/

To ease selection among your favorite templates, there is a Templates section in the preferences dialogue (Edit/Preferences, or amaya/Preferences under Mac OS X). Use it to register the templates that Amaya proposes when you create a new document.

When registering a local template, you use the file browser (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 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 recommended but not mandatory. When you create a new document instance, you can also choose a template that is not in that list.

### Creating an instance document

To create a new document instance from a template, use entry New/New document in the File menu. It displays a dialogue 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 that will be displayed by browsers (a default title is generated when the user doesn't specify it).

### Editing an instance document

When a template instance is created or opened, Amaya displays side by side the Formatted view and the Structure view of the document.

In the Formatted view:

Editing is allowed only inside the `repeat`, `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.

- Areas where the user can edit are surrounded with colored frames:
  - A blue frame surrounds an area where the user can insert text (`use` elements).
  - A green frame surrounds an area where the user can insert elements or strings (`bag` elements).
- + buttons allow the user to display a pop-up menu and insert one of new elements proposed in the menu at the current position (in `repeat` or `bag` elements).
- The `attribute` elements only impact the Attributes panel.

In the Structure view:

- Labels of XTiger elements are displayed over a colored background:
  - A grey background for inactive `use` elements
  - A gold background for active `use` elements
  - A light gold background for active `repeat` elements
  - A light green background for active `bag` elements
- With active elements,
  - A click on the label, or the top half of the attached vertical line, displays a pop-up menu that allows the user to insert a new proposed element before.
  - A click on the bottom half of the attached vertical line displays a pop-up menu that allows the user to insert a new proposed element after.

#### Editing in a `repeat` element

In a `repeat` box, you can create new instances 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 a new occurrence of the repeated structure is allowed, + icons are displayed at locations where you are allowed to create it. When you click on these icons, you get a pop-up menu that tells you what can be inserted at that position. 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 yet. 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 yet.

#### 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 blue 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. The allowed elements are listed in the Insert and Append sub-menus of the contextual menu. The available `component` elements are also listed in the Insert and Append sub-menus of the contextual menu.