Upmk Docs

Templating

upmk uses nunjucks for templating. All view files used in a project are run though nunjucks with the context of data being exposed from the corresponding controller.

Adding .njk to the end of a model will force the content body of that model instance to be ran through our build time templating. This is useful for building out custom filters (see below) that can be used within the content of a model (for example to build shortcut style inputs ala links to specific parts of a page, or to a consistent external resource ... MeanWhileInProvo.com does this with a custom filter that creates links to team member profile pages)

upmk default filters

There are a few default filters in upmk (asset, date, marked, titleize, and I18n).

asset

The asset filter is for use within editor template files. Within the editor we pull up asset files via the redirect api (/api/v1/assets/redirect/*fpath). Locally, files are accessed by their direct path within the static build. In order to make this work for editor templates, which can be built, viewed, and tested locally ... while still working in the editor, the asset filter prepends the redirect api to the asset string when it detects that it is running in a browser.

<img src="{{ image | asset }}" />

date

The date filter uses moment.js to format a date to a string:

{{ myDate | date }}

Be default it uses LL as a format. You can pass in another format as needed:

{{ myDate | date("l") }}

marked

The marked filter runs a string through the marked npm module to convert markdown to html. In order for the outputted html to be used directly in nunjucks it needs to be piped into a default safe filter:

{{ content | marked | safe }}

I18n

The I18n filter allows you to pull strings from config/locale/*.yml files. For now this defaults to only pulling from the en.yml file.

{{ "root.fourHundred" | I18n }}

titleize

The titleize filter works much like the rails string method of the same name. It uppercases the first letter of each word in a string

{{ 'some text' | titleize }} # Some Text

custom filter

Filters are simple functions that take an input and return a scalar value. see the nunjucks custom filter docs for more details. Should you need custom filters for your project add them to render/filters within your project. The render system will pick them up and make them available to anything that is being rendered during a build.

As an example to get started, each new upmk project creates a small custom limit filter within your project.

function limit(str, chars) {
  return str.substring(0, chars)
}

module.exports = limit

A few things to note about it. The first argument to a filter is the value it gets from the "pipe", any other arguments are then optional.

{{ "some string" | limit(7) }}

{{ "some string" | limit }}

Include in build

In order to get your custom filters added to the editor, add it by name to editor/filters/build/index.js

global functions

There is currently one global function made available. it is the destruct function. You can see it's usage in the default views/template/show.html.njk. It takes a single object and pulls all the the objects keys and values up to the top level. This is a somewhat dangerous function as it will clobber other keys that are already set within the render context. Use it with caution

upmk docs