HTML Template Engine en

Perhaps you’re familiar with how most wikis have standardized, reusable sections, such as infoboxes at the top right of many Wikipedia articles. Wouldn’t it be cool to have similar templates in Kanka, where you can define standard blocks to invoke throughout your campaign with variable content? Well, this plugin acts as a building block to do just that in as few steps as possible! Check out the image at the bottom for the tl;dr, or read on for the detailed step-by-step!

Step 1: Create a template

1. Create any type of entity (consider making a custom module for templates to keep things tidy) and give it the tag "Template". Give it a conveniently descriptive name and make sure its View permissions are as, um, permissive as necessary for all the places you plan to use it.
2. Apply this attribute template to the entity. It will inject a single attribute (plus _layout).
3. In the HTML Template attribute, type or paste a block of HTML that you want to reuse throughout your campaign with varying contents. Note that this HTML is subject to the Kanka whitelist. For each part of the template you want to insert custom content into, create an element with a unique, recognizable ID. Simple example:

<p>This is a template!</p>
<p>My name is <span id="name"></span>.</p>
<p>Welcome to <span id="location"></span>!</p>

In this (boring) example, the template consists of three paragraphs with some standard text, and two empty spans acting as placeholders (presumably for a name and a location).

Save, and your template is ready to use in as many places as you want.

Step 2: Transclude your template

In any entity, create an advanced mention to your template entity, wherever you want the template to go. (Advanced mentions can be enabled in your profile settings, under Appearance.) Switch to code view in the editor, and locate your mention code. Add the field:attributes parameter to it to transclude the character sheet rather than simply link to the entity, like so: [entity:12345|field:attributes]. Surround the mention code with an HTML element that will 1) tell the template where to go; 2) tell the plugin what to put in the template’s placeholders. Let’s look at an example first, then go over the details:

<span class="template-target hidden">
{"name": "Adam \"Shotgun\" Thompson", "location": "Paraiso"}
[note:7362305|field:attributes<ins class="advanced-mention-name" data-name="Template #21"></ins>]
</span>

• I use a SPAN element for its versatility and because it’s less likely to cause issues in Summernote than a DIV. I give it the "template-target" class, which tells the plugin that this is the destination for the template once populated. I also give it the "hidden" class so it’s invisible until processed. (This will also keep things clean if your campaign is no longer Premium and/or the plugin is disabled.)
• The next line is a JSON object that contains a list of IDs (see "name" and "location" from our template example above) and their values (which will go inside the respective spans). Notice how double quotes in values need to be escaped with a backslash to not conflict with the value delimiters. Each pair of ID/value is separated by a comma, and you can have as many as you want, as long as the corresponding IDs exist in your template.
• Last is the advanced mention code. Make sure to keep it inside the "template-target" element! You can have multiple references to one or more templates on the same page, so each one tries to attach itself to its immediate parent and will abort if that doesn’t have the required class.
• Feel free to put the mention first and JSON second if you prefer, and add line breaks to your JSON for legibility =)
• Values can also contain HTML themselves, just be mindful of quotes (bearing in mind that Kanka will replace any single quotes used for HTML tag attributes like class='orange' with double quotes and mess things up).

And... that’s about it, really. The plugin will create an element that has the structure of your HTML Template attribute, fill it with the values passed by its parent template-target element, and then replace the latter with the resulting HTML block.

All in all, the plugin only does a couple generic, one-size-fits-all operations, but you can build unlimited templates with it (subject to the HTML whitelist of course) and use them in all kinds of scenarios, like infoboxes, stat blocks or modular sections for your articles, creating variants and supplementing them with custom CSS! I would LOVE to see what you build with it!

---

Want to show appreciation for my plugins or request one-on-one CSS help? I accept tips on Ko-fi (no account needed):