Create Viewlet using Image Template

Image viewlets allow you to map data points to visual representations of the data (in SVG format). In this article, we will use the simple example of battery percentages.  Using a dataset that contains a sampling of batteries, we will map the charge percentages from the battery records to two visual elements in an SVG image template:

• the background color of the battery image
• a text label on the same battery image  

When you save an image template, the name you assign is used to store the SVG file. Once the SVG file is saved, you can write a data query that uses the saved image template.

To Create an Image Viewlet:

1. In version 11.2, on the left toolbar, select  Viewlet  > Create Viewlet. You can also click the blue Viewlet button .
2. Choose the Create Viewlet Using Image Template option and click Create.
3. Name the viewlet.
4. Name the Image template. As explained above, the Image template name is used to store the SVG file.
5. Click Save.

The image viewlet editor is made up of four panels:

• jKQL Query Editor (upper left)
• Selected Element Rules Editor (upper right)
• SVG File Editor (lower left)
• Image Preview (lower right)

All four panels play a role in the battery example. However, the following sections of this article pertain directly to the battery example, in this order:

• jKQL Query Editor (upper left). Create a query to obtain data for your battery image viewlet.
• SVG File Editor (lower left). Enter the code for the battery SVG image.
  • Create and group the objects that make up the battery on the All HTML tab or the Main tab.
  • Store reusable definitions, such as gradient fill attributes for styles, on the Defs tab.
  • Build CSS image and text styles for use in your image template on the Style tab.
  • Rules tab
    • Associate your image file with data by applying Binding rules.
    • Alter the background color of the battery image based on percentage conditions by applying Class rules.
    • Alter the label on the battery image based on percentage conditions using Text rules.

JKQL Query Editor (upper left)

Use the jKQL query editor in the upper-left corner to enter a query to obtain data.

For example, this query displays the battery records as a table:

get Dataset fields all where DatasetName = 'battery' show as table

Selected Element Rules Editor (upper right)

In the Selected Element Rules Editor panel (upper right), you can edit the rules for the selected object (as long as other elements do not use the same rule). See Editing rules for a selected element.

For more information about viewing and editing all rules in an SVG file, see Rules Tab.

SVG File Editor Actions (lower left)

In the SVG File Editor (lower left) you can edit all elements of the SVG file for the image viewlet. See SVG File Editor Tabs (lower left) for more information about the six tabs in this editor.

Create objects and groups

As explained later in this article, the All HTML tab contains all HTML code associated with the SVG image; the Main tab contains the code for elements that are rendered.  Therefore you can create objects in either tab.

Create objects

To create an object, enter the HTML code for the object in the All HTML or Main tab. 

For example, the code for a rectangle would look like this:

<rect x="0" y="0" width="650" height="320" rx="64" ry="64" fill="transparent" />

However, most objects do not stand on their own, but are a single part of a more complex representation. Even one part of a diagram may contain several individual shapes. For this reason, it is recommended that objects be arranged in groups. Grouping elements makes it easier to apply the binding rules that will control how the objects appear, because you can apply one rule to a collection of objects. 

For example, the following three shapes form the exterior and interior elements of the battery image that is being used for this example:

Exterior shape (transparent rectangle with rounded corners)

<rect x="0" y="0" width="650" height="320" rx="64" ry="64" fill="transparent" />

Interior shape (offset from, and inside, the exterior shape; a rounded rectangle with no border)

<rect x="20" y="20" width="610" height="280" rx="56"

        ry="56" stroke="none" />

Vertical line representing the cathode end of the battery

  <path d="M670,110 h10 q5, 0 5,5 v90 q0,5 -5,5 h-10 z">

Create groups

To group these elements, wrap them in the SVG element <g> tag.

<g data-is-main='true' >

  <rect x="0" y="0" width="650" height="320" rx="64" ry="64" fill="transparent" />

  <rect x="20" y="20" width="610" height="280" rx="56" ry="56"

    stroke="none" />

  <path d="M670,110 h10 q5, 0 5,5 v90 q0,5 -5,5 h-10 z">

</g>

Create text

This example shows how you would display the word “Test” as part of the SVG image:

