@vtfk/sjablong

Sjablong

Templating engine with the combined powers of handlebars, front-matter, JSON Schema and Sjablong-fields

What can Sjablong do?

• Replace placeholders in text (Sjablong-fields, mustache or handlebars-expressions)
• Generate JSON Schema from Sjablong-fields and validate data against it
• Have default values for the template by front-matter or Sjablong-fields
• Convert Markup to HTML

Sjablong-fields

A Sjablong-field starts with [[ and ends with ]]
Inbetween the tags you define keyvalue-pair in the format key="value"
The only required key in a Sjablong-field is path. This it path in the data it should be replaced with. The Sjablong-fields can be used to generate a JSONSchema to validate the data with.

Field examples

Key	Description	Required	Example
label	Name/title of the field	No	Firstname
path	The path in the data object it should be replaced with	Yes	name.firstname
description	Description of the field	No	Firstname of the recipient
required	Should the field be required?	No	true
default	The default value of the field	No	Bob
preview	If replacePlacehold's preview option is true	No	Bob

Examples

Sjablong-felt on a single line

[[label="fornavn":path="name.firstname"]]

Sjablong-felt with multiline default value

[[label="test":path="test":default="Line1\nLine2\nLine3"]]

Sjablong-felt on multiple lines (It is not necessary to indent the pairs)

[[
  label="Firstname"
  path="name.firstname"
]]

Sjablong-felt on multiple lines with more fields

[[
  label="fornavn"
  path="name.firstname"
  descriptione="First name of the recipient"
  required="true"
  default="Bob"
  preview="Bob"
]]

Functions

replacePlaceholder

const template = `[[path=firstName:preview="Preview user":default="Wilson"]]`

/*
  Example: Replaces the placeholder with firstName data
  Returns: Bob
*/
const data = { firstName: 'Bob'}
const replaced = replacePlaceholders(templateText, data);

/*
  Example: Replaces the placeholder with default data
  Returns: Wilson
*/
const data = {}
const replaced = replacePlaceholders(templateText, data);

/*
  Example: Replaces the placeholder with preview data
  Returns: Preview user
*/
const template = `[[path=firstName:preview="Preview user"]]`
const data = {}
const replaced = replacePlaceholders(templateText, data, { preview: true });

/*
  Example: Replaces sjablong and mustache-field
  Returns: Bob Bobson
*/
const template = `[[path=firstName]] {{lastName}}`
const data = { firstName: 'Bob', lastName: 'Bobson' }
const replaced = replacePlaceholders(templateText, data);

generateSchema

Retreives all Sjablong-fields from a template and generates a JSON schema from it. The schema can then be used to validate data before replacing placeholders.

/*
  Example: Generates a json schema from a template
  Returns:
  {
    "properties": {
      "firstName": {
        "type": "string",
        "preview": "Preview user"
      }
    }
  }
*/
const template = `[[path=firstName:preview="Preview user"]]`
const schema = Sjablong.generateSchema(template);

/*
  Example: Generates a json schema from a template making all fields required
  Returns:
  {
    "properties": {
      "firstName": {
        "type": "string",
        "required": true
      },
      {
        "age": {
          "type: "number",
          "required": true
        }
      }
    }
  }
*/
const template = `[[path=firstName]][[path=age:type=number]]`
const schema = Sjablong.generateSchema(template, { requireAll: true, });

/*
  Example: Generates a json schema where subproperties of required field are also required
  Returns:
  {
    "properties": {
      "firstName": {
        "type": "string",
        "required": true
      },
      {
        "address": {
          "properties": {
            "city: {
              "type": "string",
              "required": true
            }
          }
        }
      }
    }
  }
*/
const template = `[[path=firstName]][[path=address.city:type=string]]`
const schema = Sjablong.generateSchema(template, { requireAll: true, });

/*
  Example: Flattens a JSON schema, nice feature to auto generate inputs for a schema
  Returns:
  [
    {
      "path": "firstName",
      "type": "string"
    },
    {
      "name": "city"
      "path": "address.city",
      "type:" "string"
    }
  ]
*/
const template = `[[path=firstName]][[path=address.city:type=string]]`
const schema = Sjablong.generateSchema(template);
const flatten = Sjablong.flattenSchema(schema);

/*
  Example: Validates data against a schema
  Result: This will fail because address.city does not exist in the data
*/
const data = { firstName: 'Brede Skuldre' }
const template = `[[path=firstName]][[path=address.city:type=string:required=true]]`
const schema = Sjablong.generateSchema(template);
Sjablong.validateData(schema, data);

/*
  Example: Validates data against a schema
  Result: This will fail because address.city is not of the correct data type
*/
const data = { firstName: 'Brede Skuldre', address: { city: 5 } }
const template = `[[path=firstName]][[path=address.city:type=string]]`
const schema = Sjablong.generateSchema(template);
Sjablong.validateData(schema, data);