Developer Guide Documentation

Documentation

This is a reference for the JavaScript library and the XML schema.

Working with widgets is relatively easy and straightforward. (more content)

Members marked with a version 0.x.y were introduced in that version. Members that are marked for Page are applicable at the page level, whereas members marked Widget are applicable inside of a widget. Some members can apply to both page and widget.

JavaScript Reference

Global Object (svidget) Page Widget

Provides access into the root of the Svidget library.

svidget.$ property 0.2.0 Widget
Shortcut to svidget.current().
svidget.connected() property Widget
Gets whether the widget is connected to the page. When false, the widget is considered to be in standalone mode.
Returns
true if connected, false otherwise.
svidget.current() property Widget
Gets an instance to the current widget.
Returns
The Svidget.Widget instance.
svidget.load() method Page
Dynamically loads a widget onto the page.
Usage
svidget.load(selector, url, paramObj, callback) svidget.load(selector, options, paramObj, callback)
Parameters
  • selector string - A CSS selector to the container element where the widget will be placed.
  • url string - The url for the widget.
  • options object - An object containing properties to initialize the widget.
  • paramObj object - The name of the handler. This can be used to unregister the handler by name.
  • callback function - A callback function to call once the widget is loaded.
Returns
The newly added Svidget.WidgetReference instance.
Example 
var myWidget1 = svidget.load("#container", "widgets/graph.svg", { 
			data: [1, 2, 3], 
			color: "#da3333",
			backColor: "#ffac33"
		}, 
		function (widget) {
			// do something
		}
);

var myWidget2 = svidget.load("#container", { 
			url: "widgets/graph.svg", 
			connected: false,
			crossdomain: false,
		}, { 
			data: [4, 5, 6], 
			color: "#3333da",
			backColor: "#33ffac"
		}, 
		function (widget) {
				// do something
		}
);
svidget.off() method Page Widget
Unregisters an event handler.
Usage
svidget.off(type, handler) svidget.off(type, name)
Parameters
  • type string - The event type. See svidget Events for the list of types.
  • handler function - The handler function that was used to register the function.
  • name string - The handler name that was used to register the function.
Returns
true if the unregistering succeeds, false otherwise (in case handler or name was not found).
svidget.offload() method Page Widget
Unregisters an event handler for the load event.
Usage
svidget.offload(handler) svidget.offload(name)
Parameters
  • handler function - The handler function that was used to register the function.
  • name string - The handler name that was used to register the function.
Returns
true if the registering succeeds, false otherwise (in case handler or name was not found).
svidget.offwidgetload() method Page Widget
Unregisters an event handler for the widgetload event.
Usage
svidget.offwidgetload(type, handler) svidget.offwidgetload(type, name)
Parameters
  • handler function - The handler function that was used to register the function.
  • name string - The handler name that was used to register the function.
Returns
true if the unregistering succeeds, false otherwise (in case handler or name was not found).
svidget.on() method Page Widget
Registers an event handler for a specified event type.
Usage
svidget.on(type, data, name, handler) svidget.on(type, data, handler) svidget.on(type, handler)
Parameters
  • type string - The event type. See svidget Events for the list of types.
  • data object - An arbitrary value to pass to the Event object when the event is triggered.
  • name string - The name of the handler. This can be used to unregister the handler by name.
  • handler function - The handler function that is invoked when the event is triggered.
Returns
true if the registering succeeds, false otherwise (in case handler or name was already registered).
Example 
var added = svidget.on("load" { message: "hiya!" }, "myHandler", function (e) {
	console.log(e.data.message); // "hiya"
});
svidget.onload() method Page Widget
Registers an event handler for the load event. On a page, this event is fired once the params are passes to the widget and the widget acknowledges. In a widget, this event is fired once the DOM is loaded and the params are applied from the query string.
Usage
svidget.onload(data, name, handler) svidget.onload(data, handler) svidget.onload(handler)
Parameters
  • data object - An arbitrary value to pass to the Event object when the event is triggered
  • name string - The name of the handler. This can be used to unregister the handler by name.
  • handler function - The handler function that is invoked when the event is triggered.
Returns
true if the registering succeeds, false otherwise (in case handler or name was already registered).
Example 
var added = svidget.onload({ message: "hiya!" }, "myHandler", function (e) {
	console.log(e.data.message); // "hiya"
});
svidget.onwidgetload() method Page
Registers an event handler for the widgetload event. This event is fired once the params are passed to the widget.
Usage
svidget.onwidgetload(data, name, handler) svidget.onwidgetload(data, handler) svidget.onwidgetload(handler)
Parameters
  • data object - An arbitrary value to pass to the Event object when the event is triggered
  • name string - The name of the handler. This can be used to unregister the handler by name.
  • handler function - The handler function that is invoked when the event is triggered.
