The client-side templating provides a mechanism that allows the Client Framework 2 page authors to separate the presentation layer from the data. This mechanism is intended to be used when the client-side needs to display the data that can change over the lifetime of the page on the client. Templates are just XDIME pages containing slots and/or conditional statements. Slots are placeholders that are dynamically filled with the data, and conditional statements can be used to select proper elements for processing. The data must be provided as JSON either in the initial page, or as a response to an AJAX request.
The client-side templating provides a mechanism that allows the Client Framework 2 page authors to separate the presentation layer from the data. This mechanism is intended to be used when the client-side needs to display the data that can change over the lifetime of the page on the client. Templates are just XDIME pages containing slots and/or conditional statements. Slots are placeholders that are dynamically filled with the data, and conditional statements can be used to select proper elements for processing. The data must be provided as JSON either in the initial page, or as a response to an AJAX request.
The client-side templates can:
dynamically update the data associated with a template;
conditionally select a part of a template body based on the associated data;
set the source of an image from the data;
set the destination of an anchor element from the data;
nest components within a template;
nest custom client code within a template;
be used in a renderer with a view/model/renderer component.
Behavior of various Client Framework 2 features depends on the context within which they are used. The context consists of the following two aspects:
This is the id attribute of a component. If no id was explicitly supplied by the page author, then this is the automatically generated identifier.
This is the identifier of the property, for example, the value that would be stored in the property attribute of the cf2:param element within the cf2:on element. If this does not explicitly specify the component, then it is relative to the current component, which has just been set.
The context can be changed during processing of XDIME elements, and applies to the element that changed it and its body. Changing the context changes all aspects of the context, e.g. it is not possible to change the default property without also changing the current component.
A slot is a placeholder that is populated with the content when the data bound to it is set or changed. Each slot is bound to an observable property and has a number of associated JSON paths. The slot responds to changes in the property's value by evaluating its paths against the value and using the results to update the page accordingly.
Slots and conditional statements support optional component and property-value attributes. The component attribute references a component. The client-side value is the object representation of the component. The property-value attribute specifies the property against which the slot will evaluate its paths.
The Client Framework 2 supports three types of slots:
Conditional statements determine whether the content is displayed on the client or not. This functionality is provided by the cst:switch element. It can contain one or more cst:case elements followed by an optional cst:otherwise element. The cst:case element tests the value of the cst:switch element against a fixed value, and if they are equal, then the element is selected for processing. The cst:otherwise element specifies a case to be selected for processing if none of the cst:case elements within the containing cst:switch element are selected. Please note that conditional statements do not affect any nested components or scripts. In particular, the script elements behave in the same way as if they were outside the conditional statements.
| Name | Purpose |
|---|---|
| cst:case | One of a number of possible matches which could be selected when processing the cst:switch element. |
| cst:otherwise | Specifies a case to be selected for processing if none of the cst:case elements within the containing cst:switch element are selected. |
| cst:switch | Container for one or more cst:case elements and an optional cst:otherwise element. It is used to choose between a number of mutually exclusive alternatives. |
Selects a specific object from a JSON data structure in a similar way as XPath allows for traversing over an XML document. The following table lists JSON expressions supported in the Client Framework 2.
The paths are processed as a series of sequential steps. The processing of a JSON path starts with an initial object that is context dependent. If the path is simply '.', then the initial object is returned as the result. Otherwise the initial object is used as an input for the first step, the output from the last step is the result of processing the path, and the inputs to and outputs from the intermediate steps are exchanged between them. If, at any point, a step returns null, then the processing stops immediately and the path is assumed to have a null value.
There are two basic types of steps:
Property step: this step treats its input as a Map. If the input is not a Map or the property could not be found, then the output is null, otherwise the output is the value of the property.
Array step: this step treats its input as an array. If the input is not an array or the index is out of range, then the output is null, otherwise the output is the value at the given index.
The following table provides several examples illustrating the use of JSON paths.
| JSON path | Description |
|---|---|
| <cst:a href="."/> | Selects the object against which the path is to be resolved. |
| <cst:a href="xyz"/> | Selects the 'xyz' property of the object against which the path is to be resolved. |
| <cst:a href="[2]"/> | Selects the 2nd item of the array against which the path is to be resolved. |
| <cst:a href="xyz[2]"/> | Selects the 2nd item of the 'xyz' array property of the object against which the path is to be resolved. |
| <cst:a href="'1 2 3'[2]"/> | Selects the 2nd item of the '1 2 3' array property of the object against which the path is to be resolved. |
| <cst:a href='"1 2 3"[2]'/> | Selects the 2nd item of the "1 2 3" array property of the object against which the path is to be resolved. |