<text x="25" y="50">Test</text>

See Text Rule Examples for specific information about how text is displayed for the battery example.

 

SVG File Editor Tabs (lower left)

The SVG File Editor has six tabs: the All HTML tab, Main tab, Templates tab, Defs tab, Style tab, and Rules tab.

All HTML tab

The first tab (All HMTL) includes all the required HTML code associated with the SVG  image. The other five tabs represent sections of the code.  The tabs make navigation easier by allowing you to skip to different sections within it.

Main tab

The Main tab allows you to focus only on what is rendered (for example, elements such as shapes or text). For example, the code below renders a battery image:

<g data-binding-rules="bind-battery">

  <rect x="0" y="0" width="650" height="320" rx="64" ry="64" fill="transparent" />

  <rect data-class-rules="fully-charged partly-charged depleted" x="20" y="20" width="610" height="280" rx="56" ry="56"

    stroke="none" />

  <path d="M670,110 h10 q5, 0 5,5 v90 q0,5 -5,5 h-10 z">

</g>

When you click a portion of the battery image in the Image Preview panel, the Main tab is shown.  

Both the Main and Templates tabs include two buttons at the bottom of the panel so you can choose how to view the content:

•  Click SVG to view the code for the selected element.
  
  
•   Click Raw preview to view the element as it would look without rules applied.
  

Select with Cursor Toggle

The Select with Cursor toggle icon on the Main tab allows you to select elements from the SVG File Editor panel.

	OFF. By default, the Select with Cursor toggle is off. To turn it on, click it once.
	ON. When the Select with Cursor toggle is on, you can use your cursor to select elements from the code in the Main tab. You can either click and drag your cursor across the code or, for elements of a single line of code, double-click the line of code to select the element. Once the element is selected, the Selected Element Rules Editor panel becomes available so you can add rules to the element.

 

Templates tab

For information about the Templates tab, see Image Viewlet Example: USA Weather Map [LINK].

Defs tab

The Defs tab is for the <defs> element, which can be used to store definitions or objects that will be rendered elsewhere in the code. For example, it can be used to store shapes, images, or color gradients. In the example below, the Defs tab stores the values associated with the green, yellow, and red color gradients for the battery image. These definitions are used in the fill styles that are applied to the rectangle portion of the battery image according to Class rules.

<linearGradient id="success-gradient" x2="0.35" y2="1">

  <stop offset="5%" stop-color="#4e8b24" />

  <stop offset="95%" stop-color="#1F6E0C" />

</linearGradient>



<linearGradient id="warning-gradient" x2="0.35" y2="1">

  <stop offset="5%" stop-color="#faad08" />

  <stop offset="95%" stop-color="#b47300" />

</linearGradient>


<linearGradient id="error-gradient" x2="0.35" y2="1">

  <stop offset="5%" stop-color="#A20000" />

  <stop offset="95%" stop-color="#840C00" />

</linearGradient>

Style tab

In the Style tab, create CSS classes to control how elements are formatted.  Then you can set up Class Rules to apply these styles to elements. As a result, the formatting of elements is standardized and it is easier to make changes to multiple elements at once. For example, a style for text might include size, font, and color. A style for a rectangle might include size, border width, and shading.

See Class rules to learn about how styles are applied in the battery example.

Rules tab

Rules are displayed on the Rules tab of the SVG File Editor. On this tab, you can view and edit all existing rules in the SVG image file, regardless of the number of elements that use each rule.

Rules for a specific element are also available in the Selected Element Rules Editor panel. However, if more than one element uses a rule, you cannot use the Selected Element Rules Editor. You must instead use the Rules tab of the SVG File Editor.

Rules tab procedures

Add a rule

1. Click .
   
2. Add a name for the rule in the Rule name field.
3. Set Rule conditions. In the example below, the condition is the DatasetName (DatasetName = “battery”). When the condition is met, the rule will be applied.
4. (Optional.) To preview your changes, click Preview.
5. Continue to make changes until you have completed edits to the image template.
6. To save changes and close the editor, click Save in the lower-right corner of the window.

View a rule