Returns
true if the registering succeeds, false otherwise (in case handler or name was already registered).
Example 
var added = svidget.onwidgetload({ message: "ok" }, "myHandler", function (e) {
	console.log(e.value); // e.value == the widget ID
});
svidget.widget() property Page
Gets an instance to the widget reference specified by selector. The selector is either numeric index in the collection, or widget ID.
Usage
svidget.widget(id) svidget.widget(index)
Parameters
  • id string - An arbitrary value to pass to the Event object when the event is triggered
  • index number - The name of the handler. This can be used to unregister the handler by name.
Returns
The Svidget.WidgetReference instance, or null if not found.
Example 
var myWidget1 = svidget.widget("myWidget");					
var myWidget2 = svidget.widget(2);
svidget.widgets() property Page
Gets an collection of widget references declared on the page.
Usage
svidget.widgets()
Returns
The Svidget.ObjectCollection instance containing the collection of widget references.
svidget Events Page Widget
Gets an collection of widget references declared on the page.
  • load Page - Triggers when all widgets are loaded.
  • load Widget - Triggers when the widget is ready.
  • widgetload Page - Triggers when any widget is loaded.

Svidget.Action class Widget

Represents an invocable action on the widget. This object corresponds to a <svidget:action> element in the widget.

addParam() method
Adds the action param to the action.
Usage
action.addParam(actionParam) action.addParam(name, options)
Parameters
  • actionParam string - The action param to add.
  • name string - The action param name to add.
  • options string - The action param options to use when creating the action param.
Returns
The newly added Svidget.ActionParam instance.
binding() property function
Gets or sets the binding for the action. This can be a global function name, or a function.
Usage
action.binding() action.binding(globalFuncName) action.binding(func)
Returns
The binding function as a function or global function name as a string, or whether the set was successful when setting.
Example 
var action = svidget.$.action("invokeMe");
alert(action.binding()); // can be string or function, depending on which was set
action.binding(invokeMeFunc);

function invokeMeFunc(actionParam1) {
	// do something
}
bindingFunc() property function
Gets the binding function for the action binding. This is the function resolved from the binding() property.
Usage
action.bindingFunc()
Returns
The binding function.
Example 
var action = svidget.$.action("invokeMe");
action.binding("invokeMeFunc");
var func = action.bindingFunc();

function invokeMeFunc(actionParam1) {
	// do something
}
description() property string
Gets or sets the action description.
Usage
action.description() action.description(desc)
Returns
The description when getting, or whether the set was successful when setting.
Example 
var action = svidget.$.action("invokeMe");
document.getElementById("mydesc").innerHTML = action.description();
action.description("Updated description");
enabled() property bool
Gets or sets whether the action is enabled.
Usage
action.enabled() action.enabled(isEnabled)
Returns
The enabled value when getting, or whether the set was successful when setting.
Example 
var action = svidget.$.action("invokeMe");					
if (!action.enabled()) action.enabled(true);
external() property bool
Gets or sets whether the action is external and can be invoked from the page.
Usage
action.external() action.external(isExternal)
Returns
The external value when getting, or whether the set was successful when setting.
Example 
var action = svidget.$.action("invokeMe");					
if (!action.external()) action.external(true);
invoke() method
Invokes the action and returns the result if any. The function that is invoked is set from the binding() property. The arguments for the action are defined in the params() collection.
Usage
action.invoke(arg1, arg2, ...)
Returns
true if the invoke succeeds, false otherwise (in case binding not set).
Example 
var action = svidget.$.action("getArea");
// register handler for invoke
action.oninvoke(function (e) {
	alert(e.returnValue); //28.2743
});
// invoke
action.invoke(3);

function areaOfCircle(radius) {
	return Math.pow(3, 2) * Math.PI;
}
name() property string
Gets the action name. Must be unique among actions in the widget. Read only.
Usage
action.name()
off() method
Unregisters an event handler.
Usage
action.off(type, handler) action.off(type, name)
Parameters
  • type string - The event type. See Svidget.Action Events for the list of types.
  • handler function - The handler function that was used to register the function.
  • name string - The handler name that was used to register the function.
Returns
true if the unregistering succeeds, false otherwise (in case handler or name was not found).
offchange() method
Unregisters an event handler for the change event.
Usage
action.offchange(handler) action.offchange(name)
Parameters
  • handler function - The handler function that was used to register the function.
  • name string - The handler name that was used to register the function.
