Templates plugin

partial$misc/admon-premium-plugin.adoc

Tip	As of {productname} 7.0, the Advanced Template plugin has been renamed to Templates. When adding Templates in your editor, continue to use advtemplate.

The Templates Premium plugin enables the creation of complex, interactive templates using {productname}.

They can also be added to a {productname} instance by end-users selecting content in a {productname} document and saving the selection as a template via the {productname} user-interface.

Important

Templates does not support template editing. To update a particular template; insert the template into an editor; make edits; select the, now edited, content; and then create a new template (using, for example, the Tools > Save as Template… menu item).

Using the Templates plugin

Inserting a template

To insert a template

Select Template… from the Insert menu or Select the Insert template toolbar button.
Select the template to add to the {productname} document from the Templates dialog that presents.
Click Insert or press Return.

Adding a new template

To add a new template

Select the material in the {productname} document that is going to be the new template and
Save the template using one of the following methods:
- Select Save as template… from the Tools menu.
- Select Save as template… from the context menu.
- Select the Save as template toolbar button.

Then, in the New template dialog that presents

Enter a name for the new template in the Template name field;
Select a category for the new template from the Category pop-up menu; and
Click Save or press Return.

Adding a new category

To add a new category

Select Template… from the Insert menu to open the Templates dialog.
Click on the New category button in the dialog footer.
The New category form will pop up within the editor.
In the New category form, enter the name of the new category you want to add.
Click the Save button to submit the form.
After saving, the new category will appear in the Tree component of the Templates dialog.

Searching for templates

To search for a template

Select Template… from the Insert menu to open the Templates dialog.
Enter the name of the template you are searching for in the Search field.
As you type, the displayed list of matching templates updates in real-time in the dialog’s Tree component.

Template list management

To manage the template list

Select Template… from the Insert menu to open the Templates dialog.
Select the template or the category you want to modify.
Click on the three dots menu for the selected item.
The actions menu will open.
From the actions menu, choose the appropriate operation based on your requirements:
- Rename category/template.
- Move template to another category.
- Move all category items to another category.
- Delete template/category.

Readonly categories

Templates categories can be set to read-only in {productname}, preventing users from modifying the category or its templates. When a category is set to read-only, users cannot:

add new templates to the category
delete the category or its templates
rename the category or its templates
move templates into or out of the category

A lock icon visually indicates that a category is read-only, preventing users from modifying the category or its templates through the user interface.

To create a locked (read-only) category, add the locked: true property to the category object in your templates data:

Example of a locked category

{
  title: 'Locked Templates',
  locked: true, // Locks the category as readonly
  items: [
    {
      title: 'How to find model number',
      content: '<p dir="ltr">Hi {{Customer.FirstName}},</p>\n<p>...</p>'
    },
    {
      title: 'Support escalation',
      content: '<p dir="ltr">Hi {{Customer.FirstName}},</p>\n<p>...</p>'
    }
  ]
}

liveDemo::advtemplate-readonly-template[]

Basic setup

To setup the Templates plugin user-interface in the editor:

add advtemplate to the plugins option in the editor configuration;
add inserttemplate and addtemplate to the toolbar option in the editor configuration;
add each Templates option to the editor configuration;

Example

tinymce.init({
  selector: 'textarea',  // change this value according to your html
  plugins: "advtemplate",
  toolbar: "inserttemplate addtemplate",
  contextmenu: "advtemplate",
  // Each of the following options must be defined as
  // a function that returns a Promise.
  // Please find the specific details for each option below.
  advtemplate_list,
  advtemplate_get_template,
  advtemplate_create_category,
  advtemplate_create_template,
  advtemplate_rename_category,
  advtemplate_rename_template,
  advtemplate_delete_template,
  advtemplate_delete_category,
  advtemplate_move_template,
  advtemplate_move_category_items
});

Note	The undefined options in the above example must be defined. See the Options below for specific details on each function.

Interactive examples

There are two approaches to using the Templates Premium plugin: fixed template lists and user-modifiable template lists.

Fixed template lists

For users who work with a fixed template list that does not require modification, you can provide a list directly through the {productname} init configuration using the advtemplate_templates option.

The following interactive predefined list example provides guidance for this approach.

Configuring the Templates plugin to use a static list of predefined templates.

liveDemo::advtemplate-predefined[]

User-modifiable template lists

If the intention is for the template list to be end-user modifiable, the Templates plugin should be configured with options to enable communication with a remote Template storage service.

The following interactive remote storage configuration example provides guidance on configuring the Templates plugin to support user-modifiable template lists.

Configuring the Templates plugin to interact with a remote backend service via REST API.

liveDemo::advtemplate[]

The insertion point marker

The insertion point marker is a fixed string for adding to any template.

The string to add is as follows: {{mce-cursor}}.

Wherever this string is within a template is where the insertion point appears when that template is added to a {productname} document.

Also, and as shown in the interactive demonstration below, the Merge Tags plugin knows to ignore this fixed string, making it possible to use the insertion point marker in conjunction with both plugins.

liveDemo::advtemplate-insertionpoint[]

The mce-clipboard marker

The {{mce-clipboard}} marker is a fixed string for adding to any template.

The string to add is as follows: {{mce-clipboard}}.

Whenever a user inserts a template containing the {{mce-clipboard}} marker, the editor will replace those markers with the actual content from the clipboard.

liveDemo::advtemplate-mce-clipboard[]