Frames and Calls

Frames

Frames are sets of calls, which are instructions that interact programmatically with an Urtext project. Frames are written inside frame wrappers, double square brackets:

[[    ]]

Text inside these wrappers is interpreted as instructional code. Frames can be written anywhere; it is not necessary to store a frame in the same file it targets.

A minimal frame includes a TARGET() call for the output and another call to specify the output. The target can be a node, file or virtual target.

Calls

Calls have capitalized, non-whitespace names, with underscores permitted. Calls are followed immediately by opening and closing parentheses which enclose zero or more parameters.

[[
TARGET(| Some output Node >)
INCLUDE(*)
]]

The link syntax inside the TARGET() directive is not required but makes the parameter more readable and provides a working link to the target node.

There are no restrictions on spacing, indentation, newlines, or other arbitrary text or whitespace. Frames may contain any number of calls. Calls are evaluated imperatively, in order from first to last.

Making a frame does not create the target. The target node must exist in the project. It may be in the same file or in any other file in the project.

Included Calls

Urtext includes the calls below. You can also write your own.

SHOW( ) - Templates the output of each node outputted in a dynamic definition
SORT( ) - Sorts the included nodes.
COLLECT( ) - Aggregates occurrences of metadata, including timestamps. Returns a separate item for each occurrence
EXCLUDE() or -() - Specifies nodes to exclude when building a dynamic output.
INCLUDE( ) or +( ) - Specifies nodes to include when building a dynamic output.
LIMIT( ) - Limits the output to the specified number of results
TARGET( ) or >( ) - Specifies a target to dynamically populate with output.
TREE( ) - Shows a tree representation of each included node and its descendants
MAX_LENGTH( ) - Arbitrarily limits the dynamic output to the specific number of lines.
EXEC() - Executes arbitrary Python code.
WHEN( ) - Specifies when a dynamic definition should be evaluated.
LOG( ) - Outputs all project log (errors and information)
INFO( ) - Outputs statistics about the current project.
TEXT( ) - Displays arbitrary text
FILES() - Shows a tree representation of files from a particular starting path.

 

Tip: Sublime Text Snippet

In Sublime Urtext, a snippet is provided to automate creating and titling a new node and populating its frame in a single step. To invoke it, type frame and press tab. Type the name of the new node, then tab between entry points in the definition template. Delete whatever portions you do not need.

[rve src=”https://urtext.co/wp-content/uploads/2024/01/definition-snippet-demonstration.mp4″ ratio=”16by9″]