Returns
true if the registering succeeds, false otherwise (in case handler or name was already registered).
offinvoke() method
Unregisters an event handler for the invoke event.
Usage
action.offinvoke(handler) action.offinvoke(name)
Parameters
  • handler function - The handler function that was used to register the function.
  • name string - The handler name that was used to register the function.
Returns
true if the registering succeeds, false otherwise (in case handler or name was already registered).
offparamadd() method
Unregisters an event handler for the paramadd event.
Usage
action.offparamadd(handler) action.offparamadd(name)
Parameters
  • handler function - The handler function that was used to register the function.
  • name string - The handler name that was used to register the function.
Returns
true if the registering succeeds, false otherwise (in case handler or name was already registered).
offparamchange() method
Unregisters an event handler for the paramchange event.
Usage
action.offparamchange(handler) action.offparamchange(name)
Parameters
  • handler function - The handler function that was used to register the function.
  • name string - The handler name that was used to register the function.
Returns
true if the registering succeeds, false otherwise (in case handler or name was already registered).
offparamremove() method
Unregisters an event handler for the paramremove event.
Usage
action.offparamremove(handler) action.offparamremove(name)
Parameters
  • handler function - The handler function that was used to register the function.
  • name string - The handler name that was used to register the function.
Returns
true if the registering succeeds, false otherwise (in case handler or name was already registered).
on() method
Registers an event handler for a specified event type.
Usage
action.on(type, data, name, handler) action.on(type, data, handler) action.on(type, handler)
Parameters
  • type string - The event type. See Svidget.Action Events for the list of types.
  • data object - An arbitrary value to pass to the Event object when the event is triggered.
  • name string - The name of the handler. This can be used to unregister the handler by name.
  • handler function - The handler function that is invoked when the event is triggered.
Returns
true if the registering succeeds, false otherwise (in case handler or name was already registered).
Example 
var added = action.on("invoke", { message: "hiya!" }, "myHandler", function (e) {
	console.log(e.data.message); // "hiya"
});
onchange() method
Registers an event handler for the change event.
Usage
action.onchange(data, name, handler) action.onchange(data, handler) action.onchange(handler)
Parameters
  • data object - An arbitrary value to pass to the Event object when the event is triggered
  • name string - The name of the handler. This can be used to unregister the handler by name.
  • handler function - The handler function that is invoked when the event is triggered.
Returns
true if the registering succeeds, false otherwise (in case handler or name was already registered).
Example 
var added = action.onchange({ message: "ok" }, "myHandler1", function (e) {
	console.log(e.data.message); // "ok"
});
oninvoke() method
Registers an event handler for the invoke event.
Usage
action.oninvoke(data, name, handler) action.oninvoke(data, handler) action.oninvoke(handler)
Parameters
  • data object - An arbitrary value to pass to the Event object when the event is triggered
  • name string - The name of the handler. This can be used to unregister the handler by name.
  • handler function - The handler function that is invoked when the event is triggered.
Returns
true if the registering succeeds, false otherwise (in case handler or name was already registered).
Example 
var added = action.oninvoke(function (e) {
	console.log(e.returnValue); // value returned from invoke
});
onparamadd() method
Registers an event handler for the paramadd event.
Usage
action.onparamadd(data, name, handler) action.onparamadd(data, handler) action.onparamadd(handler)
Parameters
  • data object - An arbitrary value to pass to the Event object when the event is triggered
  • name string - The name of the handler. This can be used to unregister the handler by name.
  • handler function - The handler function that is invoked when the event is triggered.
Returns
true if the registering succeeds, false otherwise (in case handler or name was already registered).
Example 
var added = action.onparamadd(function (e) {
	console.log(e.value.name()); // value == action param that was added
});
onparamchange() method
Registers an event handler for the paramchange event.
Usage
action.onparamchange(data, name, handler) action.onparamchange(data, handler) action.onparamchange(handler)
Parameters
  • data object - An arbitrary value to pass to the Event object when the event is triggered
  • name string - The name of the handler. This can be used to unregister the handler by name.
  • handler function - The handler function that is invoked when the event is triggered.
Returns
true if the registering succeeds, false otherwise (in case handler or name was already registered).
Example 
var added = action.onparamchange(function (e) {
	console.log(e.property); // property that was changed
});
onparamremove() method
Registers an event handler for the paramremove event.
Usage
action.onparamremove(data, name, handler) action.onparamremove(data, handler) action.onparamremove(handler)
Parameters
  • data object - An arbitrary value to pass to the Event object when the event is triggered
  • name string - The name of the handler. This can be used to unregister the handler by name.
  • handler function - The handler function that is invoked when the event is triggered.
