For a long time there was no officially supported way to create screens dynamically in Ignition. Screens were created up front by designers/programmers by dropping components on windows and then scripting and configuring them.
There was no dynamic creation of components based on current data from a database or other source of information.
This has changed in Ignition. It started with the Template Repeater which was released in Ignition 7.7.0. This component allows an Ignition template to be configured and repeated any number of times. A vertical or horizontal scroll bar is automatically added to the template repeater when there isn't enough space for all templates to fit within the designated space. This is a great component but has various limitations; for example it only allows one template to be repeated in a single direction.
The Template Canvas was released in December 2014 in Ignition 7.7.2. The Template Canvas is the most powerful, most significant single component to be released by Inductive Automation since Ignition itself was released in 2010.
The Template Canvas makes it possible to dynamically create any number of instances of any number of templates. The position, width and height of each template instance can be configured. If there isn't enough space for all template instances to fit within the designated space scroll bars are automatically added - vertical or horizontal or both. Once all templates are displayed on a screen their position and configuration can be changed through Python scripting.
How to Use the Template Canvas
First a Template Canvas is dropped onto an Ignition window. You will see a box of ant track lines. The Template Canvas is a kind of Ignition container and the ant track lines show the dimensions of the Template Canvas. This shows how much space the Template Canvas will use on the window. Change the position and width and height of the Template Canvas as needed.
The Templates property of a Template Canvas is a dataset that contains template instance information. Each row of the dataset specifies a template to use to create a template instance and its position and layout. Populating this property is what creates and positions template instances. Here is a view of a Templates dataset:
There are different ways to populate the Templates property. One way is to use the Template Canvas Customizer. Right click on the Template Canvas in the designer, hover the mouse over Customizers, then choose Template Canvas Customizer. Using this customizer you can select templates to use and the layout and positioning. The Template Canvas Customizer also lets you input values for any template instance parameters. The Template Canvas Customizer is a static upfront way to create the Templates dataset. Using it is a good way to get started with the Template Canvas.
A dynamic way to create the Templates property (and therefor dynamically create template instances and configuration) is to bind a database query to the Templates property.
Python scripting is the most powerful and flexible way to dynamically create a dataset for the Templates property. Python provides many tools and capabilities to analyze and manipulate data and many ways to access sources of data.
Layout and Positioning
There are two ways to position template instances: Absolute Positioning and Layout Positioning.
Absolute Positioning uses absolute x and y coordinates and values for width and height. The x, y, width and height columns in the Templates dataset are used for Absolution Positioning. x and y coordinates need to be calculated for each template instance.
Layout Positioning uses a powerful and easy to use layout manager called MigLayout. The "layout" column in the Templates dataset is used for Layout Positioning. The layout column holds a MigLayout string for each row in the dataset.
Documentation for MigLayout is here: MigLayout QuickStart
Here is a handy MigLayout cheetsheet: MigLayout Cheetsheet.
Initializing Template Instances
By initializing template instances I mean setting any template parameters for each instance. There are a couple ways to do this.
The Template Canvas Templates property can have a column called "parameters". This column holds a string representation of a Python dictionary. Each item in the dictionary contains the name of a template parameter and a value to be set for the template parameter. The Template Canvas Customizer uses the "parameters" column to set parameter values for template instances.
Another way is to use the initializeTemplate extension function on the Template Canvas. Remember an extension function is an editable function on a component that exists to customize it.
The initializeTemplate function is called for each template instance created by the Template Canvas. The initializeTemplate function takes as an argument the template that it is called for. This extension function provides a chance to execute a Python script for each template instance to configure it, set template parameters etc. Each time the Template Canvas Templates property changes the initializeTemplate extension function runs for each template instance.
Template Canvas Video & Demo
I made a Template Canvas demo project and a video that shows how to use the Template Canvas. To see the video and get a copy of the Template Canvas demo project signup for my email list.
You are free to have and use the Template Canvas demo project for your own purposes.
Here's a screen shot of the Template Canvas demo application:
17 April 2015
Does the template canvas accepts UDT params?
If yes, which is the correct syntax for write them inside the template canvas customizers or Its related dataset?
25 June 2015
interested in seeing the demo project. did not immediately receive link to demo project after signing up to email list.
25 June 2015
The demo project can be downloaded from this link: http://nickmudge.info/download/patemplatecanvasdemo.proj
25 June 2015
thanks for the quick response Nick.
30 December 2015
Nick, do you know how I can pass a dataset as a template canvas parameter?
It seems I can pass strings and integers but not a dataset.
I don't mean to treat this as a support blog but IA is unavailable until the new year so I was curious if you ever ran into this.
WARN [TemplateCanvas-AWT-EventQueue-2] Unable to parse parameters as JSON on row 0.
org.json.JSONException: Expected a ',' or '}' at 158 [character 159 line 1]
30 December 2015
No problem. Yes, you are right, you can't pass a dataset as a template canvas parameter to a template instance.
There is a way around that problem that I have used very successfully.
Store your arguments to the template canvas template instances in a dataset somewhere else. You can store datasets in datasets if you want to (or store your data as a Python dictionary literal string).
Once you did that then use the "initializeTemplate" extension function on the template canvas to populate the template paramters of the template instances in the template canvas.
You can use the name of a template instance as a key or index for looking up a value in a dataset to use for a specific template instance.
Hope this helps, if you need more clarification let me know.