In the Blocks Editor, you can create and edit the contract of a building block on the page called Contract.
This page contains a transition table, displaying source and target states, and the parameter nodes hat are involved in a transition. (Note that this is not possible for Application blocks that does not have any contracts since they are the outermost level).
In some cases, building blocks are so simple that the SDK can “guess” the right contract. For this action, select Generate Contract… and choose Generate default Contract on the transition table.
The resulting contract always has one state named active and a transition for each parameter node. For some cases, this may already be the contract that you want to have. In all other cases, this can be a starting point that can be manually extended.
When you add or edit a transition, you'll get the window depicted in the following figure.
- Source states can be an initial state or a normal state. There must be exactly one initial state. States can have names that help to understand the states of the building block.
- Target states can be normal states or final states. Since all building blocks need some form of termination, at least one final state is needed.
- A transition refers to all parameter nodes that are passed by a token within the activity step that the transition describes.
- In most transitions that contain more than one parameter node, the sequence of the nodes is important. In most cases when there are several nodes per step, the block is setup to responds immediately to an input node with an output node, like next and out the example above, but it can also be used to allow immediate input node to an output node or signal on several nodes. The sequence might be very important, pay very close attention to it. Use the Move Up and Move Down buttons to sort the nodes.
The labels of the transitions are computed automatically, based on which parameters are part of the transition and in which sequence they are sorted. A label is a sequence of groups of parameters. A group either consists only of input or output parameters.
- The semicolon “;” separates different groups of parameters.
- The plus “+” separates parameters within the same group.
- The sequence of groups alternates between input and output groups.
- The slash “/” is written after the first group of input parameters, or before the first group of output parameters.
Intuitively, the slash is placed to that spontaneous transitions, which are triggered from within a building block are written with a slash as prefix.
It is necessary to understand contracts and activity steps in order to correctly use a building block and all the more to create the contract of a building block.
A general guideline to create a contract of a block manually is as follows:
- It is often the case that the author of the block already have an idea in mind how the block should work.
- Identify the activity steps in the activity diagram, also token markings before and after a step.
- Pay attention to the steps that contain parameter nodes and also the types of parameter nodes.
- Then, create the contract based on those factors above:
- An initial transition is related to an activity step that includes a starting parameter node.
- Activity steps that include a terminating node or an alternative terminating node form transitions to a final state.
- states correspond to token places inside the block between the activity steps.
- transitions refer activity steps containing one or more parameter nodes.
You can check whether the block and its corresponding contract are consistent by using the analyzer tool. Moreover, make sure that the block behaves as intended with the animation tool.
An example of creating the contract of a block is described here.
There are activity steps in a local block that include neither input nor output parameters. Intuitively, for these internal steps we do not create transitions.
A building block can be composed of inner blocks. Creating a contract of this kind of block is pretty much the same as the guideline described above. However, in this case you also need to consider the inner blocks' contracts.
An example for creating a contract in the presence of inner blocks is described here.