By default a template is just a template. Sapwood offers a few types of templates that override default template behavior and offer a few unique and specific features.

Clicking on that link in the previous paragraph will show you how to configure template types. This guide is here to explain them to you.

Documents

When we first built Sapwood, we considered elements and documents to be two separate things. And what drove how an element and document worked were their respective template and document type.

But as we continued to build out Sapwood, templates and document types, and elements and documents converged more than we anticipated. So we made them to be (essentially) the same thing.

A document is, for all intents and purposes, an element. The main difference is that it has a direct uploading capability. In other words, to be able to upload anything to your Sapwood property, you need at least one document template.

Each document (again, really just an element) has a url attribute when returned through the API.

Let's say we're managing a podcast through Sapwood. We may have a template for episodes that holds the data for the episode. We could choose to make that a document template and then we'd be able to upload episode audio directly. Or we might want to upload the episode audio separately (say, in the case where you need more than one file), so we'd have a regular episode template, but then add an audio document template.

Images

Sapwood also recognizes when an uploaded file is an image, and it will process the image into a few different sizes. It makes these available via the versions attribute when returned through the API.

Single Element

Sometimes you don't want a template to be a group of elements, but just one element. In Sapwood we call this a single element (single_element) template.

It works exactly like a regular template, with one major exception: after the template's first element is created, the list view disappears and you are always redirected to that first element's form.

How the heck is that useful? It saves a click in cases where you'll never create a second element.

The two most common scenarios we've seen so far are:

  1. A home page, where there will only be one element but the fields are unique to that page.
  2. Site or app settings, where you need to explicitly define each setting, and adding a second element would only add to the confusion.