• Imports
• Anatomy of a tag
• Registering a tag
• Rendering a tag
• Updating a tag

Custom Tags

Custom tags provide a means for you to group common rendering functionality into reusable code blocks. They are only supported when you are using the default template engine for rendering, not when you are using Angular, React or Vue.

No additional include is required to use custom tags - the code supporting them is inside the core.

A custom tag is registered with a given tag name, and consists of 3 parts:

{  
  template:"<div class=\"some class\"><img/></div>
  rendered:function(el, data, instance) {
  
  },
  updated:function(el, data, instance) {
  
  }
}

• template is the HTML to use when rendering the tag. Note that this template is parsed by Knockle, and is subject to the same rendering rules as all templates rendered by Knockle. For further information, see this page
• rendered is a function that is called whenever the tag is rendered for the first time. You are given the DOM element that was rendered, the data that it was rendered with, and the instance of Knockle that is rendering this tag.
• updated is a function that is called whenever the tag is updated, as a result of an update call either on the tag's element or on one of its parents. You are given the DOM element that was originally rendered, the data that it was rendered with, and the instance of Knockle that is rendering this tag.

Tags are registered on instances of the Surface widget. You can do this in two ways:

After the Surface is initialised

var s = toolkitInstance.render({
...
});

s.registerTag("tag-name", {  
    template:"<div data-id=\"${id}\" data-foo=\"${foo}\">The message is ${message}</div>",
    rendered:function(el, data, instance) {
    
    },
    updated:function(el, data, instance) {
    
    }
}); 

In the render parameters

var s = toolkitInstance.render({

    ...,
    
    tags:{
        "tag-name":{  
           template:"<div data-id=\"${id}\" data-foo=\"${foo}\">The message is ${message}</div>",
           rendered:function(el, data, instance) {
           
           },
           updated:function(el, data, instance) {
           
           }
       }
    },
    
    ...

});

Custom tags are rendered as they are found by Knockle. The rendered callback is hit each time a custom tag is rendered for the first time, allowing you to take action if you need to. But all interpolated values are populated automatically by Knockle.

Custom tags are updated as they are found by Knockle. The updated callback is hit each time a custom tag is updated, allowing you to take action if you need to. But all interpolated values are repopulated automatically by Knockle.