Create an Elementi widget

Introduction

A widget is typically a single SVG file that was built for a certain purpose (for instance to display a clock, to display an RSS feed, to send a command to the screen, etc.) and which offers different parameters / properties that the user can change from the interface, thus allowing for further customization of the widget functionality without having to modify the code behind.

You can create a widgets for Elementi through the usage of special customization tags within the code. These customization tags are XML elements (part of the spx namespace) with a special meaning within Elementi, in the sense that they are transformed into "widget properties" that the user can modify from the Edit panel in order to change the widget functionality.

These tags can describe:

which target object (JSON string or XML element) or attribute can be modified from the UI,
what type of content is expected,
how to present the content of each element or attribute to the user,
how to group together certain options for better usability.

When an SVG document is opened, Elementi scans through the direct children of the top level <svg> element for these special tags and transforms them into editable "properties" within the Edit panel.

Using the spx namespace

The tags detailed below are defined within the spx namespace (http://www.spinetix.com/namespace/1.0/spx), therefore this namespace need to be specified when using them. Usually, the namespace is added under the top-level svg element (and the tags are prefixed with "spx:"); alternatively, you can specify the namespace directly on the element.

For instance, the properties tag can be added into the SVG code as spx:properties (the spx namespace being defined at the svg element level) or as properties (the spx namespace being defined on the element).

<svg xmlns="http://www.w3.org/2000/svg" xmlns:spx="http://www.spinetix.com/namespace/1.0/spx" ... >
  <spx:properties> 
    <spx:customization_tag />
    ...
  </spx:properties>

<svg xmlns="http://www.w3.org/2000/svg" ... >
  <properties xmlns="http://www.spinetix.com/namespace/1.0/spx">
     <customization_tag />
     ...
  </properties>

Note:

For better clarity of the code, the former variant is preferred within this documentation.

`properties` tag

If the spx:properties (or properties) tag is encountered under the top level <svg> element, then Elementi displays the "Properties" view within the UI and adds properties to this view according to the customization tags found underneath the properties tag.

Additional attributes:

xml:id - usually set to "properties" .
translate = yes|no - where "yes" means that the names found within should be translated, if those strings are available within the translation file.

For example, this code makes the content of the "dur" attribute of the video element customizable, with a default value of 10s:

<svg xmlns="http://www.w3.org/2000/svg" xmlns:spx="http://www.spinetix.com/namespace/1.0/spx"
 xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 1280 720">
  <spx:properties xml:id="properties">
    <spx:text name="Video duration" xlink:href="#movie" attributeName="dur" />
  </spx:properties>
  <video xml:id="movie" dur="10s" xlink:href="clip.mp4" width="1280" height="720" />
</svg>

Customization tags for JSON objects

A JSON object can be specified inside an SVG document by using the CDATA section within an XML element, that is usually not part of the rendering tree (like title or defs). The link between the customization tag and this XML element is done by the xlink:href attribute (detailed below).

JSON customization tags

Below are listed the tags that can be used to define properties for a JSON object. Each tag must have at least name and xlink:href attributes; some tags might have other/optional attributes as well.

<spx:json-string name="str" xlink:href="#id" />

Defines a string property.

<spx:json-number name="str" min="num1" max="num2" xlink:href="#id" />

Defines a numerical property.

The optional attributes min and max can be used to limit the input values between the specified numeric values.

<spx:json-integer name="str"  min="int1" max="int2" xlink:href="#id" />

Defines an integer number property.

The optional attributes min and max can be used to limit the input values between the specified integer values.

<spx:json-boolean name="str" true="str1" false="str2" xlink:href="#id" />

Defines a boolean property.

The optional attributes true and false can be set to custom texts (like Yes/No) used to overwrite the default boolean values displayed to the user when the option is selected or not.

<spx:json-color name="str" xlink:href="#id" />

Defines a color property.

<spx:json-duration name="str" xlink:href="#id" />

Defines a duration property, which can be a number or a string (e.g., 5s).

<spx:json-choice name="str" entry="no" default="val" 
  choice="fonts|locales|timezones" 
  choice-1="val1" choice-2="val2" ...  name-1="str1" name-2="str2" ... 
  xlink:href="#id" />

Defines a list of values to be chosen by the user from a drop-down box.

Optional attributes:

default → specify the value selected by default.
entry → set it to "no" to prevent entering text, thus allowing only the pre-selected choices to be used.
choice → can be used to list all the available fonts, locales, or time zones (useful for clock widgets).
choice-1, choice-2 ... → used to add entries in the drop-down list. Must be present, except "choice" attribute is used instead .
name-1, name-2 ... → used to add entries names, defaults to the value of "choice-XX" if missing.

<spx:json-text name="str" default="str" fontSize="ignore" xlink:href="#id" />

Defines a jSignage text layer object.

Optional attributes:

default → can be used to specify a default text content
fontSize → can be set to "ignore" to prevent using the font size attribute, which is useful when the font size is computed automatically

<spx:json-layer name="str" positionable="yes" xlink:href="#id" />

Defines a jSignage layer object.

The optional attribute positionable can be used to specify that the object geometry can be adjusted from the interface.

<spx:json-data name="str" type="uri|variable|inline|documentURI" social="yes" xlink:href="#id" />

Defines a data source object (used for data-driven widgets).

The type attribute specifies the data source type as one of the following: "uri", "variable", "inline", or "documentURI".

Common attributes

The following attributes can be used with the JSON customization tags detailed above:

name (required)
Defines the string that appears in the left column on the "Properties" view.

xlink:href (required)
Defines the XML element referenced by the customization tag. The accepted format is "#id", where "id" is equal to the value of the id (or xml:id) attribute of the target XML element (e.g., xlink:href="#jsonLayers").

desc
Defines the string that appears when hovering the value field of the property.

index
If the JSON object contained by the target XML element refers to an array of JSON objects, this attribute defines which of them is targeted by the customization tag, for instance index="0" refers to the first object from the array.

propertyName
Defines the property that is customized by the tag from the properties of the target object. In case the property is part of an inner object, use the standard JavaScript notation for objects to reference it (e.g., defaultTransition.args.dur, data.0, etc.).

ui
When present and set to "enabled", this attribute indicates that the property is in fact a Fusion option. In this case, the property will appear in both Properties and Fusion tabs. See this page for more details.

Examples

Let's say we have the following JSON object:

<defs>
  <title xml:id="jsonParams"><![CDATA[
  [
    {
        "defaultSlideDur": "5s",
        "defaultTransition": {
                "args": {
                        "direction": "leftToRight",
                        "dur": 1
                },
                "ctor": "slide"
        },
        "looping": true,
        "shuffle": false
    },
    { 
       "data": [ "text 1", "text 2" ],
       "width": 500
    }
  ]
 ]]></title>
</defs>

The following properties can be defined for it:

<spx:properties>
  <spx:json-string name="Default Slide Duration" index="0" propertyName="defaultSlideDur" xlink:href="#jsonParams" />
  <spx:json-string name="Transition Duration" index="0" propertyName="defaultTransition.args.dur" xlink:href="#jsonParams" />
  <spx:json-boolean name="Looping" index="0" propertyName="looping" false="No" true="Yes" xlink:href="#jsonParams" />
  <spx:json-string name="Data 1" index="1" propertyName="data.0" xlink:href="#jsonParams" />
  <spx:json-number name="Width" index="1" propertyName="width" min="0" max="1000" xlink:href="#jsonParams"/>
</spx:properties>

You can also retrieve and use these properties within the jSignage code:

$(function(){
    var jsonParams = $.parseJSON( $('#jsonParams').text() );
    if ( jsonParams[0].looping ) {
        // do something with the data
        var data0 = jsonParams[1].data[0],
            width = jsonParams[1].width;
    }
});

Customization tags for XML objects

The following tags are (still) supported, however the Elementi built-in widgets are mostly using JSON properties objects instead.

For element customization

<spx:text>
Allows the user to modify the text content of the target element.
Shortcut: "Enable content edit".
<spx:rich>
Allows editing of formatted text using <tspan> and <tbreak> elements with text formatting properties.
Shortcut: "Enable content edit" on a <text> or <textArea> elements.
<spx:transform>
Allows the user to move and resize elements in the Preview panel. Can be used with most graphical elements: <image>, <rect>, … and <g>. It modifies the transform attribute. Shortcut: "Enable position change".
<spx:media>
Allows the user to change the media file using drag and drop. It should be used with the following media elements: <image>, <video>, <audio> and <animation>. It can also be used with <textArea> to enable effects. Shortcut: "Enable media edit".
Additional attributes:
- positionable = yes|no : 'yes' means that the media can be positioned using the Preview panel.
- textarea = yes|no : 'no' means that the media cannot be a text area.

For attribute customization

<spx:text>
Allows the user to directly enter the content of an attribute. It can be used with any attribute.
<spx:color>
Allows the user to change the color of an attribute using the Color Selection dialog. It should be used with color-related attributes (fill, stroke, color etc.).
<spx:choice>
Defines a list of values to be chosen by to user from a drop-down box.
Additional attributes:
- "choice-XX" (e.g., "choice-[01..99]"): corresponds to an entry in the drop-down list.

Common attributes

The customization tags detailed above share some common attributes:

name (required)
The name that appears in the left column on the "Properties" view.
xlink:href (required)
Defines the xml element referenced by the customization tag. The accepted format is "#id", where "id" is equal to the value of the id (or xml:id) attribute of the target xml element (e.g., xlink:href="#layers").
targetAttribute
Identifies the name of the attribute whose content is to be customized. If not present, the customization applies to the element.
targetNamespace
If targetAttribute is present, this further specifies a namespace for the target attribute.
ui
If set to "enabled", this indicates a customization attribute targeting specifically Fusion. It will appear in the "Fusion" tab, and not in the "Properties" tab.

Other customization tags

`group` tag

<spx:group>

It is used to group together certain properties under "Properties" view for better usability, by adding an indentation level. It must contain customization tags as children. It takes two attributes:

name (required) - defines the string that appears in the left column on the "Properties" view.
expand = yes|no - where "yes" means that the group is expanded by default.

<spx:group expand="yes" name="Headers">
   <spx:json-boolean false="no" name="Show header" propertyName="showHeader" true="yes" xlink:href="#jsonParams"/>
   <spx:json-string maxChars="30" name="Text" propertyName="headerText" xlink:href="#jsonParams"/>
</spx:group>

help tag

<spx:help>

It is used to add a "Help" tab. It can either contain glib markup (a subset of HTML with <b>, <i>, <a> and limited <span> support) or it can be empty and contain a xlink:href attribute to get a standard "Online help is available for this widget" text with a provided link set onto the first two words.

<spx:help xlink:href="http://support.spinetix.com/wiki/Calendar_widgets"/>

Tabular views

The json-array and table tags are used to create new views (i.e. the specified properties are not displayed under the "Properties" view) within Elementi UI.

table tag

If an <spx:table> tag is found under <spx:properties>, it will create a new table tab in the "Properties" view, for edition of an XML table. An XML table is composed of rows and columns. The name and format of columns is specified by the tags below the <spx:table> element, using the same customization tags as above.

The <spx:table> element has the following attributes:

name (required)
Name of the table, used as the tab label in the properties panel.
defaultPage
If set to 'yes' the properties panel with use the table tab as its default tab.
xlink:href (required)
Points to the table XML element, the one whose children are the table rows.
itemElement
Name of the XML element that will contain one row of data. Default: 'item'.
itemElementNamespace
If itemElement is present, further specifies the namespace of the row element.

By default this the rows are in the same namespace as the table.
ui
If set to 'enabled' the table shall be editable with Fusion.

Columns specification

To define the columns of the table created with <spx:table>, use the following customization tags: <spx:text>, <spx:choice>, <spx:color>, <spx:media>, <spx:rich>.

These may have the following attributes:
- name (required) = Column header
- elementName (required) = Name of the element created to contain the column, as a child of the corresponding row element.
- elementNamespace = If element is present, this further specifies the namespace for the column element. By default the column element is in the same namespace as the row element.
- showDefault = If set to 'no', the column will not be initially visible. The user will have to manually enable it with a right click on the table header before it can be edited.
- minWidth = Minimum width in pixel for the column space in the UI. Default: 250 pixels for media, otherwise 100 pixels.
Only one column can be of type <spx:media> (e.g. only one media per row).
The customization tags are the same as in the previous section, with the exception of <spx:transform> and <spx:group> which are forbidden.

Example

Here is a simple user editable table with three columns. The table is already populated with two rows.

<svg xmlns="http://www.w3.org/2000/svg" xmlns:spx="http://www.spinetix.com/namespace/1.0/spx"
 xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 1280 720">
  <spx:properties>
    <spx:table name="Inventory" xlink:href="#inventory" itemElement="row">
      <spx:text name="Item" elementName="item" />
      <spx:text name="Quantity" elementName="qty" />
      <spx:text name="Price" elementName="price" />
    </spx:table>
  </spx:properties>
  <defs>
    <defs xml:id="inventory">
      <row>
        <item>Carrot cake</item>
        <qty>20</qty>
        <price>$8.99</price>
      </row>
      <row>
        <item>Pumpkin pie</item>
        <qty>10</qty>
        <price>$15.99</price>
      </row>
    </defs>
  </defs>
  ...
</svg>

json-array tag

If a <spx:json-array> element is encountered under spx:properties, it acts similarly to <spx:table>, except that the table is described using JSON. The table contains objects whose properties are specified exactly as above.

For example, one could rewrite the inventory examples like this:

<svg xmlns="http://www.w3.org/2000/svg" xmlns:spx="http://www.spinetix.com/namespace/1.0/spx"
 xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 1280 720">
  <spx:properties>
    <spx:json-array name="Inventory" xlink:href="#inventory">
      <spx:json-string name="Item" propertyName="item" />
      <spx:json-integer name="Quantity" propertyName="qty" min="0" />
      <spx:json-number name="Price" propertyName="price" min="0" />
    </spx:json-array>
  </spx:properties>
  <defs>
    <defs id="inventory"><![CDATA[
      [
        { "item": "Carrot cake", "qty": 20, "price": 8.99 },
        { "item": "Pumpkin pie", "qty": 10, "price": 15.99 }
      ]
    ]]></defs>
  </defs>
  <script>
    var table = $.parseJSON( $('#inventory').text() );
  </script>
</svg>

As a special case, the table may have a single column, with no propertyName to define an array of this type of elements rather than an array of objects.

Create an Elementi widget

From SpinetiX Support Wiki

Contents

Introduction

Using the spx namespace

`properties` tag

Customization tags for JSON objects

JSON customization tags

Common attributes

Examples

Customization tags for XML objects

For element customization

For attribute customization

Common attributes

Other customization tags

`group` tag

help tag

Tabular views

table tag

Columns specification

Example

json-array tag

See also

Create an Elementi widget

From SpinetiX Support Wiki

Contents

Introduction

Using the spx namespace

properties tag

Customization tags for JSON objects

JSON customization tags

Common attributes

Examples

Customization tags for XML objects

For element customization

For attribute customization

Common attributes

Other customization tags

group tag

help tag

Tabular views

table tag

Columns specification

Example

json-array tag

See also

`properties` tag

`group` tag