CircleScript: Content Replacement and Concatenation

This article is a syntax reference for CircleScript's core content assembly features, including tag syntax, $using directives, local definitions, iteration, and the .cmf file format.

If you are new to CircleScript, read the CircleScript Overview first to understand the underlying concepts before working through the syntax here.

In this article

• Tag syntax
• $using directives
• Local definitions
• Defaults: coalescence and guard
• Iteration with $each
• The .cmf file format
• Other supported data formats

Tag syntax

CircleScript uses [$path] syntax to reference content. The path can point to a file in the CMS or to a locally defined variable.

$using directives

The $using directive makes a CMS directory or data file available for tag resolution within the current scope. Once declared, tags are resolved against the specified path before looking elsewhere.

Multiple $using directives can be stacked. If the same key is defined in more than one file, the last $using directive takes precedence within the current scope.

$using directives stack and can be scoped. A $using declared inside a nested scope [$$$...$$] applies only within that scope.

Local definitions

Local definitions create variables within the current content scope. They are available from the point of definition through the end of the current scope.

Variables defined in a nested scope do not affect the outer scope.

Defaults: coalescence and guard

Coalescence

Use the ?? operator to provide a fallback value when an expression is blank or missing.

Syntax:

Example:

Coalescence expressions can be chained:

Guard

Use the ? operator to include content only when an expression is not blank.

Syntax:

Example:

AND and OR logic

Guard and coalesce syntax can be combined to implement simple boolean logic. Blank represents false; any non-blank value represents true.

AND example:

OR example:

Iteration with $each

The $each directive repeats a block of content for each item in a range or sequence. It stops automatically once its block produces no output (short-circuit evaluation).

Basic iteration

Iterator in path

Implicit path iteration (shorthand)

[$content_*] is shorthand for [$content_[$i]] when used inside a $each directive.

Qualifying the each block

Use a guard expression to skip blank items and stop iteration cleanly.

Iteration in a sub-context

To loop through a block in the middle of other content, place the repeated block in a nested scope with a $each directive on the first line.

The .cmf file format

The .cmf (Content Manager Format) file is the primary format for storing key-value definitions used in CircleScript content assembly. It supports both short single-line definitions and multi-line HTML blocks.

Short definitions

Each definition starts in the first column with an identifier followed by an equals sign, with the value on the same line.

Multi-line HTML blocks

When the equals sign is followed by a newline with no value on the same line, the value is pulled from the following lines until the next definition or the end of the file.

Using a .cmf file in content

Other supported data formats

CircleScript can also parse .csv, .tsv, .json, and .xml files into name-value pairs for use in content assembly.

.csv and .tsv

Tabular data is converted to name-value pairs using column headers. Columns that represent unique keys must be annotated with (key) in the header row.

.json

JSON objects and arrays are traversed and converted to name-value pairs by building up keys as the structure is parsed.

.xml

XML is parsed into name-value pairs. Both element content and nested structures are accessible.