Developer Guide

The stated goal for Svidget.js is to cleanly separate visualization SVG from its host HTML page. This means that the page has a DOM, and a Svidget widget has its own DOM. Contrast this with the fact that most JavaScript visualization libraries manipulate the DOM directly. There are advantages and disadvantages in both approaches.

The primary advantage of a single DOM is perceived performance and ease of manipulation. However, due to JavaScript's single threaded nature any performance gains are minimal. Coming soon, there will be some sample pages to demonstrate Svidget's performance capabilities.

The design goals of the Svidget framework are:

Clean Separation. You can build and test your widgets as standalone SVG files before integrating them with a page.

Ease of Use. Consuming a widget on a web page only requires minimal HTML and JavaScript knowledge.

Encapsulation. Neatly encapsulting data visualization components making reuse clean and easy to use.

Isolation. JavaScript errors within the widget do not interfere with the page in most cases, and vice versa.

Customization. Working within an SVG file allows you make as specialized a visualization as you need.

• A real-time view into your IoT assets.
• A blog or content-oriented site that wants to quickly integrate a chart without the hassle of picking and coding against a charting library.
• A live dashboard or infographics page that contains multiple charts, graphs or other visual assets that is constantly refreshing its data.
• An interactive game, puzzle, or activity that reuses a lot of similar graphical components (like ABC blocks for example).

Here is a simple widget with a single text element. This illustrates the basic layout of a widget.

<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svidget="http://www.svidget.org/svidget"
 width="200" height="100" viewBox="0 0 200 100" style="background:transparent">
	<title>Hello World Example</title>
	<desc>The most basic example showing the features of params, actions, and widgets.</desc>

	<svidget:params>
		<svidget:param name="data" shortname="d" type="string" subtype="color" binding="#textLabel" />
		<svidget:param name="color" shortname="c" type="string" subtype="color" binding="#textLabel@fill" />
		<svidget:param name="size" shortname="s" type="number" binding="#textLabel@font-size" />
	</svidget:params>

	<svidget:actions>
		<svidget:action name="spin" external="true" binding="spinIt" description="Spins the star." />
	</svidget:actions>

	<svidget:events>
		<svidget:event name="spinComplete" description="Triggered when the spinning has completed." />
	</svidget:events>

	<g>
		<text id="textLabel" x="100" y="55" text-anchor="middle" font-size="24" fill="#3f3f3f" font-family="Arial" class="pulse"></text>
	</g>

	<script type="application/javascript" xlink:href="../scripts/svidget.js"></script>
	<script type="application/javascript">
		<![CDATA[
	
		// bound to spin action
		function spinIt() {
			// perform the spin
			// (some code that does that here)
			// invoke spinComplete event
			svidget.$.event("spinComplete").trigger();
		}
	
	  ]]>
	</script>

</svg>

The Svidget framework defines a series of types and subtypes that mostly correspond to JavaScript native types. These types and subtypes are referenced in params and actionparams. When using a widget, it is important (although not critical) to adhere to the types.

The object and array types can be represented as JSON when declaratively setting a param using a <param> tag inside of a <object> tag. Svidget has a bit more relaxed approach to parsing JSON syntax than you would see when using JSON.parse(). Specifically, Svidget allows the use of single quotes in JSON. This is so you can specify JSON in the value attribute without the need to escape double quotes.

<object id="myStar" role="svidget" data="widgets/donut.svg" type="image/svg+xml" width="200" height="200">
	<param name="data" value="[['banana', 7], ['apple', 6], ['cherry', 2], ['orange', 10], ['grape', 3.5]]" />
</object>

Svidget uses CSS selector syntax to bind a param to one or more elements or attributes within the SVG document. However, the W3C spec for CSS selectors does not currently provide support for selecting attributes directly. Because of this, Svidget as added an additional capability on top of the standardized selector syntax, the use of @attr to select the attribute.

Consider this example:

<svidget:param name="backgroundColor" type="string" subtype="color" binding="#rect1@fill" />
<rect id="rect1" width="100" height="100" fill="yellow" />

The backgroundColor param is bound to the fill attribute of the <rect id="rect1"> element. We normally couldn't select the fill attribute directly, but using Svidget's +Attributes syntax, we now can. Note that this syntax may change in the future if the W3C spec is updated to allow direct attribute selection.

1. Handle click and tap/touchstart/touchend separately. Since a user can't typically hover over an element on a touch-only device, using tap/touch to simulate this behavior is the best approach.

2. Use Chrome's built in emulator to emulate different mobile devices. The Chrome developer tool allows you to test your widget in different resolutions and orientations, and includes emulating tap/touch capabilities, so you can for example handle click and tap events separately.

The best way to add a widget to a page is to use the <object> tag.

<object id="hwWidget" role="svidget" data="widgets/helloworld.svg" type="image/svg+xml" width="200" height="100">
	<param name="data" value="Hello World" />
	<param name="color" value="#da3333" />
	<param name="size" value="20" />
</object>

You can also add a widget programatically using svidget.load().

svidget.load("#widgetContainer", { url: "widgets/helloworld.svg", id: "hwWidget" }, { 
	data: "Hello World", 
	color: "#da3333",
	size: 20
});

With our widget up and running, the next things to think about are how to interact with the widget. A widget is a living component, which means that its params can be set at any time.

Here is an example of setting the data param on our Hello World widget:

var hwWidget = svidget.widget("hwWidget");
var dataVal = hwWidget.param("data").value(); // gets the value
hwWidget.param("data").value("Goodbye World"); // sets the value

The next thing you can do is invoke actions on the widget. Our Hello World widget defines a spin action that doesn't take any params.

var hwWidget = svidget.widget("hwWidget");
hwWidget.action("spin").invoke();

The final thing you can do is listen for events on the widget. Our Hello World widget defines a spinComplete event.

var hwWidget = svidget.widget("hwWidget");
hwWidget.event("spinComplete").ontrigger(function (e) {
	document.getElementById("someDivTag").innerHTML = "Spin has completed.";
});

Note: For a live example of params, actions, and events in action, see the Spinning Star example.