back to developer home

Audience

This material is intended to help software developers and highly-technical non-developers understand how create custom touchatag applications using Specification Documents.

Before reading this, you must be familiar with the concepts of the ACS Block System.

Overview

Specification documents let you devise new touchatag Applications using the ACS Block System.

Every touchatag Application available in the touchatag application portfolio has a corresponding XML document called a Specification. Each Specification document defines the logical procedure for an application, as well as the parameters the Application must use. Whenever an end user configures (or reconfigures) an Application through the touchatag dashboard, the changes are posted to the touchatag Application Correlation Service (ACS) in an updated Specification document.

For example, touchatag's Web Link Application requires a URL parameter from the end user. The Application’s procedure results in an action that causes the end user’s computer to open that web link (URL). When you configure a Web Link Application in the touchatag dashboard, the dashboard sends a complete Specification document to the ACS. (You can see an example of that Specification here.)

You can create your own Specifications to define touchatag Applications that use the Block System in completely new and innovative ways.

Each Specification is an XML document that you submit to the touchatag Application Correlation Service (ACS) either via the Specification Tool (used mainly for testing Specifications), or via the Configurator API (which allows you to create user-friendly configuration interfaces that make your Applications sharable through the touchatag dashboard).

This page explains the details and implementation for creating Specification documents. We start by briefly introducing some identifiers that are used in Specification document. Then we introduce the structure of the Specification document. Finally, we spend the bulk of the discussion on writing the Blueprint section of the Specification.

Specification Technical Details

Structural Overview

This video presents an overview of how Specification documents are structured.

Specification Structural Overview (on Vimeo).

Note As an overview, this video does not cover some of the possible possible structural variations for constructing specifications.

Specification Structure

As discussed in the ACS Block System Overview, a Specification document defines an Application. The document has two major sections.

• application defines a list of commands
• blueprint defines a superblock that uses the standard Application Block runtime interface

These two sections can also be readily identified in the overall structure of the Specification document:

Note the following XML elements:

• XML preamble : A typical optional XML preamble indicating the type of XML and its encoding. Please note that although this preamble is not required, we do require a UTF-8 encoding.
• specification : The root element of a specification. Please note that the schema supports blueprint as a top level element as well, but this is currently not yet supported.
• xmlns="http://www.touchatag.com/schema/configurator/specification-1.0" : The namespace to use for all elements within specification.
• application: The application element covers the definition of commands.
• blueprint: The blueprint element covers the definition of superblocks. In this case it must be used to define a Superblock that adheres to the Application contract.

Application Section

The application section of the specification covers the definition of commands. It follows the following structure:

An application can define multiple commands and MUST at least define 1 command. If there is only a single command, it is commonly called default, but you are free to choose this identifier. The name attribute is used in the tag association screen and allows a more meaningfull message for the user.

Blueprint Section

The blueprint section of the specification covers the definition of superblocks. It makes up the bulk of a specification. Please note that the blueprint element is a general construct to define superblocks. Today however we only support the definition of a single superblock that adheres to the Application interface. In the remainder of the discussion the term application will be used to mean a superblock that adheres to the Application interface, unless specified otherwise.

There are basically two ways to define an application using a blueprint. Either you reference an existing library application and just configure that one or you define your own application that is build up of library blocks and superblocks. Since these two cases are sufficiently distinct, we cover them in separate sections.

Identifiers

Before diving deeper into the two main sections of the Specification Document, we need to define some of the Identifiers used within them.

The Specification uses three types of Identifier to identify the functional components within it. Each type of identifier—Block, Pin Endpoint, and Property—has its own rules.

Block Identifiers

A Block Identifier is used to identify a block from the ACS Block System. This can be any type of block (Block, Superblock or Application). The general notation is as follows:

namespace:identifier#shorthand

• namespace: Optional namespace which has the format urn:part1:...:partN. This can be used to scope your identifier.
• identifier: The actual identifier for the block (within the specified namespace)
• shorthand: An optional shorthand for the block identified by namespace:identifier

There is a special character, *, that can take the place of the namespace:identifier to indicate that the identifier may be autogenerated because it is not important. It will depend on context whether or not this autogenerated id is allowed. Also note that it is allowed to write #shorthand which will actually imply the *, so the normalized form of #shorthand is actually *#shorthand.

There is also a specially reserved namespace urn:touchatag:block, which is used to identify the touchatag block library. All references to touchatag blocks require this namespace.

Pin Endpoint Identifiers

When creating a Wiring it is required to refer to pins. This is done using Pin Endpoint identifiers. The general notation is as follows:

blockid:pinname

• blockid : Optional Block Identifier (any form)
• pinname : The name of the pin

When defining pin endpoints for wires, you are always required to identify the block via a blockid, since we have to uniquely identify the pin within all the constituents of an aggregate. For shunts, one of the endpoints represents a pin on the aggregate, in this case the endpoint on the aggregate should NOT mention a blockid, but only the pinname.

Property Identifiers

Properties of blocks typically represent configurable parameters. These properties are identified by a name. This name can only contain a limited set of characters, which can be described by the following regular expression:

