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);