8.9. The "Save Selected Element as Template" dialog box
Prev | 8. Dialog boxes | Next

### 8.9. The "Save Selected Element as Template" dialog box

This dialog box is displayed by menu item Options+Customize Configuration → Save Selected Element as Template. Basically, it allows the user to specify a label for the newly created element template.

Giving a label to an element template is needed to support different templates for the same element type. For example, in a DocBook document, select a `table` element and use Options+Customize Configuration → Save Selected Element as Template to label it as "L1". Then select another `table` element and use the same menu item to label it as "L2". This gives you two `table` element templates, one called "L1" and the other called "L2".

The label of an element template must be a valid `NMTOKEN`. It cannot contain whitespace.

The element name and label of a template may be identical to the element name and label of one of the existing templates. This allows to replace an existing template by a new one.

In the above screen shot, we can see that:

- The user is creating a new `table` element template called "invoice".

  After creating this template, it will be displayed in the "Existing element templates" list as "table(invoice)", "table" being the element name of the template and "invoice" being its label.

- Previously, the user has created another `table` element template labelled "3x3".

- Previously, the user has replaced predefined "table(simple)" template by a "table(simple)" template of its own.

#### 8.9.1. Advanced options

Use only if the parent element matches the following XPath

  Normally an element template is suggested by the Edit tool whatever the parent element where this template is to be inserted. But in some cases, generally with W3C XML schemas and with RELAX NG schemas and not with DTDs, you'll want the template to be usable only in certain contexts.

  Example: your schema defines two `title` elements: a job title which is a possible child element of `person` and `author` elements and the optional title (i.e. a caption) of `table` and `figure` elements.

  You intend to define several job title templates. Example: element template "title(arch)" is defined as `<title>Software Architect</title>`.

  Of course, you don't want to see "title(arch)" listed by the Edit tool when you are about to give a title to a `table`.

  In such case:

  1. Click on the "Use only if the parent element matches the following XPath" radio button.

  2. Type XPath expression "`person|author`" in the text field below the radio button.

  This means: suggest "title(arch)" but only when the template is to be inserted in a `person` or an `author` element.

  Note that a very small subset of XPath is supported here:

This replaces the default, automatically generated, element template

  This option is best explained by an example.

  Out of the box, if you insert a `table` element in a DocBook document, in fact, you insert predefined `table` template called "table(simple)".

  The "table(simple)" template has two rows and two columns which makes it much more useful that the default, automatically generated, `table` template which just contains a single cell[12].

  Note that when a single named template such as "table(simple)" replaces the default, automatically generated, element template, the Edit tool does not display its label. For example, in the case of the DocBook `table`, the Edit tool displays "table"[13] and not "table(simple)".

  Now, what if you prefer to use a `table` having 3 rows and 3 columns plus a `thead` header as your default table?

  1. Create the table by inserting the rows, cells and header you want.

  2. Select this table.

  3. Use Options → Customize Configuration → Save Selected Element as Template.

  4. The "Existing element templates" list shows you that a predefined template already replaces the default, automatically generated, one. You can see this because "table(simple)" is displayed in italic.

     You need to label your own template like the existing one in order to replace it. Therefore specify "simple" in the Label of the element template field.

  5. Click on check box "This replaces the default, automatically generated, element template".

#### 8.9.2. Removing a previously defined element template

This dialog box also allows to remove user-defined element templates. In order to do this, simply click on a template in the "Existing element templates" list and then click on the Remove button.

Note that this operation takes immediate effect: clicking on the Cancel button of the "Save Selected Element As Template" dialog box will not cancel the deletion of the template[14].

You can only remove the element templates you have created. You cannot remove predefined (grayed) element templates.

In the above screen shot, notice how removing user-defined "table(simple)" template would restore the predefined template having the same element name and label.

[12] The default, automatically generated, element template is the simplest, valid, element allowed by the schema.

Most of the time this heuristic gives good results. However in some cases, the default, automatically generated, element template, is, well, too simple to be useful.

[13] There is no ambiguity and this is shorter to type.

[14] The Cancel button of the "Save Selected Element As Template" dialog box just cancels the action of creating a new template.

Prev | Up | Next
8.8. The "Save Document As Template" dialog box | Home | 8.10. The "Add Keyboard Shortcut" dialog box