Templates and Components

You can create component files that contain data that can be easily inserted into your campaign documents. Component files can be either .json or .yaml files.

Template Basics

Templates are Markdown, .md files that specify how to take the content in "component" files and generate markdown elements to be put into your campaign documents. Rather than having to remember the layout or style you have for your monster stat blocks or magic item cards, templates allow you to design the layout once and then insert them into your documents consistently and reusably.

Templating Engines

Currently, there are 3 supported templating engines: Handlebars (the default), Mustache, and Pandoc (requires installation). However, Handlebars is essentially a "beefed" up version of Mustache, so there are really only two templating styles: Mustache and Handlebars (which use double curly braces, {{value}}) and Pandoc (which uses "$", $value$)

Template Metadata Options

Template files can specify options to use when rendering components:

• templateEngine: the templating engine to use instead of the default setting ("handlebars", "mustache", or "pandoc")
  • Default: Whatever value is specified for dmbinder.defaultTemplatingEngine
• escapeHtml (Handlebars and Mustache only): if set, will allow the templating engine to escape HTML content

Component Basics

Component files are fairly simple. They simply contain named data attributes that can be used and reused to insert prebuilt snippets into your markdown formatted campaign documents.

.yaml example:

# This is a comment
singleAttribute: Single Value
parentAttribute:
  childAttribute: Nested Value
  otherChild:
    nestedAgain: Turtles all the way down
listAttribute:
  - Item 1
  - Item 2
  - Item 3
complexList:
  - itemTitle: Title 1
    itemBody: Body 1
    itemCoolAttribute: Cool Attribute 1
    coolnessFactor: 1
  - itemTitle: Title 2
    itemBody: Body 2
    itemCoolAttribute: Cool Attribute 2
    coolnessFactor: 10

.json example:

{
    "singleAttribute": "Single Value",
    "parentAttribute": {
        "childAttribute": "Nested Value",
        "otherChild": {
            "nestedAgain": "Turtles all the way down"
        }
    },
    "listAttribute": [
        "Item 1",
        "Item 2",
        "Item 3"
    ],
    "complexList": [
        {
            "itemTitle": "Title 1",
            "itemBody": "Body 1",
            "itemCoolAttribute": "Cool Attribute 1",
            "coolnessFactor": 1
        },
        {
            "itemTitle": "Title 2",
            "itemBody": "Body 2",
            "itemCoolAttribute": "Cool Attribute 2",
            "coolnessFactor": 10
        }
    ]
}

Component Metadata Options

Component files can specify options to use when being rendered:

• templateItem: the name of the template file (leave off the .md extension) to use by default

.yaml example:

---
templateItem: name-of-template-file
---
name: dummyComponent

It is important to note that in the YAML file, the templateItem attribute is preceeded and proceeded by ---, this is to separate this attribute from the actual component attributes. Unfortunately this syntax (sometimes called "front matter") isn't possible to separate from the rest of the data when using the JSON format, at least in any meaningful way.

.json example:

{
    "templateItem": "name-of-template-file",
    "name": "dummyComponent"
}

Component Auto-Generation

You can add a placeholder element into your documents that can be used to (re)generate your component items. If the setting dmbinder.autogenerateOnRender is enabled, the components will be regenerated when rendering any document to PDF (this will not actually update the source files, only the PDF files that are generated). To generate the component in the source, use the dmbinder.component.autogenerate command with the source you want processed opened and in the active/focused text editor.

Component (Cool-Dude.yaml):

name: Cool Dude
inventory:
  - a Bag of Holding
  - a bedroll
  - rations (x7)
  - 7 gp

Template (cool-dude-template.md):

**Name:** {{name}}
{{name}} is holding {{inventory}}.

Source

<dmb-autogen data-dmb-component="Cool-Dude" data-dmb-template="cool-dude-template"></dmb-autogen>

Output:

<dmb-autogen data-dmb-component="Cool-Dude" data-dmb-template="cool-dude-template">

**Name:** Cool Dude
Cool Dude is holding a Bag of Holding,a bedroll,rations (x7),7 gp.
</dmb-autogen>

Inserting A Component

You can insert a component by right clicking the component in the DMBinder view, unless specified in the component data, you will then be prompted to select the template to use to format the component data.

Inserting vs. Building Component

Selecting "Insert component" or using the command dmbinder.component.insert, inserts the formatted component at the cursor location of the currently opened document.

Selecting "Build component" or using the command dmbinder.component.build, outputs the formatted component into a new document.

Inserting a component example:

Note: Using Custom JSON Schemas

Some components and templates can become increasingly complex, making it difficult to remember how to format certain component values or even which attributes a component has or which are required. You can use custom JSON schema definitions to help here (provided you're using the .json component format instead of the .yaml format). You can learn more in the Custom JSON Schemas footnote.