User templates

If you have ever developed a website with a CMS, you have probably had to decide more than once if you should write a module for a piece of content on the website or not. Sometimes, a module is just overkill for content which will not be updated very frequently, so you decide not to develop a module. Fair enough, let’s use editor templates in CKEditor instead.

Editor templates are helpful if you know how they work and as a (frontend) developer, you should understand how they work. Alas, your average CMS user probably won’t. She/he will manage to screw up your template from the moment they try to modify the content.

That’s why we decided we needed something different.

Requirements

So we needed some kind of templates that can handle more complex layouts but are easy to manage in the backend. It should also be pretty easy for the frontender/developer to add these templates to the theme as the templates are theme-specific.

The templates should be able to contain the following types of content:

  • Text
  • Textarea
  • Link with text
  • Link without content
  • Image
  • Image background
  • Editor

With these basic types, you can practically create any layout, without the need for a full-blown module.

Integration

So, now we know the requirements, but how do we integrate this? Obviously we’re not trying to reinvent the wheel, so we’ve got our inspiration from CKEditor, Mailchimp and Campaign Monitor.

CKEditor uses html-files and a javascript-file to load the editor templates. We can use the same structure for the user templates, although we will be using a .json-file instead of a .js-file. This file is used in the backend to populate the templates dropdown and read the real html of the templates.

In Mailchimp and Campaign Monitor you can add extra attributes to the html to make the content editable. The content editor transforms the html to a form to make it easy for the user to modify the content.

As we want our output to be valid html, we use data-attributes for the different types. Each type of content has a data-ft-label attribute, which will be used for the labels in the generated form. The data-ft-type attribute defines the type of content::

  • Text: data-ft-type=”text”
  • Textarea: data-ft-type=”textarea”
  • Link with text: data-ft-type=”link”
  • Link without content: data-ft-type=”link-without-content”
  • Image: data-ft-type=”image”
  • Image background: data-ft-type=”image-background”
  • Editor: data-ft-type=”editor”

When adding or editing a template in the backend, some clever javascript trickery will transform the html into a nice form.

When we save the changes, the form values are reinserted in the original html and saved in the database. This way we can generate the form over and over again when editing the existing content.

How to create a user template

In your theme, create a folder ‘UserTemplates’ in the Templates-folder. In this folder, add a file ‘Templates.json’. In case of the quote example, the file should look like this:

[
  {
    "title": "quote",
    "description": "Easy way to add a quote",
    "file": "quote.html"
  }
]

On the same level, add a file ‘quote.html’ which contains the html you want to use. Add the correct data-ft-label and data-ft-type attributes to the content that should be editable.

Here’s an example of a quote template which can also be found in the Fork theme (/src/Frontend/Themes/Fork/Core/Layout/Templates/UserTemplates/quote.html):

<blockquote>
  <div class="row">
    <div class="col-sm-2">
      <img src="http://placehold.it/128x128" alt="Placeholder" class="img-responsive img-circle" data-ft-label="Avatar" data-ft-type="image" />
    </div>
    <div class="col-sm-10">
      <p data-ft-type="textarea" data-ft-label="Quote text">The only way to do great work is to love what you do</p>
      <footer>
        <span data-ft-type="text" data-ft-label="author">Steve Jobs</span>,
        <span data-ft-type="text" data-ft-label="function">Founder</span> of
        <a href="http://www.apple.com" data-ft-type="link" data-ft-label="Website">Apple</a>
      </footer>
    </div>
  </div>
</blockquote>

That’s it!

How to use a user template

Now, if you want to add a block to a page, you’ll get an extra type of content you can select:

add block popup

When adding (or editing) a template on a page in the backend, this gets transformed into a neat form:

user template form

In the frontend, this template could look like this:

user template example

Pro’s and cons

Pro’s

  • You can add more complex layouts which are easily editable in the backend, without the need for a custom module.
  • The user cannot modify the html, so you are sure the layout in the frontend will be exactly how you intended it to look.
  • New templates are straightforward to add.
  • (Way) better and easier to use than CKEditor templates.

Cons

  • User templates are only available in the pages module.
  • Changes to the template file are not transferred to the templates which are already in the database, so the content needs to be added again, as we store the generated HTML.
  • User templates are page-specific, so if a piece of content is to be repeated on several pages, the content has to be inserted on all pages separately.