Block System Overview

By learning how the ACS Block System works, you can use the Block System to new types of touchatag Applications.

After learning the fundamentals of the Block System, you define new applications using a Specification document.

Overview

All touchatag Applications are powered by a modular execution engine called the Block System, which is a component of the touchatag Application Correlation Service (ACS).

Each time a tag is touched to a reader or a QR Code is scanned, the Application Correlation Service (ACS) correlates the tag to an Application. As soon as the Application is identified, the ACS dispatches a job to the ACS Block System.

The Block System is so named because it provides a set of re-usable building blocks that you can assemble into the complete logic of a touchatag Application. Each block provides different functionality for the Application, such as sending instructions to the touchatag client, or calling an external web service.

You assemble blocks into a touchatag Application by creating an XML document called a Specification. Before creating your first Specification, there are some important concepts to understand about the Block System. These include Blocks, Superblocks, Applications, and Wiring.

Once familiar with these concepts, you can proceed to learn how to compose a technical Specification for an application that implements one or more Blocks, as documented in the Specification docs.

Finally, for those who enjoy knowing things just a little deeper, you will find a short appendix of Deeper Technical Information.

Blocks

Blocks are the most basic units of logic in the Block System. They represent the most fundamental features available within the ACS.

Every Block has one or more Pins, which provide the block with runtime interfaces for input and output. When you link various Blocks together, you do so by connecting output pins to input pins in a Wiring Scheme.

Many Blocks also have Properties. Properties function as configuration interfaces, allowing you to assign configuration values that are needed within a touchatag application. The value set for a property can be obtained from a given block through an output Pin.

Each Block available in the ACS Block System also has a urn, which is a unique identifier comprised of the block's namespace and the block's name. (All blocks in the ACS Block System's library share the reserved namespace urn:touchatag:block, plus the block's unique name.)

To put these concepts into context, let's look at a couple block examples from the Block Reference documentation.

Example 1: The text-source Block

The text-source block provides a simple first example. You can use the text-source block to provide a string of text to another block.

In the image at right, notice in the summary that the text-source block has one property, named Value, and one output pin, named out.

It has no input pins, because the text-source block's whole purpose is to provide the text in its Value property to other blocks through its output pin.

In order to understand how this block might be used in conjunction with other blocks, let us consider a second example.

Example 2: The message Block

The message block sends a system tray notification message to the end user's computer.

In the image at right, notice that the message block has one input pin, one output pin, and no properties. It has no properties because, like many blocks in the ACS Block System library, it was designed to be simple and functional.

The input pin, named in, can be wired to accept text data.

The output pin (out) is an action for the ACS to perform, which in this case is to send a message from the input pin text to the end user's system.

As you can see, the message block requires a text input in order to perform its action. In the previous example, the text-source block has a text output. The text-source block can provide what the message block needs by wiring the text-source block's out to the message block's in.

Note You can jump ahead and see how this would look in a Specification in the Message Specification example.

Superblocks

A Superblock encapsulates other smaller blocks (and even other superblocks) to create a single, functional unit that can be used just like any other block.

As with a block, a superblock may have input and/or output pins, as well as properties. Although you use a superblock just as you use a block, the benefit of the Superblock is that it abstracts the assembly of blocks it contains, making it a single construct to use and re-use instead of re-assembling its constituent blocks each time you need them.

On its inside, a Superblock has three sections:

1. Properties, which may be used by any of the blocks within the Superblock
2. Breakdown, which lists the blocks used in the Superblock, assigning each a unique name (id).
3. Wiring Scheme, which identifies how each of the Superblock's internal blocks connect together at runtime.

Let's consider another example, this time using the XML notation for a Superblock.

Example 3: Message Superblock

In the previous two examples, we saw two blocks that would work well together as a simple, yet functional, touchatag Application. The following XML is excerpted from the Specification document example for a system tray Message. In it, identify the three sections of the Superblock, and consider how they relate to one another.

...
<superblock id="urn:example:sample:message-app">
            <property name="Message"><text>Ta-dah!! Your tag has been read!</text></property>        
            <breakdown>
                <block id="ts" ref="urn:touchatag:block:text-source">
                    <property name="Value"><delegate as="Message"/></property>
                </block>
                <block id="m" ref="urn:touchatag:block:message"/>     
            </breakdown>
            <wiringscheme>
                <wire from="ts:out" to="m:in"/>
                <shunt from="m:out" to="action-out"/>
            </wiringscheme>
        </superblock>
...

Let's briefly analyze this Superblock's three sections.

1. You can see that the Superblock has one property, named Message.
2. You can see that the Breakdown identifies two blocks. The block having the id of ts is a text-source block. The other block, id of m, is a message block.
   • The assigned id values give a unique name for each instance of a given block. So if your Superblock needed to use an additional TextSource block, you can add another and assign it its own unique id.
   • Notice that the TextSource block's Value property is not assigned directly, but is delegated from the value of the Superblock's Message property. When constructing more complex Superblocks, where many blocks may need the same value, delegating properties simplifies the re-use of your Superblocks.