Returns
true if the registering succeeds, false otherwise (in case handler or name was already registered).
Example 
var added = action.onparamremove(function (e) {
	console.log(e.value); // name of action param that was removed
});
param() property Svidget.ObjectCollection
Gets the action param by either its name or its index.
Usage
action.param(name) action.param(index)
Parameters
  • name string - The name of the param.
  • index number - The index of the param.
Returns
The Svidget.ActionParam instance, or null if not found.
Example 
var myParam1 = action.param("myWidget");					
var myParam1 = action.param(2);
params() property Svidget.ObjectCollection
Gets the action params.
Usage
action.params()
removeParam() method
Removes the action param from the action.
Usage
action.removeParam(name)
Parameters
  • name string - The action param name to remove.
Returns
true if the removal succeeds, false otherwise (in case param not found).
Svidget.Action Events
  • change - Triggers when one the action properties has changed.
  • invoke - Triggers when the action is invoked.
  • paramadd - Triggers when an action param is added to the action.
  • paramchange - Triggers when any of the action params have changed.
  • paramremove - Triggers when an action param is removed from the action.

Svidget.ActionProxy class Page

Represents a proxy to a Svidget.Action instance contained within the widget. The members are proxies to members of the underlying object, so the same documentation applies.

Svidget.ActionParam class Widget

Represents an param for an action. This object corresponds to a <svidget:actionparam> element in the widget, contained within an action. Note that action params are used primarily for discovery. A consumer of your widget may find it useful what params the action expects.

defvalue() property
Gets the default value for the action param. This is used if a value is not supplied at the ordinal position of this action param.
Usage
actionparam.defvalue()
Returns
The default value for the action param.
Example 
var param = svidget.$.param("color");
var defvalue = param.defvalue();
var curvalue = param.value();
alert("Has it changed? = " + defvalue !== curvalue);
description() property string
Gets or sets the action param description.
Usage
actionparam.description() actionparam.description(desc)
Returns
The description when getting, or whether the set was successful when setting.
Example 
var param = svidget.$.action("myAction").param(0);
document.getElementById("mydesc").innerHTML = param.description();
param.description("New description for action param 0.");
name() property string
Gets the action param name. Must be unique among action params for the action. Read only.
Usage
actionparam.name()
off() method
Unregisters an event handler on the action param.
Usage
actionparam.off(type, handler) actionparam.off(type, name)
Parameters
  • type string - The event type. See Svidget.Param Events for the list of types.
  • handler function - The handler function that was used to register the function.
  • name string - The handler name that was used to register the function.
Returns
true if the unregistering succeeds, false otherwise (in case handler or name was not found).
offchange() method
Unregisters an event handler for the change event.
Usage
actionparam.offchange(handler) actionparam.offchange(name)
Parameters
  • handler function - The handler function that was used to register the function.
  • name string - The handler name that was used to register the function.
Returns
true if the registering succeeds, false otherwise (in case handler or name was already registered).
on() method
Registers an event handler for a specified event type for the action param.
Usage
actionparam.on(type, data, name, handler) actionparam.on(type, data, handler) actionparam.on(type, handler)
Parameters
  • type string - The event type. See Svidget.Param Events for the list of types.
  • data object - An arbitrary value to pass to the Event object when the event is triggered.
  • name string - The name of the handler. This can be used to unregister the handler by name.
  • handler function - The handler function that is invoked when the event is triggered.
Returns
true if the registering succeeds, false otherwise (in case handler or name was already registered).
Example 
actionparam.on("change", { message: "something changed!" }, "myHandler", function (e) {
	console.log(e.data.message); // "something changed!"
});
onchange() method
Registers an event handler for the change event.
Usage
actionparam.onchange(data, name, handler) actionparam.onchange(data, handler) actionparam.onchange(handler)
Parameters
  • data object - An arbitrary value to pass to the Event object when the event is triggered
  • name string - The name of the handler. This can be used to unregister the handler by name.
  • handler function - The handler function that is invoked when the event is triggered.
