Templates

While expression based attribute values obviate the need for script to generate base SVG elements, defining non-SVG namespaced elements to instantiate these objects is still handy. In CSVG one can use templates to define the content that is to be rendered in place of the custom element. The RCC-XSLT syntax proposed in the SVG 1.2 working draft is used.

Why use XSLT?

There are a couple of reasons why XSL templates should be used as the prototyping mechanism for CSVG. Firstly, it is a widely used language for specifying transformations from one XML grammar to another. Rendering custom content is exactly this problem. XSLT, being XML, is easily integrated into an SVG document. Its declarative nature is more easily processed by a user agent than free form script.

The issue of shadow tree regeneration is an important one. With script based RCC, the author must explicitly control when and how the shadow tree is to be regenerated. This will mostly be by attaching DOM mutation event handlers to the custom element. Because the initial shadow tree generation is done using script it is difficult for the user agent to analyse it to determine the minimum changes necessary, automatically. When XSLT and constraints are used, the constraints can be set up to depend on the custom element's attributes, so that changes to the custom element will automatically result in an update in the shadow tree.

Animation could also be specified on custom elements, something which cannot be done with current RCC. Elements in the shadow tree could have attributes which depend on animated attributes of the custom elements, resulting in much more flexibility in animation over what is current possible.

Template examples

Example 5 — Graph

Here is an example for specifying nodes, arcs and labels in an undirected graph.

This example, graph.svg, will have a list of ex:node elements which specify the coordinates of the node and also the label which will be displayed on the node. Corresponding ex:arc elements will be used to specify lines to be drawn between particular nodes. These arcs also have labels.

The ex:arc elements use a string to refer to the ID of the nodes the arc is to connect.

The ex:graph element here is just a container for the ex:node and ex:arc elements. It makes sure though that the arcs are rendered before the nodes, so that the lines do not appear over the top of the circles.

The shadow tree for the ex:node element is reasonably simple. First, it defines a few CSVG variables to hold information given in the ex:node's attributes. Defined also is b which holds the bounding box of the node's label. If the label would extend past the edge of the default 30 radius circle, the size of the circle is increased. This is done using the c:max function in the r attribute of the two circles in the template.

The first circle is an outer ring for those nodes which are marked as "final". It has a constraint on the display attribute which will prevent it from beind rendered if the node is not a final node. Finally there is the text element into which is copied the label specified on the ex:node element.

The template for the ex:arc element is similar. Note that the x1, y1, x2 and y2 variables (defining the start and end coordinates of the arc) use the c:instance function to access the custom element which instantiated this shadow tree. XPath is then used to select the sibling ex:node element so the strat and end coordinates can be found.

After the CSVG variable definitions the line element which is the arc is copied to the shadow tree. Finally, a text element is used to display the arc label. A white rect is drawn just before this to make sure the label is legible over the line.

Example 6 — Flowchart

The next example is a translation of the RCC flowchart example from the SVG 1.2 working draft.

flowchart.svg has an ex:flowchart element which contains a series of ex:processNode and ex:terminalNodes.

The template first declares a few CSVG variables for the attributes given on the outer ex:flowchart element which specify the dimensions of the object. A rect is then drawn to show the outline of the flowchart. As in the graph example, the child custom elements (the ex:processNode and ex:terminalNodes) are copied into the ex:flowchart's shadow tree, upon which these node elements will have their own shadow trees generated.

The templates for the ex:processNode and ex:terminalNodes are reasonably similar. Shown here is the code for the ex:processNodes. The differ only in that for process nodes a circle is drawn, for terminal nodes, a circle. Both of these are positioned to be layed out horizontally, one after the other. Their x coordinates depend on the cx CSVG variable, which calculates the horizontal position using the current position number $pos (just the count of how many node elements precede the current one in the document tree), and the step variable, which is the amount of horizontal space to leave between each node. Next, a text is placed in the middle of the node. Its content is selected from the character content of the ex:terminalNode or ex:processNode that is currently being processed. Finally, a line is added to the shadow tree. Its display property is constrained to be displayed only if this node isn't the last in the flowchart.

The script in the RCC example does essentially the same thing as this template. It loops over the node elements to calculate the the total width and the positioning of the nodes and then copies the SVG objects into the shadow tree for them to be rendered. The RCC example cannot handle updates to the custom elements, though. This type of functionality is currently not built in to RCC, so the author must explicitly attach DOM event handlers so that script can be run when the subtree is modified. This could could simply re-run the function which generated the shadow tree in the first place, but this will probably be inefficient if only a small change was made. If the author wants to make only the necessary changes, they must keep a track of the dependencies in their code manually. In the CSVG solution, this dependency tracking and update propagation is handled automatically.

Example 7 — Simple buttons

Say that we want to make a simple button widget. This button should just be a rect with some text centered on it. The button also should be able to run some user specified code when it is clicked.

To generate the buttons in this example, button.svg, we need three things — the template definition, the template instantiation elements and the script to handle the behaviour of the buttons.

Here we have two custom elements to insert buttons into the document. The ex namespace is declared on the root svg element earlier in the document. The ex:button elements have attributes for the coordinates at which to place the button and an event handler to have some script run when the button is clicked. The text inside the element will be used as the button's label.

