Apostrophe Doc Template Library

This module solves the "blank page problem" for developers and product managers, and makes it faster for editors to create content. doc-template-library allows for the configuration of default widgets and pre-populated content on piece or page templates, and to re-use existing layouts.

Installation

To install the module, use the command line to run this command in an Apostrophe project's root directory:

npm install @apostrophecms-pro/doc-template-library

Usage

Configure the template library module in the app.js file:

require('apostrophe')({
  shortName: 'my-project',
  modules: {
    '@apostrophecms-pro/doc-template-library': {}
  }
});

Using the template manager

Once this module is enabled, the admin bar for your site will have a new button located on the right side just to the left of the user login menu and/or locales dropdown. Clicking on this button will bring up the template manager with cards for each of the page-type and piece-type templates.

For pages, the card will display a preview image of the template using an iframe. A preview iframe image for a piece template will be present only if there is a corresponding piece-page that has been created in the page tree for the piece-type. Each card will also indicate the name and document type for the template. The filter button can be used to display only templates of a certain type and the search box can be used to search for templates by name.

Hovering over a page template card will reveal two buttons. The first button, "Edit Settings" will open the page editor modal. Clicking the second, "Edit Layout" will open the page in preview mode for in-context editing of the template layout. Note that editing a template will only impact future pages made from this template, not pages that have already been created. Any time you are editing a template, a yellow bar will appear across the top of the template. Additionally, the page template slug is prefixed with an @ symbol to further delineate that it is a template and won't be visible in the page navigation.

Hovering over a piece-page template card will reveal a single button that opens the piece editor modal. Like with the page templates, changing the piece-page templates only impacts new pieces made with this template, not past pieces. From within the piece editor modal, you can choose to edit the piece in-context if a piece-page has been created in the project. This will open the preview with a yellow bar across the top and the addition of an @ symbol prefixing the piece slug to indicate that a template is being edited.

Creating new templates

Creating a new template from within the template manager modal

From within the template manager, there are several ways you can create a new template. At the upper right corner is a "New Template" button that will open a modal to allow the entry of a title and selection of either a page or any piece-type registered in the project. Selecting "page" will allow for further selection of the page-type. This will add tabs to the manager corresponding to the tabs defined by that page-type to enter content. Similarly, the selection of a particular piece-type will populate the modal with any fields defined by that type. You can also elect to add an optional preview image, rather than having Apostrophe auto-generate one, by clicking on the "Add Image" button to the right and selecting an image from the media library.

A second way to create a new template is by clicking on one of the edit buttons to select the template and then clicking on "Duplicate ..." within the context menu. This will create a copy of the template, which can then be edited and saved back to the template library.

Saving an existing page as a template

Existing pages can be copied to the template library either from the page tree or while editing the page. In both cases, clicking on the context menu will allow for the selection of "Save as template...". This will bring up a modal to allow for the change of the template title or content.

Saving an existing piece as a template

Existing pieces can be copied for use in the template library from either the piece manager or from the individual piece 'show.html' page. In both cases, clicking on the context menu will allow for the selection of "Save as template...". This will bring up a modal to allow for changing the template title or content.

Creating a new page or piece using a template

When the module is enabled, the page and piece editor modals will contain an extra "template" tab when first creating a new document. This tab will not be present once you save either a draft or published version of the document. Selecting the template tab will open a template selection modal containing all of the templates that apply to that page- or piece-type. As with the template library manager, you can use the search box to find templates by name. Hovering over the template will bring up an "Apply template" button. After clicking on this button the content from the template will be populated into the schema fields of the page or piece.

Template permissions

Activating this module alongside the @apostrophecms-pro/advanced-permission module provides a new row in the group permissions grid named "Templates". If this is left as "None", users that are assigned to this group will not be able to see the template library at all. If this is assigned a value of "Editor", then users will be able to see all templates in the library. They will only be allowed to save edits to a template if they also have permission to edit that document type. Similarly, they will only be allowed to apply that template to documents that they have permission to edit.

Without the Advanced Permission module enabled, users with either 'Admin' or 'Editor' permissions will be able to fully edit and utilize templates from the library. Users who have a 'Contributor' role will be able to apply already created templates to any pages or pieces, but won't be able to edit the settings or layout of any template.

Excluding a piece type from templates

If you do not wish to have templates for a particular piece type, you can set the hasTemplates option of that module to false.