After a rule has been created, you can use the buttons at the bottom of the Rules tab to determine how you want it to be displayed:

• Click Rules in HTML to display rules in HTML code only:
   
  
• Click Rules editor to display rules in the user-friendly graphical user interface format:
  
  

Edit a rule

1. On the Rules tab, Expand the type for the rule you want to edit (for example, Binding, Drilldown, or Class).
2. Make your changes to the Rule name or Rule conditions.
3. (Optional.) To preview your changes, click Preview.
4. To save changes, click Save in the lower-right corner of the window.

Delete a rule

1. On the Rules tab, Expand  the type for the rule you want to delete (for example, Binding, Drilldown, or Class).
2. Click .

To learn how to view and edit rules for a specific element, see Editing rules for a selected element.

Binding rules

Binding rules bind SVG elements or groups of elements to sets of data. When elements are grouped, the binding rule for the <g> tag is applied to all grouped elements.

The Binding Rule for the battery example shows that the battery image is associated with, or bound to, the dataset called “battery.”

Drilldown rules

Drilldown rules control when happens when users interact with certain portions of an image viewlet. More information about Drilldown rules is forthcoming.

Icon rules

Icon rules allow icons, such as icons from the data, to be displayed in image viewlets. More information about Icon rules is forthcoming.

Class rules

Class rules are used to apply the CSS class styles that you set up on the Style tab. For example, you can apply a Class Rule to change the color of an element based on certain criteria. In the battery example, style classes determine the formatting of the battery image. The battery image class rules cause it to change color based on the percentage of battery power that remains.

The “fully-charged” class rule formats the battery image using the “fully-charged” style when the percentage is at least 50 percent:

The “partly-charged” class rule formats the battery image using the “partly-charged” style when the percentage is between 25 and 49, inclusive:

The “depleted” class rule formats the battery image using the “depleted” style when the percentage is at 24 percent or less:

For example, the following query shows a depleted battery image:

Get Dataset where Properties('BatteryID') = 'battery5' show as image('battery')

Text rules

When setting up a text element, such as a label, in the battery example, you have three options: Field value, Custom text, or a combination of the two.

• If you select Field value, the value from the selected field is displayed. In the first example below, the Percentage field value is used as a label to indicate the battery charge level.
• If you select Custom text, you can define any text to be shown. This can be static text, or dynamic, using rules. In the second example below, the descriptive label varies depending on the battery status ("GOOD," "OK," or "LOW").
• You can also combine static and dynamic text in one text element. 

In this section we will look at using these different options to add different labels to the battery to reflects its current charge level.

Example 1: Field Value as Text

In this example, we will apply a text rule so that the text label will reflect the actual percentage of the battery.  Since this will vary by battery, this rule uses a Field Value, pulling the value for the label from the actual data.

To add a rule for Field Value as Text:

1. In the SVG File Editor (lower-left panel), turn on the Select with Cursor toggle icon (see Select with Cursor Toggle).
2. Select the text element in the Main tab of the SVG editor to open the Selected Element Rules Editor (upper-right panel). You can either click and drag your cursor across the code or, for elements of a single line of code, double-click the line of code to select the element.
3. Select the Element Rules button at the top of the panel. You can now modify the Text rules of the text element by expanding the Text rules (as long as no other text elements use the same rule). 
4. A list of the fields in the dataset is provided. Select the field from the list that you want to use in your text. In this case, the Percentage field is selected:
   
5. (Optional.) To preview your changes, click Preview.
   
6. Continue to make changes until you have completed edits to the image template.
7. To save changes and close the editor, click Save in the lower-right corner of the window.

Example 2: Custom Text

In this example, we will apply a text rule so that the text label will change according to the same conditions that affect the color of the battery. When the battery percentage is in the range indicated by the green background, the label will read "GOOD." When it is in the range indicated by the yellow background, the label will read "OK."   When it is in the range indicated by the red background, the label will read "LOW." 

What is a Group?
A Group is one logical condition. It can contain one or more value statements. Groups can also contain other groups.

What is a Value?
A value is a data point that is being evaluated. By default, each data point that is being evaluated is a simple value based on the data type of the selected field (that is, for integer fields, the data point is a number; for string fields, it is text). But you can click the Show Hide Advanced Options icon  to make it a Variable or a Field instead.

