About

The template module provides the ability to use variables to create conditional content and for loops as well as the ability to create page templates to include things like a sidebar or titlebar.

Example

Variables are defined in the options of the fileTransform and can be a String, Object or Array[String / Object]. Variables are included on a page using double curly braces (e.g. {{variableName}}) Below is an example showing how to set up and use variables in your pipeline:

Example Markup

Javascript

// Summarised Pipeline Config
const template = require('quantum-template')

const templateOptions = {
  // Define the variables to use:
  variables: {
    exampleString: 'my string',
    exampleList: ['a', 'b', 'c'],
    exampleObjectList: [
      { head: 'Something', body: 'Content 1' },
      { body: 'Content 2' }
],
exampleObject: {
  name: 'Dave',
  age: 25
}
}
}

module.exports = {
  pipeline: [
    // Add to your pipeline
    template.fileTransform(templateOptions)
]
}

Quantum

# Use the `exampleString` variable as the title
@h1: {{exampleString}}

# Object properties are referenced with a dot:
@h2: {{exampleObject.name}}, {{exampleObject.age}}

# Loop through the items in an array:
@for item in exampleList
  @bold[{{item}}]
  @br

# Loop through an array of objects:
@for item in exampleObjectList
  @if item.head
    @h3: {{item.head}}
@p: {{item.body}}

# Loop through the keys/values of an object
@for key value in exampleObject
  @p: @b[key:] {{key}}, @bold[value:] {{value}}

@ifnot nonExistentVariable
  @p: Display This

@ifnot exampleString
  @p: This won't display because exampleString exists

Example Result

my string

Dave, 25

a

b

c

Something

Content 1

Content 2

key: name, value: Dave

key: age, value: 25

Display This

Page Template Example

Page templates are provided by including an @template at the root of a page. This is most sensibly done using @inline. The fileTransform processes the @template, finds the @contentEntity and moves everything outside the template into the content entity.

Example Markup

templates/template.um (Quantum)

@template
  @contentEntityName templateContent
  @content
    @header
      @icon [/resources/logo.svg] [/]
      @title QuantumJS

@sidebarPage
  @sidebar
    @navigationMenu
      @section Introduction
        @page /: Home
        @page /page-1: Page 1

@content
  @templateContent

pages/index.um (Quantum)

@inline /templates/template.um

@contentSection
  @topic Home
    Some information on the home page

pages/page-1.um (Quantum)

@inline /templates/template.um

@contentSection
  @topic Page 1
    Some information on page 1

Example Result

target/index.html

target/page-1/index.html

API

Below are all the properties of the object returned from require('quantum-template'). For information about different versions, see the Changelog

Functions

fileTransformoptionsObjectFileTransformadded

The function for getting a FileTransform for parsing template variables and processing the entities (e.g. @for, @if provided by this module.

Arguments

options

Properties

variables

The variables to use when templating. They can be any type of String, Object or Array. Variables are then available on pages in the form of {{variableName}}

Example Markup

Javascript

template.fileTransform({
  variables: {
    myVar: 'my variable'
}
})

Quantum

@h3: Heading
@p: {{myVar}}

Example Result

Heading

my variable

Returns

FileTransform

wrapperfileContentArray[Entity]added

The function used by the fileTransform that processes the @template entities.

It does not apply variable definitions and only processes the page content to apply the templating.

Example

Javascript

const wrapper = require('quantum-template').wrapper

// Example use in pipeline
const pipeline = [
  (file) => {
    return file.clone({
      content: wrapper(file.content)
})
}
]

Arguments

fileContentArray[Entity]

The content of a processed File object.

Entities

foradded

Loop through an Array variable or an Object variables keys

Example Markup

Javascript

...

// Variables passed into fileTransform
{
  exampleList: ['a', 'b', 'c'],
  exampleObjectList: [
    { head: 'Something', body: 'Content 1' },
    { body: 'Content 2' }
],
exampleObject: {
  name: 'Dave',
  age: 25
}
}
...

Quantum

@h3: Loop through list
@for item in exampleList
  @bold[{{item}}]
  @br

@h3: Loop through list of objects
@for item in exampleObjectList
  @if item.head
    @h3: {{item.head}}
@p: {{item.body}}

@h3: Loop through object keys
@for key value in exampleObject
  @p: @b[key:] {{key}}, @bold[value:] {{value}}

Example Result

Loop through list

a

b

c

Loop through list of objects

Something

Content 1

Content 2

Loop through object keys

key: name, value: Dave

key: age, value: 25

ifadded

Display some content based on a variable value.

Example Markup

Javascript

...

// Variables passed into fileTransform
{
  exampleString: 'my string'
}
...

Quantum

@if exampleString
  @h3: exampleString is declared
  {{exampleString}}

@if undeclaredVariable
  @h3: Variable not declared, this will not show

Example Result

exampleString is declared

my string

ifnotadded

Inverse of @if, can be used as an 'else' statement for @if blocks. It displays content if a the value of a variable is falsey.

Example Markup

Javascript

...

// Variables passed into fileTransform
{
  exampleString: 'my string'
}
...

Quantum

@ifnot exampleString
  @h3: exampleString is declared, this will not show
  {{exampleString}}

@ifnot undeclaredVariable
  @h3: Variable not declared, this will show

Example Result

Variable not declared, this will show

templateadded

Creates a template to apply to the page.

An example can be seen in the Page Template Example section

Entities

content

The default location to put the template content. This can be overriden by providing a @contentEntityName

contentEntityName

Used to define what entity to put the content of a templated page inside.

By default, it looks for @content

Example

Quantum

@template
  @contentEntityName someEntity

  @someEntity
    # Content would be placed here