HMD Template Authoring

From SpinetiX Support Wiki

Jump to: navigation, search

Introduction

HMD includes a templating mechanism which allows SVG documents and custom scripts authors to make their documents customizable using the UI.

When an SVG document is opened, HMD will scan through the first level of the XML tree, i.e. direct children of the top level <svg> element for templating instruction in the form of specially recognized XML elements in the spx (http://www.spinetix.com/namespace/1.0/spx) namespace.

These elements describe :

  • which target XML elements and attributes in the document may be modified from the UI,
  • what type of content each element or attribute expects,
  • how to present the content of each element or attribute to the user,
  • how to group together certain options for better usability.

Property sheets for XML content

If an <spx:properties> element is encountered, a property sheet for customization at the XML level will be displayed in the properties panel. Each element under <spx:properties> defines a line in the property sheet.

For example, this 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>
    <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>

Common attributes

Each customization tag must have some common attributes:

  • name (required)
    The name that will appear in the left colum of the property sheet
  • xlink:href (required)
    Identifies the target element, whose content or attributes is to be customized
    Must be of the form '#id' where id is the id of an element of the document.
  • targetAttribute
    Identifies the name of the attribute whose content is to be customized.
    If not present the customization applies to the element.
  • targetNamespace
    In case targetAttribute is present, further specifies a namespace for the target attribute.
  • ui
    If set to 'enabled' this indicates a customization attribute targetting specifically Fusion. It will appear in the Fusion property sheet rather than the main property sheet.

List of customization tags

For attribute customization

  • <spx:text> (shortcut: "Make content editable")
    • Allows the user to directly enter the content of an attribute
    • Can be used with any attribute
  • <spx:color> (shortcut: "Make color editable")
    • Allows the user to change the color of an attribute using the Color Selection dialog
    • Should be used with color-related attributes (fill, stroke, colour, etc)
  • <spx:choice> (shortcut: "Make choice editable")
    • Allows the user to choose between preset values for an attribute
      • Each “choice-XX” attribute corresponds to an entry in the drop-down list
      • Change the value of “choice-01” to add a preset value
      • Add a new attribute (ALT+A) and rename it sequentially (“choice-[03..99]”) to add more preset values.

For element customization

  • <spx:text> (shortcut: "Make content editable")
    • Allows the user to modify the text content of the target element
  • <spx:rich> (shortcut: "Make content editable" on a <text> or <textArea>)
    • Allows editing of formatted text using <tspan> and <tbreak> elements with text formatting properties.
    • Should be used only with <text> and <textArea>
  • <spx:transform> (shortcut: "Make positionable")
    • Allows the user to move and resize elements in the preview panel.
    • Can be used with most graphical elements: <image>, <rect>, … and <g>
    • Will modify the transform attribute
  • <spx:media> (shortcut: "Make media editable")
    • Allows the user to change the media file using drag and drop
      Includes using multi-media effects
    • Should be used with multi-media elements
      <image>, <video>, <audio> and <animation>
    • Can be used with <textArea> to enable effects
    • Additional attribute:
      positionable = yes|no : 'yes' means that the media is positionable using the preview panel
      textarea = yes|no : 'no' means that he media may not be a text area

For grouping of options

  • <spx:group>
    • Adds an indentation level in the property sheet.
    • Must contain customization tags as children
    • Additional attributes:
      expand = yes|no : 'Yes' means that the group is expanded by default.

XML table

If an <spx:table> tag is found under <spx:properties>, it will create a new table tab in the properties panel, 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.

XML table element

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
    • element (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 columms. 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>
    <table 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>
    </table>
  </defs>
  ...
</svg>
Retrieved from "https://support.spinetix.com/w/index.php?title=HMD_Template_Authoring&oldid=6010"
This page was last modified on 23 April 2013, at 17:16.