Returns
true if the registering succeeds, false otherwise (in case handler or name was already registered).
Example 
var added = actionparam.onchange({ message: "ok" }, "myHandler1", function (e) {
	console.log(e.data.message); // "ok"
});
subtype() property string
Gets or sets the subtype. The subtype is used in conjuction with type to further describe how the value is intended to be used. Valid subtypes are: color, integer, regex and choice.
Usage
actionparam.subtype() actionparam.subtype(val)
Returns
The subtype when getting, or whether the set was successful when setting. Setting will fail if not a valid subtype.
Example 
var param = svidget.$.action("myAction").addParam("backgroundColor", "transparent", { type: "string" });
var isOk = param.subtype("color");
console.log(isOk); // true
isOk = param.subtype("somethingElse");
console.log(isOk); // false
type() property string
Gets or sets the type. The type corresponds to a primitive JavaScript type. Valid types are: string, number, bool, object, or array.
Usage
actionparam.type() actionparam.type(val)
Returns
The type when getting, or whether the set was successful when setting. Setting will fail if not a valid type.
Example 
var param = svidget.$.action("myAction").addParam("backgroundColor", "transparent", { type: "string" });
console.log(param.type()); // "string"
var isOk = param.type("object");
console.log(isOk); // true
isOk = param.type("myMadeUpType");
console.log(isOk); // false
Svidget.ActionParam Events
  • change - Triggers when one the action param properties has changed.

Svidget.ActionParamProxy class Page

Represents a proxy to a Svidget.ActionParam instance contained within a widget action. The members are proxies to members of the underlying object, so the same documentation applies.

Svidget.Collection class Page Widget

Represents a collection of items. Extends JavaScript Array.

Svidget.Event class Page Widget

An event object that is passed to the handler when any event is triggered. Note: This object is patterned closely with jQuery's Event object implementation.

currentTarget property object
Gets the current object (widget, param, action, etc) that currently triggered the event, either the original or current bubble target.
Usage
event.currentTarget
Example 
svidget.$.param("myParam").onchange(handleParamChange);
svidget.$.onparamchange(handleWidgetParamChange);

function handleParamChange(e) {
	console.log(e.currentTarget.toString()); // [Svidget.Param]
}
function handleWidgetParamChange(e) {
	console.log(e.currentTarget.toString()); // [Svidget.Widget]
}
data property object
Gets the data that was passed in when the event handler was registered for the event.
Usage
event.data
Example 
svidget.$.param("myParam").onchange(handleParamChange, { my: "data" });

function handleParamChange(e) {
	console.log(e.data.my); // data
}
isImmediatePropagationStopped() method bool
Gets whether the event will continue to propagate to the next handler for the current event or next object in the chain. For example, a param change event will propagate to a widget paramchange event.
Note: if this is true, then isPropagationStopped() will also return true.
Usage
event.isImmediatePropagationStopped()
Returns
True if immediate propagation is stopped due to a stopImmediatePropagation() call, false otherwise.
isPropagationStopped() method bool
Gets whether the event will continue to propagate to the next object in the chain. For example, a param change event will propagate to a widget paramchange event.
Usage
event.isPropagationStopped()
Returns
True if propagation is stopped due to a stopPropagation() call, false otherwise.
name property string
Gets the name of the handler that was passed in when the event handler was registered for the event.
Usage
event.name
Example 
svidget.$.param("myParam").onchange(handleParamChange, 3, "handler1");

function handleParamChange(e) {
	console.log(e.data); // 3
	console.log(e.name); // handler1
}
stopImmediatePropagation() method void
Stops immediate propagation of the event. This prevents the remaning handlers for the current event, as well as handlers in parents, from executing.
Usage
event.stopImmediatePropagation()
Example 
svidget.$.param("myParam").onchange(handleParamChange);
svidget.$.param("myParam").onchange(handleParamChange2);
svidget.$.onparamchange(handleWidgetParamChange);

function handleParamChange(e) {
	console.log("handleParamChange");
	e.stopImmediatePropagation();
}

// this is never called because immediate propagation was stopped
function handleParamChange2(e) {
	console.log("handleParamChange2");
}

// this is never called because immediate propagation and propagation were stopped
function handleWidgetParamChange(e) {
	console.log("handleWidgetParamChange");
}
stopPropagation() method void
Stops propagation of the event. For example, a param change event will no longer propagate to a widget paramchange event.
Usage
event.stopPropagation()
Example 
svidget.$.param("myParam").onchange(handleParamChange);
svidget.$.onparamchange(handleWidgetParamChange);

function handleParamChange(e) {
	console.log("handleParamChange");
	e.stopPropagation();
}

// this is never called because propagation was stopped
function handleWidgetParamChange(e) {
	console.log("handleWidgetParamChange");
}
target property string
Gets the original target object (widget, param, action, etc) that triggered the event.
Usage
event.target
Example 
svidget.$.param("myParam").onchange(handleParamChange);
svidget.$.onparamchange(handleWidgetParamChange);