[a-zA-Z][a-ZA-Z0-9]*

It means that only basic latin characters are supported and numbers, but that the name should never start with a number. (And that is should at least entail a single character). Or to be even more precise we will only support US-ASCII characters 0x30 ->0x39; 0x41 -> 0x5A; 0x61 -> 0x7A.

Application Use

Application use represents the case where you reference a library application and configure it using properties. It will look something like this:

• superblock : There should only be a single superblock element within blueprint. This will be the container for our application.
• id="*" : It is mandatory to have an id on superblock (mainly for future extension), but on the top level superblock it is not used yet. It is recommended to use the autogeneration placeholder *. This id is a Block Identifier.
• ref="urn:touchatag:block:some-app": The ref attribute is critical for the application use scenario. This ref references a library application called some-app. The full list of available library applications can be found in the Block Reference.
• property : Property elements directly below the superblock element represent properties on the enclosing superblock. Using properties the enclosing superblock can be configured.
• property name="someProperty" : The name attribute on property refers to the name of the property to set. Please note that it is not allowed to have multiple property elements with the same name. The name attribute represents a Property Identifier.
• uri / text : The content of a property element is an element identifying a property type and its associated value. An overview of all supported property types can be found in the Block Reference.

The XML Schema will allow you to add additional interface, breakdown and wiringScheme elements. If you provide them, they will be ignored if you have referenced a library application. There is no concept of inheritance or overriding, so you either re-use in this fashion or you define your own application entirely, which is covered in the next section.

Application Definition

When you don't reference a library application, you can define your own and leverage all the features of the Block System. Applications you define yourself will not be added to the library and thus will not be available for you or others to reference as described in Application Use. An application definition will look like this:

• superblock id="*" : The superblock element without a ref indicates we want to define a new application instead of configuring an existing one. As stated earlier, although id is mandatory, it is unused and thus * is recommended, although you could give it a more descriptive id.
• breakdown : The breakdown element marks the "bill of material" of the application. It will contain the list of blocks that will be used in the application. Please note that it is possible to have multiple instances of the same block, but they will require unique ids.
• block id="ro" ref="urn:touchatag:block:text-source" : The block element represents a block declaration, which features a ref attribute to reference a block (any type) from our library. The id is in this case mandatory and meaningful, since the id will be used to uniquely identify the block within the superblock.
• property : A block can be configured as well using properties. It works exactly the same as properties on the superblock.
• wiringscheme : The wiringscheme element marks the composition of the actual application. It will contain a mix of wire and shunt elements that will make up the wiring of the application.
• wire from="ro:value-out" to="m:message-in" : The wire element represents a wiring between consituents and requires that the from and the to represent Pin Endpoint identifiers with blockid. You can only connect wires between pins of the same type and opposite direction.
• shunt from="m:action-out" to="action-out" : The shunt element represents a wiring between an aggregate pin and a constituent pin. The aggregate pin should not feature a blockid and the consituent pin should. You can only connect shunts between pins of the same type and same direction.

Since we are defining an application, the interface of the aggregate is fixed. This means that you can only shunt with one of the following 5 pins:

An application should at least shunt with the action-out pin, since this represents the feedback to the invoking client. The input pins do not have to be shunted. They can be ignored if the application does not rely on any of its dynamic information. It does mean that you application should be self-activating in some way, typically by feeding in configuration via registers (which have self-activated output pins).

The XML Schema also supports an interface element within the superblock element and superblock elements within the breakdown element. These elements are not yet supported but are already specified as a provision for future evolutions in which we may allow you to define superblocks within your application to offer a decomposition means for complicated applications.

When you are writing a Configurator Applet, you will typically submit the same specification over and over again, only variable in some small respects. In order to make it easier to seperate the static from the dynamic part of your specification, we also support the exposure of properties at the application level. We will now revisit the above example to illustrate this capability.

• property name="message" : Now we have a top level message property on our application. Whatever we configure here will be propagated to the Value property on the ts block. This was done via...
• delegate as="message" : This special property value delegate defines a property on the enclosing aggregate with the name specified by the as attribute.

Examples

Application

These Application examples are ordered from least to most sophisticated.

1. Web Link Application
2. System Tray Notification Application
3. Bidirectional Web Link Wheel Application
4. Twitter Application

Practical Use

These Application examples are ordered from least to most sophisticated.

1. Constructed TextToText Map

Troubleshooting

Currently, the feedback that you get by submitting a Specification through the Specification Tool may sometimes not be enough to help you troubleshoot your Specification document. Here are a few techniques that may help you.

• Schema not valid: Try using a schema validation tool to find out what's wrong. The touchatag schema definition is here. If you don't have such a tool, DecisionSoft provides a free, online XML Schema Validator.

Deeper Details

The XML Schema for the touchatag Specification document (http://www.touchatag.com/schema/configurator/specification-1.0.xsd) is designed for re-usability and extensibility. This should aid in getting useful code generated by all kinds of XML binding frameworks, if you care to use them.