Unless the value you are entering is a custom field, you can select from a list of the values that exist for that field within the dataset.

To add a rule for Custom Text:

1. In the SVG File Editor (lower-left panel), turn on the Select with Cursor toggle icon (see Select with Cursor Toggle).
2. Select the text element in the Main tab of the SVG editor to open the Selected Element Rules Editor (upper-right panel). You can either click and drag your cursor across the code or, for elements of a single line of code, double-click the line of code to select the element.
3. Select the Element Rules button at the top of the panel. You can now modify the Text rules of the text element by expanding the Text rules. If a Text rule is used by multiple text elements, you must edit it in the Rules tab of the SVG File Editor.
4. Click .
5. Add a name for the rule in the Rule name field.
6. Set Rule conditions. By default, you start with a single Group. You can add value statements to a group by selecting . The group of one or more value statements as a whole is evaluated according to the "operator" you choose for the group (All, Any, or Always true [Always apply]), as follows:
   • If you choose All, then the data must "pass" all the value statements in that group for the condition to be met.
   • If you choose Any, then the data must "pass" at least one of the value statements in that group for the condition to be met.
   • If you choose Always true (or "Always apply"), then the rule event is always applied. This option is useful when, for example, you want to use the same custom text for multiple elements. You can apply an Always true (or "Always apply") rule to each element so that you can set up the custom text in one place for all of them.
7. (Optional.) Click to add another condition (in the form of another Group, or set, of value statements).  
8. (Optional.) To preview your changes, click Preview.
   
9. Continue to make changes until you have completed edits to the image template.
10. To save changes and close the editor, click Save in the lower-right corner of the window.

Text Rule Scenarios

In the scenario below, the condition group that represents a battery percentage between 50 and 100, inclusive, is made up of two separate value statements, both ("All") of which must be met: a percentage ≤100 and a percentage ≥50.  

When the condition represented by this group is met, the Green rule will be applied and the text label "GOOD" will be displayed.

In the scenario below, the condition group of a battery percentage between 25 and 49, inclusive, is made up of two separate value statements: a percentage ≤49 and a percentage ≥25. 

When the condition represented by this group is met, the Yellow rule will be applied and the text label "OK" will be displayed.

In the scenario below, the condition of a battery percentage less than 25 only requires one value statement: a percentage ≤24.  

When the condition is met, the Red rule will be applied and the text label "LOW" will be displayed.

Example 3: Combining Values and Text

You can also combine custom text and variables. In this example, we will use text to add a percent sign to the percentage field from Example 1.

To include a field value within custom text, introduce the field name with an at (@) sign and wrap it in curly brackets: @{FieldName}.

In our example, the field name looks like this:

@{Percentage}%

 

If you wanted to put a "Percent" label in front of the percentage value, you would enter Percent: @{Percentage}

Fragment rules

More information about Fragment rules is forthcoming.

Image Preview (lower right)

The lower-right panel of the image viewlet editor shows a preview of the image.

Image Preview Panel Buttons:

• Click Close to close the image template editor and return to the user interface.
• Click Preview to preview changes you’ve made in the SVG File Editor to see their effects before saving.
• Saving your changes to the image template editor will close the editor. When you have completed all desired changes in the SVG File Editor, click Save to save changes to the image template editor.

Editing rules for a selected element

You can view the rules that have been applied to an element.

1. Select the specific element using one of the methods below:

• • Select the code for the element in the SVG File Editor.
  • Click the element in the Image Preview panel. (However, see the Important note in the Main Tab section for detailed information.)

2. The Selected Element Rules Editor shows the rules that have been applied to that element.
   By default, the Simplified tab shows all existing variables for the element and allows you to specify values for them.
   
3. To modify rules, select the Element Rules tab. On this tab, you can create new rules. You can also edit existing rules, as long as the rule is not also used by other elements. In that case, you must edit the rule on the  Rules tab (see Rules Tab).
   
4. (Optional.) To preview your changes, click Preview.
5. To save changes, click Save in the lower-right corner of the window.