function handleParamChange(e) {
	console.log(e.target.toString()); // [Svidget.Param]
}
function handleWidgetParamChange(e) {
	console.log(e.target.toString()); // [Svidget.Param]
}
timeStamp property string
Gets the date/time numeric timeStamp of the event.
Usage
event.timeStamp
Example 
svidget.$.param("myParam").onchange(handleParamChange);

function handleParamChange(e) {
	var timeDiff = +(new Date()) - e.timeStamp;
	console.log("Millisecs elapsed since event was triggered = " + timeDiff);
}
type property string
Gets the event type, i.e. "invoke", "change", "actioninvoke", "eventtrigger", that the event is for.
Usage
event.type
Example 
svidget.$.param("myParam").onchange(handleParamChange);

function handleParamChange(e) {
	console.log(e.type); // change
}
value property string
Gets the value for the event. This is supplemental data passed when the event is triggered.
Usage
event.value
Example 
svidget.$.param("myParam").onchange(handleParamChange);

function handleParamChange(e) {
	var changeObj = e.value; // change events always have this object layout: { property: "propName", value: val }
	console.log(changeObj.property); // enabled
	console.log(changeObj.value); // true (note: this is the new value)
}

Svidget.EventDesc class Widget

Represents an event for the widget. This object corresponds to a <svidget:event> element in the widget.

Svidget.EventDescProxy class Page

Represents a proxy to a Svidget.EventDesc instance contained within the widget. The members are proxies to members of the underlying object, so the same documentation applies.

Svidget.ObjectCollection class Page Widget

Represents a collection of object types used by the widget. Extends Svidget.Collection.

Svidget.Param class Widget

Represents a param for a widget. This object corresponds to a <svidget:param> element in the widget.

binding() property string
Gets or sets the binding for the param. This is a CSS Selector + Attributes syntax string that maps to one or more elements or attributes in the document.
Usage
param.binding() param.binding(bindingStr)
Returns
The binding string, or whether the set was successful when setting.
Example 
var param = svidget.$.param("backColor");
param.binding("rect@stroke"); // map param to the stroke attribute of every rect element in the document
coerce() property bool
Gets or sets whether the value should be coerced to the type specified by the type property. This is especially useful for object and array types as they are sometimes initialized as strings.
Usage
param.coerce() param.coerce(val)
Returns
The coerce value when getting, or whether the set was successful when setting.
Example 
var param = svidget.$.param("data");
param.type("object");
param.coerce(true);
param.value("{ firstName: 'Joe', lastName: 'Pesci' }");
console.log(param.value()); // [object Object]
// ok, no more coersion
param.coerce(false);
param.value("{ firstName: 'Joe', lastName: 'Pesci' }");
console.log(param.value()); // "{ firstName: 'Joe', lastName: 'Pesci' }"
defvalue() property
Gets the default value for the param. This is used if a value is not supplied when the widget is initially loaded. Can only be set declaratively through the <svidget:param> element.
Usage
param.defvalue()
Returns
The default value for the param.
Example 
var param = svidget.$.param("color");
var defvalue = param.defvalue();
var curvalue = param.value();
alert("Has it changed? = " + defvalue !== curvalue);
description() property string
Gets or sets the param description.
Usage
param.description() param.description(desc)
Returns
The description when getting, or whether the set was successful when setting.
Example 
var param = svidget.$.param("data");
document.getElementById("mydesc").innerHTML = param.description();
param.description("Updated description");
enabled() property bool
Gets or sets whether the param is enabled. When not enabled, its value cannot be set.
Usage
param.enabled() param.enabled(isEnabled)
Returns
The enabled value when getting, or whether the set was successful when setting.
Example 
var param = svidget.$.param("invokeMe");					
if (!v.enabled()) param.enabled(true);
name() property string
Gets the param name. Must be unique among params in the widget. Read only.
Usage
param.name()
off() method
Unregisters an event handler on the param.
Usage
param.off(type, handler) param.off(type, name)
Parameters
  • type string - The event type. See Svidget.Param Events for the list of types.
  • handler function - The handler function that was used to register the function.
  • name string - The handler name that was used to register the function.
Returns
true if the unregistering succeeds, false otherwise (in case handler or name was not found).
offchange() method
Unregisters an event handler for the change event.
Usage
param.offchange(handler) param.offchange(name)
Parameters
  • handler function - The handler function that was used to register the function.
  • name string - The handler name that was used to register the function.
Returns
true if the registering succeeds, false otherwise (in case handler or name was already registered).
offset() method
Unregisters an event handler for the set event.
Usage
param.offset(handler) param.offset(name)
Parameters
  • handler function - The handler function that was used to register the function.
  • name string - The handler name that was used to register the function.
