Creating Dynamic Vector Images

Top Previous Next

AggreGate platform provides an elegant way to allow static SVG images became alive and interactive. You can add custom parameters to an image. When SVG image with custom parameters is loaded into a Vector Drawing component, parameters are shown as component properties in a special tab of the GUI Builder's Properties Editor. Modifying them can dynamically alter various drawing's aspects: color, lines thickness, rotation angle, tank levels, turn animation on/off etc.

Custom parameters is declared by special tags in SVG document. They define rules of changing SVG document elements when certain parameter gets a new value. The vector drawing is dynamically updated on every SVG document change.

XML namespace

All custom tags use a separate namespace: agg. So it must be declared in SVG document header to keep the document well formed:

XML tags

The structure of custom parameters declaration is the following:

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

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

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

agg:paramS

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

agg:PARAM

It has attributes that:

•	hold information about a component property,

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

When the tag is located in <agg:params> root node it is treated as a component property: both the component property information and the rule is used.

When the tag is located in <agg:state> node then only the rule data is used and no component property is created (see AGG:STATES).

Attributes used to define component property:

Attribute:	Type:	Description:
name	String	Component property name.
description	String	Component property description in properties editor.
type	String	Text code for property type. The following types are supported: I (Integer), F (Float), S (String), C (Color), state, level.
min	Float	Minimum limit for property value when used with number types or lower limit for parameter value when used with level type.
max	Float	Maximum limit for property value when used with number types or upper limit for parameter value when used with level type.

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 AGG:STATES).

Attributes that define SVG modification rules:

Attribute:	Type:	Description:
ids	String	Comma-separated SVG document elements identifiers list. Elements with given identifiers is affected by parameter changes.
classes	String	Comma-separated CSS classes list. Elements with given CSS classes is affected by parameter changes.
attributes	String	Comma-separated attributes list. Document element attributes that values are overwritten by a new value on parameter change.
cssAttributes	String	Comma-separated CSS attributes list. CSS attributes that values are overwritten by a new value on parameter change.
pattern	String	A string pattern containing "{0}". It is used to transform property value to a document string by replacing the {0} token with the value.
forceRepaint	Boolean	This flag controls SVG drawing repaint policy on parameter changes. When set to false the drawing repaints partially, based on changed regions detection (fast). When set to true the drawing repaints completely on each parameter change (slow). In certain cases the SVG drawing engine can't properly handle dynamic document changes (e.g. changing clipping masks) so the drawing must be repainted completely. Force repaint slows down SVG dynamic performance. The default value is false.
animation *	"play/stop"	Plays or stops animation for elements with given identifiers and classes.
value *	String	Sets the value for attribute with given identifiers and classes.

Animation and value attributes 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.

agg:state

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. State parameter is non scalar and displayed in 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:

Attribute:	Type:	Description:
name	String	State name.
description	String	State description in properties editor.

Examples

Style

You can control styling of SVG document elements by modifying their CSS attributes. To change the color for different drawing parts 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 GUI Builder it will have the Color component property. Every time the Color gets a new value the drawing engine will find all document elements where class is mainColor and set a new color value to their fill CSS attribute. This will change the drawing parts color.

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 Specificaton.

Rotation

Suppose that a SVG document have an element representing a knob with id knob. Applying a rotation transformation at point (61.542, 61.792) makes the knob to rotate. To create a parameter for rotation to a definite angle you can write the following:

<agg:params>

<agg:parameter 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 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.

Level

Let the fluid level in SVG image document of a reactor depends on 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. So, to control the level we must 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 Integer type having 0 to 100 limits. Attributes min="660" and max="66" define the range of y attribute. Every time a component property gets a new value it is proportionally translated from [0, 100] range to [600, 66] range 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 Level change. Because dynamic clip mask modifications are not supported and you might see unexpected results without repainting the whole image.

States

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. Now to control a flip switch state you must control groups visibility. The parameter for switching the state can be defined like this:

<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.

Animation

Suppose you have a fan drawing and it animated with:

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 gets the On value then the rotate animation is started. When the value is set to Off the rotate animation is stoped.

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