Skip to main content

Templating 2#

One great feature of the jsPlumb Toolkit is the way client side templating is baked right in - your node, group and port definitions in the View declare the id of some template to use and the Toolkit takes care of the rest.

This page discusses a new package in 5.6.0 - @jsplumbtoolkit/browser-ui-templates-2 - which contains a rewrite of the original templates package with 3 key goals:

  • remove dependency on eval and with, making the template engine compatible with such sandbox environments as Salesforce Lightning
  • improve update speed
  • provide better integration with template literals
note

If you are using the Angular, Vue2, Vue3, React or Svelte integration, then you're not going to be using this template engine.

Changes from original templates#

There are three main changes in templates-2:

  • values are interpolated using {{someValue}} instead of ${someValue}
  • Inline IF statements are not supported
  • Arbitrary execution of Javascript is not supported. Use template macros instead

As a quick comparison, consider this template written in the format that the original templates package uses:

<script type="jtk" id="tmplTable">    <div data-id="${id}">        <h1>${id.substring(0, 5)}</h1>        <p>${content}</p>    </div></script>

Here, we extract id and write it to the data-id attribute. We truncate the ID and write it to an h1, and then we have a paragraph containing content. In templates-2 we'd write this template this way:

<script type="jtk" id="tmplTable">    <div data-id="{{id}}">        <h1>{{#truncatedId}}</h1>        <p>{{content}}</p>    </div></script>

truncatedId is a template macro, which will have been supplied as a render parameter:

toolkit.render(someElement, {    templateMacros:{        truncatedId:(data) => data.id.substring(0, 5)    }})

Limitations#

When using the default template engine, your templates must return a single root node. If you return multiple nodes, the Toolkit will use the first node only.

Inferring Template IDs#

As shown above, the node and port definitions passed as part of the view parameter on a render call allow you to specify a template to be used to render an instance of the given type. Sometimes you will find that you have nothing other than a template directive in a node or port definition. So to cut down on boilerplate, the Toolkit will make a guess at a suitable template id if you do not provide.

The inferred template id consists of "jtk-template-" as a prefix, followed by the type of the object. So in the previous example, a node of type table would have an inferred template id of jtk-template-table.

Custom Template Resolver#

The default template resolution mechanism is to look for a <script> element in the DOM with an ID matching the ID of the template to retrieve. You can supply your own template resolver like this:

toolkit.render(someElement, {  view:{ ... },  templateResolver:function(templateId) {    // find the matching template and return it - as a String.  }});

Providing Templates Directly#

Another option is to pass a map of templates into the render call:

toolkit.render(someElement, {  view:{ ... },  templates:{    type1:"<div><span>type 1</span>...</div>",    type2:"<div><span>type 2</span>...</div>",  }});

For some use cases, where the templates are not overly complex, this can be handy. One caveat to note with this approach is that Knockle expects double quotes for attributes, so if your template has any attributes declared you need to use escaped double quotes:

toolkit.render(someElement, {  view:{ ... },  templates:{    type1:'<div class="foo"><span>type 1</span>...</div>',    type2:"<div><span>type 2</span>...</div>",  }});

External Templates#

To help you organize your templates better, you can store them in external files and reference them via a script import in your HTML:

<script type="text/x-jtk-templates" src="../palettes/shapes-svg.html"></script>

The key here is that the type is text/x-jtk-templates. There may be one or more templates declared in the specified file. This example is one from one of the Toolkit's unit tests; the file contains several templates. Here's the first two:

<script type="jtk" id="tmplRectangle">    <svg:svg style="position:absolute;left:0;top:0;">    <svg:rect width="{{width}}" height="{{height}}" x="{{strokeWidth}}" y="{{strokeWidth}}" fill="{{fill}}" stroke="{{stroke}}" stroke-width="{{strokeWidth}}"/>  </svg:svg></script>
<script type="jtk" id="tmplCircle">   <svg:svg style="position:absolute;left:0;top:0;">    <svg:circle class="jtk-svg" cx="{{cx}}" cy="{{cy}}" r="{{r}}" fill="{{fill}}" stroke="{{stroke}}" stroke-width="{{strokeWidth}}"/>    <jtk-endpoint port-id="port" port-type="basic"/>  </svg:svg>    </script>

You can have multiple x-jtk-templates scripts declared in your html. Note, though, that the loading of these scripts postpones the firing of the ready event in the Toolkit, so you should ensure you're not getting any 404s and what you are loading is loading quickly.

Recado#

The templates-2 package is known internally as 'Recado'. It uses a strict XHTML syntax and can run both in the browser and headless on the server.

These are the key points:

  • Format is strict XHTML: all tags must be closed. This means
<input type="text"></input>

for example.

  • Use only double quotes for attributes:
<div class="foo"></div>

not

<div class='foo'></div>

Inside attribute values, however, you can use single quotes:

<r-if test="value == 'foo'">...</r-if>

Tags#

Each#

With Objects in an Array#
{  someDataMember:[    { id:"one", label:"value1" },    { id:"two", label:"value2" }  ]
<ul>    <r-each in="someDataMember">        <li id="{{id}}">{{label}}</li>    </r-each></ul>    
With Arrays in an Array#
{  someDataMember:[    [ "one", "value1" ],    [ "two", "value2" ]  ]
<ul>    <r-each in="someDataMember">        <li id="{{$value[0]}}">{{$value[1]}}</li>    </r-each></ul>    

The point to note here is that the current array is exposed as the variable $value.

With an Object#
{  someData : {    id:"foo",    label:"FOO is the label",    active:true,    count:14  }
<table>  <r-each in="someData">    <tr><td>{{$key}}</td><td>{{$value}}</td></tr>  </r-each></table>

The point to note here is that each entry is presented to the template as an object with $key and $value members.

Uniquely identifying child nodes#

In some cases, such as the Database Visualizer application that ships with the Toolkit, you might want to use the r-each element to loop through your data and add ports to your nodes. For instance:

<ul class="table-columns">    <r-each in="columns" key="id">        <r-tmpl id="tmplColumn"/>    </r-each></ul>

This is how the database visualizer application renders the columns in a table. tmplColumn looks kind of like this:

<script type="jtk" id="tmplColumn">  <li class="table-column table-column-type-{{datatype}}" primary-key="{{primaryKey}}" data-port-id="{{id}}">        ...             </li></script>

with some details removed for brevity. The thing to note is that this template, which is looped over, generates ports for the node. Note the key attribute on the r-each element above. It instructs Recado on how to get a unique identifier for each value in the loop. Thus, if you change the data in some port, Recado will just update the port's element, since it can use the key property to identify the existing element. Similarly, if you add a new port, Recado will use the key to determine that it has no current element, and if you remove a port, Recado will use the key to determine that the element corresponding to that port is no longer needed, and will remove it.

Recado will log a message to the console any time the r-each element is used without a key. If you do not supply a key then Recado will not be able to perform an update of the loop.

If#

Unlike its predecessor, Recado supports only the <r-if > element. Inline {{if ...}} statements are not supported.

Existence#
<r-if test="someObjectRef">    <div>hola</div></r-if>

An existence test will be evaluated according to Javascript's "falsy" rules. If you are unfamiliar with falsiness in Javascript, you might like to take a look here

Expressions#
<r-if test="foo == 5">    <div>hola</div></r-if>

Expressions are limited by the following rules:

  • the only comparators supported are ==, ===, <=, <, >, >=
  • javascript expressions are not supported (eg someMethod(foo) == 5)

Comments#

Comments follow the standard XHTML syntax:

<div><!--    a comment    <span>Maybe some code was commented</span>--></div>

Comments are stored in the parse tree for a template. This may or may not prove useful.

Embedding HTML#

By default Recado treats text as plain text. Unlike its predecessor, Recado does not support embedding arbitrary HTML.

Nested Templates#

With specific context#
<div>  <r-tmpl id="nested" context="someItem"></r-tmpl></div>
Inheriting parent context#
<div>  <r-tmpl id="nested"></r-tmpl></div>

The difference between these two examples is that in the first, an item called someItem is extracted from the current dataset, and passed in to the nested template, whereas in the second, the nested template is passed the exact same data that the parent is currently using to render itself.

Inside an r-each loop#
<div>    <r-each in="someList">        <r-tmpl id="nested"></r-tmpl>    </r-each></div>

This is similar to the example immediately above - the nested template inherits its parent's context, but in this case the parent's context is currently some item from the list. You can also use context in this situation:

<div>    <r-each in="someList">        <r-tmpl id="nested" context="someMemberOfTheListItem"></r-tmpl>    </r-each></div>

The context for the nested element here is the someMemberOfTheListItem member of each list item.

With complex context#

You are not limited to extracting single variables from the current context to pass in to a nested template. You can specify a complex object too:

<div>  <r-tmpl id="nested" context="{id:foo, label:'Hello'}"/></div>

In this example, foo will be extracted from the context in which the current template is executing, and Hello is a hardcoded string.

Accessing nested properties#

You can also specify properties that are nested inside the current context, either with dotted notation:

<div>  <r-tmpl id="nested" context="{id:record.id, label:'Hello'}"/></div>

or by naming the property:

<div>  <r-tmpl id="nested" context="{id:record['id'], label:'Hello'}"/></div>
Dynamic Template Names#

You can lookup the name of a nested template at runtime, for example consider these templates:

<script type="jtk" id="someTemplate">    <h3>{{title}}</h3>    <r-tmpl lookup="{{nestedId}}" default="def"/></script>
<script type="jtk" id="green">    <h3>GREEN</h3></script>

Here we see the ID of the nested template is derived from the nestedId property of the data we are rendering:

{    title:"example",    nestedId:"green"}

default allows you to provide the ID of a template to use if the lookup fails.

### Rendering SVG

To render SVG elements you must prefix the tag with a namespace:

<svg:svg width="50" height="50">  <svg:rect x="10" y="10" width="10" height="10"></svg:rect></svg:svg>
### Updating Data

Given this template for some node type:

<div class="someNode">    <span>{{title}}</span>    <ul>            <r-each in="someDataMember">            <li>{{id}}</li>        </r-each>    </ul></div>

and this call to a Toolkit instance:

var node = toolkit.addNode({  title:"FOO",  someDataMember:[    { id:"one" },    { id:"two" },    { id:"three" }  ]});

You'll get a node element with a span that says FOO, and a list of three items: one, two and three.

Calling updateNode on the Toolkit instance associated with this node:

toolkit.updateNode(node, {   title:"FOO-NEW",   someDataMember:[       { id:"un" },       { id:"deux" },       { id:"trois" }   ]});

will result in a node element with a span that says FOO-NEW, and a list of three items: un, deux and trois.

Updating the class attribute#

Recado won't update the class attribute once a template has been written. Since the update method can only write values for classes that were in the template, there's a risk that any classes added by other parts of your app would be removed. For example say you have this template:

<div class="{{nodeType}}">  FOO</div>

If you render this with {nodeType:"start-node"} then you'd end up with a div with class start-node. Then say some code comes along and does this:

$(myDiv).addClass("selected");

Now you've got a div with class start-node selected. If you then called update, Recado would re-write the class attribute to have only the nodeType class; probably not at all what you want. In this scenario you are better off using attribute selectors.

### Template Macros

These are a means for you to inject values into your templates that require computation at runtime. You indicate to the template engine that you wish to invoke a macro by prefixing the value to interpolate with a hash. A slightly more convoluted version of the above example:

<script type="jtk" id="tmplTable">    <div data-id="{{id}}">        <h1>{{#truncatedId}}</h1>        <p>{{content}}</p>        <p>{{#concatTags}}</p>    </div></script>

We use two macros here:

toolkit.render(someElement, {    templateMacros:{        truncatedId:(data) => data.id.substring(0, 5),        concatTags:(data) => data.tags.join(" ")    }})

The data argument passed in to each macro is the vertex's backing data. For example, for this setup, we might have this payload:

{  "id": "78947329843h2hjlkshkfasd789",  "content": "Loretta ipsum",  "tags": [ "foo", "bar", "qux"]}