Returns
true if the registering succeeds, false otherwise (in case handler or name was already registered).
on() method
Registers an event handler for a specified event type for the param.
Usage
param.on(type, data, name, handler) param.on(type, data, handler) param.on(type, handler)
Parameters
  • type string - The event type. See Svidget.Param Events for the list of types.
  • data object - An arbitrary value to pass to the Event object when the event is triggered.
  • name string - The name of the handler. This can be used to unregister the handler by name.
  • handler function - The handler function that is invoked when the event is triggered.
Returns
true if the registering succeeds, false otherwise (in case handler or name was already registered).
Example 
param.on("set", { message: "something changed!" }, "myHandler", function (e) {
	console.log(e.data.message); // "something changed!"
});
onchange() method
Registers an event handler for the change event.
Usage
param.onchange(data, name, handler) param.onchange(data, handler) param.onchange(handler)
Parameters
  • data object - An arbitrary value to pass to the Event object when the event is triggered
  • name string - The name of the handler. This can be used to unregister the handler by name.
  • handler function - The handler function that is invoked when the event is triggered.
Returns
true if the registering succeeds, false otherwise (in case handler or name was already registered).
Example 
var added = param.onchange({ message: "ok" }, "myHandler1", function (e) {
	console.log(e.data.message); // "ok"
});
onset() method
Registers an event handler for the set event.
Usage
param.onset(data, name, handler) param.onset(data, handler) param.onset(handler)
Parameters
  • data object - An arbitrary value to pass to the Event object when the event is triggered
  • name string - The name of the handler. This can be used to unregister the handler by name.
  • handler function - The handler function that is invoked when the event is triggered.