The template element defines what content will be used as the shadow tree for the ex:button element. The template starts with a few CSVG variable elements. The x and y variables use the c:instance function to get the x and y attribute values from the ex:button element which instantiated the template. The w and h variables will store the width and height of the text label of the button.

Next is the rect which makes up the base of the button. Its x, y, width and height attributes are written in terms of the variables defined above it. Event handlers are assigned to control the behaviour of the button. Following the rect is a couple of lines to give the button a three dimensional look.

Finally in the template there is the text element which is used for the button label. The content of the text element is generated using the XSLT value-of element to select the text nodes which are children of the ex:button element.

Notice that the rect's onclick event attribute gets its content from the onbuttonclick of the custom element. In the example here, this is all that is needed for a custom event to be supported. In more complex situations, it may be necessary to synthesize an event in script.

The script here handles the behaviour for the button widget. When the mouse is moved over or clicked on the button, the rect in the shadow tree is modified to make its colour change.

Constraint propagation will occur if the attributes of the custom elements are modified. If an element in the shadow tree uses the c:instance() function to refer to a value on the custom element, this value will be updated in the shadow tree automatically, just like for non-templated elements.

Example 8 — Complex buttons

The button example can be extended to allow arbitrary SVG content as the button's label.

This example, complexButton.svg, uses a circle and a rect as the button's label. Only a small modification to the template used in the previous example is needed to handle this.

In place of the text element there is an g element. This is used to position the content over the button. The transform attribute is used to specify a translation in terms of the $x and $y variables. The xsl:copy-of element is used to copy the children of the ex:complexButton template instantiation elements to become children of this g element.

Example 9 — Checkboxes

Another simple widget example is given here in checkbox.svg.

Example 10 — Vertical layout container

Templates can be written to arrange SVG objects so that common layout problems don't have to be handled explicitly. The first layout example here is a vertical layout element, which arranges its child elements in a column.

This example, vlayout.svg, uses a template to place each of the child elements of the custom element at differing y coordinates.

The t:vertical-layout element just contains the SVG elements which will be layed out. Since each element will be placed in a g element which has been translated to the current position in the column, each of the SVG elements here are placed close to (0, 0). The text element, for example, has its y attribute set so that the top of the text is aligned with y=0.

The template works by copying each of the child elements into the shadow tree one by one. The xsl:for-each element will iterate over each element. The current y coordinate and the maximum width of the layout in each iteration are kept track of by generating CSVG variable elements that build upon previous variable elements with the same name. After the iteration, two variables are defined for the final y and maximum width values, which are used earlier in the template for the dimensions of the rect that acts as the background colour for the layout widget.

The shadow tree for the t:vertical-layout element is shown below.

In this example clicking on the black rectangle in the upper right corner will increase the height attribute of the white rect. The objects below this rect will be shifted down to accommodate the rect's new height.

Example 11 — Grid layout container

To lay out SVG objects in a grid is more complex. Many variables must be set up to ensure the x coordinate of all cells in the one column are equal, and the y coordinates of all cells in the one row also.

In this templated grid example, gridt.svg, we want to be able to lay out objects in a grid with an arbitrary number of rows and columns. We'll use a specification similar to HTML tables, which uses one element to enclose the whole table, one to enclose a row of elements and one to enclose one cell in a row.

The template to position these objects correctly will need to iterate over each t:cell and copy its contents into the shadow tree, wrapped by an g element so it can be repositioned.

The xsl:for-each element is used to iterate first over each t:row in the grid. Each iteration, an XSLT variable is defined to store the current row number. Note that this is not a CSVG variable; this variable exists while processing the template and is not copied into the shadow tree like CSVG variables are. Inside this loop is another xsl:for-each to iterate over each t:cell element in the current row. For each of these cells, an g element is inserted into the shadow tree containing the contents of the t:cell.

See that the the x and y attributes of the svg element use braces to evaluate an expression at template processing time. This is used here to construct the name of the variable being referred to. So, the first cell in the grid will have its g element with transform attribute transform="concat('translate(', $x1, ', ', $y1, ')')" and the last cell will have transform="concat('translate(', $x1, ', ', $y1, ')')". Following that, two CSVG variables are defined which will hold the width and height of the current cell. Again, braces are used to construct the variable anmes.

The next task for the template is to generate variables which will store the maximum width of the cells in each column. These variables will be called min1w, min2w, etc. — one for each column. This begins by iterating over each of the cells in the first row of the grid. For each of these cells, a CSVG variable is created. This variable should be equal to a c:max function call of the width of the cell in each row. The $value XSL variable is used here to construct the complex value attribute for the c:variable. It will generate an attribute with value max($c11w,$c12w,$c13w) for the first column. Similarly for the other two columns.

The same thing is done for each row of the grid. Variables called r1h, r2h, etc. are generated which hold the height of each row.

Finally the template creates CSVG variables which store the x coordinates of each column and the y coordinates of each row. xsl:choose is used to create the variable x1 equal to the x attribute given on the t:grid element, and other xn variables which are equal to the previous x coordinate plus the width of the previous column. It is these variables which are used on the g's transform attribute at the start of the template.

The shadow tree that is finally generated in this example is shown below.

In this example clicking on the purple rect in the centre of the grid will cause its width or height to be increased. The rest of the elements in the grid will move over appropriately as the constraints are updated.

---