Creating Dynamic Vector Images

The Iotellect platform provides an elegant way to allow static SVG images to become alive and interactive through the addition of a few custom parameters. When an SVG image with custom parameters is loaded into a Vector Drawing component, each parameter is available in a special tab of the Properties Editor of the GUI Builder. Such parameters can then be modified to dynamically alter the image's color, lines thickness, rotation angle, animation status, and anything else defined in the SVG document.

Custom parameters are declared by special tags in SVG document. They define rules for changing the SVG document elements when a given parameter is assigned a new value. The vector drawing is dynamically updated on every SVG document change.

All custom tags use a separate namespace: agg. This tag must be declared in the document header in order to create a well-formed SVG document:

<svg version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:agg="http://www.example.com" ... >

Custom parameter declarations are structured as follows:

• There must be a single <agg:params> root node holding all other declarations.

• The root <agg:params> element can hold multiple <agg:param> elements.

• Each <agg:param> element can hold multiple <agg:state> elements with <agg:param> elements.

This is a root container for all custom declarations. Only a single <agg:params> tag may be present in a document.

The <agg:param> attributes can:

• Hold information about a component property,

• Define rules for applying a property value to the SVG document elements.

When the tag is located in the <agg:params> root node, it is treated as a component property: both the component property information and the rule are used. When the tag is located in an <agg:state> node then only the rule data is used and no component property is created (see the agg:state section below).

Attributes used to define a component property:

Level type implies that component property is an Integer number limited by a [0..100] range. Every property value within this range is proportionally translated to [min..max] range when applying to a document. min and max numbers are defined by appropriate parameter attributes. Note, that min value can be greater then max value.

State type is for applying fixed modifications to a document (see section agg:state, below).

Attributes that define SVG modification rules:

Animation and value attributes are used only when <agg:param> defines a state. Value holds a constant string value that applies to document when an appropriate state of the component parameter is set. Animation begins/stops playing an animation with given id when the appropriate state is set.

States are used to apply some predefined modifications (states) to a document. For example it can be used to turn on/off a fan rotation. The state parameter is non scalar and displayed in the Properties Editor as a combo box with predefined options.

It is used to set multiple values to multiple DOM elements when the state is applied. The idea of defining a state is simple: create an <agg:param> with "state" type and enumerate states within it by <agg:state>. Each <agg:state> tag can have multiple <agg:param/> tags that define how the DOM should change when the state is applied.

It has parameters:

You can control the styling of SVG document elements by modifying their CSS attributes. To change the color for different parts of a drawing, the following parameter declaration can be used:

<agg:params> <agg:param name="color" description="Color" type="C" cssAttributes="fill" classes="mainColor"/> </agg:params>

When the drawing is loaded in the GUI Builder, it will have the Color component property. Every time the component property Color gets a new value, the drawing engine will find all document elements with class mainColor and set the new color value to their fill CSS attribute.

To make SVG more flexible, faster to download and easier to maintain, you can use CSS (Cascading Style Sheets) right in the same file. Read Styling with CSS section in W3C SVG Specification.

Suppose that an SVG document has an element representing a knob with the ID knob. Applying a rotation transformation at point (61.542, 61.792) forces the knob to rotate. To create a parameter for rotation to a certain angle, you can use the following parameter:

<agg:params> <agg:param name="angle" description="Angle" type="I" ids="knob" attributes="translation" pattern="rotate({0} 61.542 61.792)"/> </agg:params>

This declares a single SVG parameter Angle with Integer type that will be shown as a component property. If the parameter is set to 45 then the translation attribute of the knob DOM element will be set to rotate(45 61.542 61.792) and the knob will turn by 45 degrees.

Suppose the fluid level in an SVG image document of a reactor depends on the y attribute value of a <clipPath id="clipPathId"...> tag: when y is 66.9 the reactor is full, when y is 660 the reactor is empty. To control the leve,l we create a parameter with level type:

<agg:params> <agg:param name="level" description="Level" type="level" attributes="y" min="660" max="66" ids="clipPathId" forceRepaint="true"/> </agg:params>

This parameter creates a component property with an Integer type having 0 to 100 limits. Attributes min="660" and max="66" define the range of the y attribute. Every time a component property gets a new value, it is proportionally translated from the range [0, 100] to the range [600, 66] and the y attribute of the clipPathId element is set to this translated value. If the Level property of Vector Drawing is set to 0 then the y will be set to 660. If the Level property is set to 50 then the y will be set to 297. If the Level property is set to 100 then the y will be set to 66.

The forceRepaint flag is used to completely repaint the drawing on every change of Level, because dynamic clip mask modifications are not supported and you might see unexpected results without repainting the whole image.

To manage drawing states like "the box is opened" or "the switch is turned on", you can use a state parameter. To create a dynamic left-right flip switch, for example, you can create an SVG document with two groups of elements. One for the left switch state and another for the right state. To control the flip switch state you change the visibility of each group. The parameter for switching the state can be defined as follows:

<agg:params>
  <agg:param name="state" description="State" type="state">
    <agg:state name="left" description="Left">
      <agg:param attributes="visibility" ids="switch-left" value="visible"/>
      <agg:param attributes="visibility" ids="switch-right" value="hidden"/>
    </agg:state>
    <agg:state name="right" description="Right">
      <agg:param attributes="visibility" ids="switch-left" value="hidden"/>
      <agg:param attributes="visibility" ids="switch-right" value="visible"/>
    </agg:state>
  </agg:param>
</agg:params>

This defines a State component property with two values: Left and Right. When the State is set to Left then the visibility attribute of the switch-left DOM element gets visible value, and the visibility attribute of the switch-right DOM element gets "hidden" value. When the State is set to Right the switch-left becomes hidden and the switch-right becomes visible.

Suppose you have a fan drawing and it is animated with:

<animateTransform id="rotate" attributeName="transform" attributeType="XML" type="rotate" from="0 45 45" to="360 45 45" begin="indefinite" dur="10s" repeatCount="indefinite"/>

To control animation you can define the following state parameter:

<agg:params>
  <agg:param name="state" description="State" type="state">
    <agg:state name="on" description="On">
      <agg:param animation="play" ids="rotate"/>
    </agg:state>
    <agg:state name="off" description="Off">
      <agg:param animation="stop" ids="rotate"/>
    </agg:state>
  </agg:param>
</agg:params>

This defines a State component property with two values: On and Off. When it is set to the On value the rotate animation is started. When the value is set to Off the rotate animation is stopped.

You can see more examples of using custom SVG parameters in the Symbol Library.

Was this page helpful?

Tell us more

Send

Thank you!