Using square brackets without unintended token replacement

The problem

ECA uses square brackets [ and ] to identify tokens. When ECA encounters text like [something], it attempts to replace it with the corresponding token value. If the token does not exist, the content inside the brackets is removed, resulting in an empty string.

This becomes a problem when you need to use square brackets for purposes other than tokens. A common example is using CSS frameworks like Tailwind CSS, which uses bracket notation for arbitrary values. For instance, a class like [&_.cf-form-label]:tw-hidden would be interpreted by ECA as a token reference, and the content between the brackets would be stripped away.

The same issue arises in any context where square brackets are part of the intended value, such as:

• Tailwind CSS arbitrary value classes (e.g. [&_.label]:hidden)
• Form element machine names containing brackets (e.g. wrapper][form][submit)
• Regular expressions or other syntax that uses square brackets

The solution

The recommended approach is to define two custom tokens that resolve to the bracket characters themselves:

Token	Value
[bracket:open]	[
[bracket:close]	]

Since token replacement is not recursive by default, the resulting bracket characters will not trigger further token replacement. This means you can safely use these tokens wherever you need literal bracket characters.

For example, instead of writing:

[&_.cf-form-label]:tw-hidden

You would write:

[bracket:open]&_.cf-form-label[bracket:close]:tw-hidden

After token replacement, this produces the intended result: [&_.cf-form-label]:tw-hidden.

Making bracket tokens available globally

Rather than defining these tokens in every model that needs them, you can make them available globally using the ECA token generate event. This event fires before ECA processes tokens for any model, making the bracket tokens available everywhere on your site.

Step-by-step setup

1. Create a new ECA model and give it a descriptive name, such as "Global Tokens".

2. Add the event ECA token generate event as the trigger. In the "Name of token" field, enter bracket:* to react to all tokens in the bracket group.

3. Add the first action Token: set value and configure it:

   • Token name: bracket:open
   • Token value: [

4. Add a second action Token: set value and configure it:

   • Token name: bracket:close
   • Token value: ]

5. Save and enable the model.

Once this model is active, the tokens [bracket:open] and [bracket:close] are automatically available in the token browser and in text fields within any ECA model on your site. You only need to set this up once.

Tip

This approach of using the ECA token generate event to define utility tokens can be extended to other global tokens you might need across your models. Consider adding other commonly used special characters or values to the same model.