3. In the Wiring Scheme, you can see how pins are named using blockid:pinname, and how output pins are wired to input pins.
   • For now, consider shunt to be the same as wire. shunt is covered below under Wiring.

There are some pre-made superblocks in the ACS Block System library, which you can compose into your own Specification documents. Note, however, that until some later date it is not possible to create your own superblocks to re-use in this same way.

Applications

All touchatag Applications—whether the simple Web Link application or the multi-tag Music Cube application—are built using a type of block called an Application. Because an Application block describes a complete touchatag application, an Application block is actually the same as a Specification document.

As with blocks and superblocks, an application has pins and properties. Applications also have some components not found in other block types:

1. Commands
2. A Pre-defined Runtime Interface

Commands

A Command represents a distinct operation to which one or more touchatag tags can be associated.

Remember, a touchatag application may use more than a single tag. For example, the Music Player Application uses a physical cube with a tag on each of its six faces. Each tag is mapped to a different command within the same overall application.

Example 4a: Commands

Let's examine the commands in a Specification Example for the Bidirectional Web Wheel. This is an application opens web links from a list. One command moves forward to the next link, the other backwards to the previous.

We can see how these two commands are represented in the application section of the complete Specification example for this application:

...
<command id="next" name="Show next link"/>
...
<command id="previous" name="Show previous link"/>
...

The command id is the identifier used within the Application. The name is a friendly name that end users see in the Configurator when associating the application with tags, as shown at right.

But if a single Application can have multiple commands, and the different commands can have different actions, then how does the Application know how to handle whichever command invoked the application? That brings us to the Application's pre-defined runtime interface.

Predefined Runtime Interface

Every Application has a set of predefined input pins that can provide the application with initial contextual runtime information. The information provided by these interfaces can be used by the Application as conditions for making logical decisions. For example, the command-id-in runtime interface provides context on which command was used to invoke the application.

An Application's predefined runtime interface also includes an output pin called action-out, which defines the action to send back to the client system.

The complete list of runtime interfaces are documented in the Specification documentation.

Example 4b: Runtime Interfaces

Let's once again consider the Specification Example for the Bidirectional Web Wheel, and observe how it uses the Application runtime interfaces command-id-in and action-out in its wiring scheme. (Note that you do not need to understand much about how a wiring scheme works to get the key concept here. We will discuss wiring schemes right after this.)

...
<wiringscheme>
                <shunt from="command-id-in" to="t2i:in"/>
                <wire from="t2i:out" to="cu:in"/>
                <wire from="cu:out" to="wl:in"/>
                <shunt from="wl:out" to="action-out"/>
            </wiringscheme>
...

You can see that the wiring scheme section connects command-id-in to the in pin of a block named t2i (which is defined in the complete example as a text-to-integer-mapping block that assigns +1 to the next command, and -1 to the previous command). Without necessarily understanding what the t2i block does, you can see that the command-id is being used as an input to the Application's workflow.

Similarly, You can also observe that the wl (web-link) block's out pin is wired (shunted) to the application's action-out pin, which sends some action back to the client system that initially invoked the application.

Wiring

Let us now go into more detail on the wiring concept. As previously stated, you wire individual blocks together to create the functionality you desire your Application to have. You do this by defining connections between the various input and output pins of different blocks in a Wiring Scheme.

As previously noted, all pins have a direction of either in or out. Each Pin also has a type that defines what kind of data that it provides (if the Pin's direction is in). In general, you must always wire an output pin to an input pin of the same data type.

Wires

A simple connection between the pins of two different blocks is called a wire. A wire always connects from the output pin of one block to the input pin of another, as was shown in the previous example:

...
<wire from="t2i:out" to="cu:in"/>
...
<wire from="cu:out" to="wl:in"/>
...

Shunts

As explained above, Application blocks and Superblocks are composed of other blocks. The blocks that they contain are wired together as previously explained. However, because Applications and Superblocks function as aggregating constructs—that is, they use abstraction to simplify whatever internal complexity they contain—Applications and Superblocks will have input and output pins of their own. When wiring the pin of one of these aggregating constructs to the pin of one of its constituent components, both pins will have the same direction. This requires you to use a shunt instead of a wire.

For example, as previously discussed, Application blocks provide various runtime interfaces, such as command-id-in. The pin command-id-in is an input pin, because it provides input into the Application block. However, if we want to use the command-id-in data in a block inside the application, we must connect it to an input pin for that block. That means we must use a shunt, as we saw in the example:

...
<shunt from="command-id-in" to="t2i:in"/>
...
<shunt from="wl:out" to="action-out"/>
...

Summary

Defining a Wiring Scheme is a key part creating any Specification. The complete reference for creating a Wiring Scheme, including its various options, is documented in the Specification documentation. For now, bear in mind the following distinction between wires and shunts:

• Wire: A connection between an output pin and an input pin between two constituents (green in image)
• Shunt: A connection between pins with the same direction (output to output, or input to input), where one pin belongs to the aggregating construct, and the other pin belongs to a constituent (blue in image)

Next Step

Now that you have learned how the Block System works, move on to learn how to construct Specification documents to define new applications.