Macros are used to define text replacement patterns that automatically convert specific strings into formatted or symbolic text during output or preview.

• They are stored on a per-project basis.
• They act as shortcuts for generating consistent markup, icons, symbols, or text expansions throughout your project.
• Macros are processed anywhere that supports markup text, such as Text Layers (but not Text Geometry Layers).
• They can be referenced directly in your Data Sources or typed into property fields within the Property Editor.

Macros are editable from the Project Toolbar.

Macro Editor Overview #

The columns in the Macro Editor each represent:

• Pattern:
  • The text key or pattern to match. This is what will be replaced when the macro is expanded.
• Expansion:
  • The text or markup that will replace the pattern during rendering.
• Sample:
  • Shows what should be entered into Data Sources and property fields in order to be replaced.
  • The keys “Parameter1, Parameter2, etc.” should be replaced with whatever text or key you would like to be placed into the expansion.
  • This must be wrapped in brackets “[ ]” as is shown in the sample, or else the expansion will not execute.
• Output:
  • Displays the final rendered result after the macro expansion is applied.

This example uses markup in the first Macro definition to simplify the writing process.

How Macros Work #

During output, Cocktail Card Designer scans for text that matches a macro pattern and replaces it with the defined expansion.

This conversion is reflected automatically in:

• The Layout Preview
• The Layout Canvas
• The Final Output

Observe text in this Text Layer with the [Red] sample text entered.

We see in our example picture that the sample text [Red] will expand to:

The result is reflected in the Layout Canvas:

Numbered Parameters #

Macros that include numbered placeholders must follow these rules:

• Parameters must start at 0 (e.g., {0}, {1}, {2}, etc.).
• Parameters must be sequential.
  • Skipping numbers (like {0} and {2} only) is not valid.
• Multiple numbered parameters can be used within a single macro to allow flexible input substitution.

For example:

• Pattern:
  • icon_{0}_{1}_{2}
• Expansion:
  • <icon src=”{0}/{1}/{2}”/>
• Sample:
  • [icon_Fire_Rare_001]
• Output:
  • <icon src=”Fire/Rare/001″/>

Unnumbered Macros #

If no numbered placeholders are used, the pattern works as a simple text key, replacing the entire match directly.

For example:

• Pattern:
  • Red
• Expansion:
  • 0x2423
• Sample:
  • [Red]
• Output:
  • 0x2423

Anywhere [Red] appears, it will be replaced with 0x2423.