README

A Silverstripe CMS form field that allows users to compose template strings by chaining visual token pills instead of typing raw text.

Overview

This module provides TokenTemplateField, a custom form field for the Silverstripe CMS. Instead of manually typing placeholder syntax, users build template strings by selecting and arranging visual token segments (pills). The underlying value is stored as a plain string with curly-brace placeholders (e.g. {RecipientName}).

Features

• Visual pill/segment-based token composition
• Configurable list of available tokens per field instance
• Drag & drop reordering of tokens (native HTML5, no external library)
• Inline editing of free text tokens (click to edit, Enter or blur to confirm)
• Collapsible token selector with chevron toggle
• Individual pastel colors per token or uniform grey mode
• Per-token custom color support via color option
• Optional free text tokens (ABC button) — can be disabled
• Readonly and disabled states
• Keyboard support: Delete/Backspace to remove selected tokens
• Stores a plain text value with curly-brace-delimited placeholders
• No external JS dependencies — built with vanilla JS and jQuery Entwine

Requirements

• PHP ^8.1
• Silverstripe Framework ^6
• Silverstripe Admin ^3

Installation

composer require clesson-de/silverstripe-token-template-field

After installation, expose frontend assets and rebuild the database:

composer vendor-expose
vendor/bin/sake dev/build flush=all

Usage

Basic usage

use Clesson\Silverstripe\TokenTemplateField\Forms\TokenTemplateField;

$field = TokenTemplateField::create(
    'EmailSubject',
    'Email subject',
    [
        'RecipientName'  => 'Recipient name',
        'BillingMonth'   => 'Billing month',
        'BillingYear'    => 'Billing year',
        'OperationCount' => 'Number of operations',
    ]
);

The field stores its value as a plain string, e.g.:

Billing for {RecipientName} – {BillingMonth} {BillingYear}

Tokens with custom colors

Each token value can be either a plain string (label) or an array with label and optionally color:

$field = TokenTemplateField::create(
    'EmailSubject',
    'Email subject',
    [
        'RecipientName' => ['label' => 'Recipient name', 'color' => '#fde68a'],
        'BillingMonth'  => ['label' => 'Billing month', 'color' => '#bbf7d0'],
        'BillingYear'   => 'Billing year', // uses pastel palette or mono
    ]
);

Disable free text tokens

By default, users can add free text tokens via the ABC button. To restrict the field to predefined tokens only:

$field->setShowFreeText(false);

Colorful mode

By default, all tokens use a uniform grey background. To enable individual pastel colors per token:

$field->setColorful(true);

Note: Tokens with an explicit color value always use their custom color, regardless of the colorful setting.

Readonly / Disabled

The field supports Silverstripe's standard readonly and disabled transformations:

// Readonly — tokens are displayed but cannot be modified
$field->setReadonly(true);
// or
$field->performReadonlyTransformation();

// Disabled — tokens are displayed, input is disabled
$field->setDisabled(true);
// or
$field->performDisabledTransformation();

In both states, tokens are rendered without remove buttons, drag handles, or the token selector.

Parsing a template string

Use the static parse() method to replace {key} placeholders in a template string with actual values:

use Clesson\Silverstripe\TokenTemplateField\Forms\TokenTemplateField;

$result = TokenTemplateField::parse(
    'Hello {firstname} {lastname}, your order {orderId} is ready!',
    [
        'firstname' => 'Max',
        'lastname'  => 'Mustermann',
        'orderId'   => '12345',
    ]
);
// → "Hello Max Mustermann, your order 12345 is ready!"

Placeholders that are not present in the values array remain unchanged in the output.

API Reference

Stored Value Format

The field stores a plain Varchar-compatible string. Free text is stored as-is, predefined tokens are wrapped in curly braces:

Hello {firstname} {lastname}, your order {orderId} is ready!

License

BSD-3-Clause — see LICENSE.