Returns
true if the registering succeeds, false otherwise (in case handler or name was already registered).
Example 
var added = param.onset(function (e) {
	console.log(e.value); // new value for param
});
sanitizer() property function
Gets or sets the function to use to sanitize the value when it is being set. This can be a global function name, or a function. The function signature is (param, val) where param is the current Svidget.Param instance and val is the value being set. The sanitizer function should return the updated value. If the sanitizer function returns undefined then the original passed in value is used.
Note: When coerce is true the value is coerced prior to being sanitized.
Usage
param.sanitizer() param.sanitizer(globalFuncName) param.sanitizer(func)
Returns
The sanitizer function as a function or global function name as a string, or whether the set was successful when setting.
Example 
var colorParam = svidget.$.param("color");
colorParam.sanitizer(function (param, val) {
	if (!/^#(?:[0-9a-fA-F]{3}){1,2}$/.test(val)) return "#000";
	return val;
});
colorParam.value("NotReallyAColor");
console.log(colorParam.value()); // "#000"
shortname() property string
Gets or sets the param short name. This is a shorter version of the official param name, used primarily for getting values from the query string, when the widget is loaded in standalone mode.
Usage
param.shortname() param.shortname(sn)
Returns
The shortname when getting, or whether the set was successful when setting.
Example 
var param = svidget.$.param("data");
document.getElementById("mysn").innerHTML = param.shortname();
param.shortname("d2");
subtype() property string
Gets or sets the subtype. The subtype is used in conjuction with type to further describe how the value is intended to be used. Valid subtypes are: color, integer, regex and choice.
Usage
param.subtype() param.subtype(val)
Returns
The subtype when getting, or whether the set was successful when setting. Setting will fail if not a valid subtype.
Example 
var param = svidget.$.addParam("backgroundColor", "transparent", { type: "string" });
var isOk = param.subtype("color");
console.log(isOk); // true
isOk = param.subtype("somethingElse");
console.log(isOk); // false
type() property string
Gets or sets the type. The type corresponds to a primitive JavaScript type. Valid types are: string, number, bool, object, or array.
Note: Changing the type will NOT coerce the value when coerce is true. Work around this by setting the value to its current value.
Usage
param.type() param.type(val)
Returns
The type when getting, or whether the set was successful when setting. Setting will fail if not a valid type.
Example 
var param = svidget.$.addParam("backgroundColor", "transparent", { type: "string" });
console.log(param.type()); // "string"
var isOk = param.type("object");
console.log(isOk); // true
isOk = param.type("myMadeUpType");
console.log(isOk); // false
typedata() property string
Gets or sets the typedata for the param. This is used in conjuction with type and subtype to provide further supplemental value for the type. Currently, this is commonly used for the string/choice type/subtype scenario, in which case the typedate is a pipe delimited string of choice values.
Usage
param.typedata() param.typedata(td)
Returns
The typedata value when getting, or whether the set was successful when setting.
Example 
var amParam = svidget.$.addParam("fruit", "none", { type: "string", subtype: "choice" });					
amParam.value("banana");
console.log(amParam.value()); // "none", because it's the only choice in the list
amParam.typedata("banana|pear|grape|watermelon|mango");
amParam.value("banana");
console.log(amParam.value()); // "banana"
value() property any
Gets or sets the value for the param. When coerce is true, the value is converted to the type/subtype. When a sanitizer function is set, it is called to check the value. Setting this value triggers the "set" event for the param.
Usage
param.value() param.value(val)
Returns
The value when getting, or whether the set was successful when setting. Set will fail if param is not enabled.
Example 
var ratioParam = svidget.$.addParam("ratio", 0, { type: "number" });					
ratioParam.value(0.5);
console.log(ratioParam.value()); // 0.5
Svidget.Param Events
  • change - Triggers when one the param properties has changed.
  • set - Triggers when the param value has changed.

Svidget.ParamProxy class Page

Represents a proxy to a Svidget.Param instance contained within the widget. The members are proxies to members of the underlying object, so the same documentation applies.

Svidget.Proxy class Page

Provides base class functionality for all Proxy classes in the framework.

Svidget.Widget class Widget

Represents the widget object.

Svidget.WidgetReference class Page

Represents a reference to a widget from a page.

Xml Reference

<svg> Widget

Describes custom Svidget attributes for the <svg> root element.

Attributes
  • xmlns:svidget string - The svidget namespace. Required. Must be set to http://www.svidget.org/svidget.
  • svidget:version string - The version of svidget.js that the widget is targeted. This is mostly for informational purposes.
Example 
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" 
	xmlns:svidget="http://www.svidget.org/svidget"
	svidget:version="0.2.0"
	width="200" height="200"
>

<svidget:actions> Widget

Contains <svidget:action> elements.

Attributes
  • onadd string - The name of the global function handling the addaction event when adding actions to the widget.
  • onremove string - The name of the global function handling the removeaction event when removing actions from the widget.
Example 
<svidget:actions>
	<svidget:action name="spin" external="true" binding="spin" description="Spins the star." />
	<svidget:action name="stopSpin" external="true" binding="stopSpin" description="Stops any currently running spin animation." />
</svidget:actions>

<svidget:action> Widget

Defines an Svidget.Action for the widget.

Attributes
  • name string - The action name. Required, and must be unique among all actions.
  • binding string - The global function name to invoke when the action is invoked.
  • description string - The action param name to add.
  • external bool - Whether the action is external.
  • onchange string - The name of the global function handling the change event.
  • oninvoke string - The name of the global function handling the invoke event.
  • onparamadd string - The name of the global function handling the paramadd event.
  • onparamchange string - The name of the global function handling the paramchange event.
  • onparamremove string - The name of the global function handling the paramremove event.
Example 
<svidget:action 
	name="spin" external="true" binding="spin" description="Spins the star."
	onchange="spinChange" oninvoke="spinInvoke" 
	onparamchange="spinParamChange" onparamadd="spinParamAdd" onparamremove="spinParamRemove" 
/>

<svidget:actionparams> Widget

Contains <svidget:actionparam> elements.

<svidget:actionparam> Widget

Defines an Svidget.ActionParam contained within an Svidget.Action for the widget.

<svidget:events> Widget

Contains <svidget:event> elements.

<svidget:event> Widget

Defines an Svidget.EventDesc for the widget.

<svidget:params> Widget

Contains <svidget:param> elements.

<svidget:param> Widget

Defines an Svidget.Param for the widget.

<object> Page

Loads a widget onto an HTML page.

Attributes
  • role string - Overrides the ARIA attribute to tell the framework that this object tag is specifically a Svidget.js widget. Required. Must be set to svidget.
  • data-connected bool - Whether the widget is connected to the page. When false, the widget is is standalone mode, and no communication between the page and the widget will take place after the widget is initialized. Default is true.
  • data-crossdomain bool - A hint that indicates that the widget is hosted on another domain. Set this to true if you know that your widget is hosted on another domain to speed up loading, or if you prefer your widget to be hosted in an <iframe>. Default is false.
Example 
<object id="someWidget" role="svidget" data="widgets/donut.svg" data-connected="true" data-crossdomain="false"
	type="image/svg+xml" width="200" height="200">
	<param name="data" value="0.55" />
	<param name="color" value="#da3333" />
	<param name="backColor" value="#ffac33" />
	<param name="textColor" value="#da3333" />
</object>
Fork me on GitHub