Directives

Blueprints use several types of directives, each with a distinct function:

• Static, Plain Text

• Substitutions

• Flows

• Functions

• Comments

Static, Plain Text

Text is the most basic content your blueprint can contain. In fact, this is a completely valid blueprint, even though it doesn't contain any dynamic data:

Just simple text

Since all strings are processed as Unicode, all Unicode characters are allowed, including emojis or special control characters.

In some situations, you want to use plain text inside the control tags, for example, to define the value of a substitution parameter. In this case, you can enclose it with double quotes to tell the syntax parser to ignore it:

Just a simple text: {{ text.suffixed("_") }}

Note - ignoring only works inside computed areas - you can use quotes outside them to participate in the output. The syntax engine is smart enough to know that quotes are expected or missing and in most cases will still produce valid results without them.

Substitutions

Substitutions allow replacing certain parts of the blueprint with dynamic data provided by variables, functions, or any other structure containing data.

Username: {{ name }} -> Username: Jiri

The data can also be further refined using transformers:

Username: {{ name.uppercased() }} -> Username: JIRI

Substitutions and transformers are very powerful tools because they allow you to turn static templates into dynamic definitions - see the dedicated section for all the options.

Flows

Flows refer to definition structures that control the flow of execution - conditions, loops, tree-traversals, and others. Flows start with {[ and end with ]} tags respectively, and must be closed with {[/]}:

{[ for name in names ]}
- {{ name }}
{[/]}

Some flows change or enhance data inside the blocks they define. In the example above, the value of the property name will always be different with each pass of the loop. When running with appropriate data (names = [Anna, George, Peter]), the output will look like this:

- Anna
- George
- Peter

See the dedicated section for all the options.

Functions

Functions have two distinct use cases - computing and data retrieval. Functions start with @ and are followed by a function definition and its properties:

{[ for token in @ds.allTokens() ]}
- {{ token.meta.name }}
{[/]}

In the example above, we are requesting data from the currently opened project to retrieve all screens - and then print out their names. When run with appropriate data, the output will look like this:

- cta
- primary
- secondary

See the dedicated section for all the options.

Comments

Blueprints can get really complex really quickly, especially for tasks concerning code generation. Comment syntax is supported to enhance maintainability of blueprint code. Comments are enclosed within {* and *} tags:

{* XML Node *}
<doc />

Comments are also not constrained by their position and can be part of the plain text:

<doc name="{{ data.name }}" /> {* XML Node *}

or even

<doc name="{{ data.name }}" {* XML Node *} />

Finally, multi-line comments are supported as well:

{*
   XML Nodes
   - Docs
   - Pages
*}
<docs />
<pages />

Comments can contain any character as everything inside a comment is ignored and does not contribute to the output.