PHPackages                             clesson-de/silverstripe-token-template-field - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Templating & Views](/categories/templating)
4. /
5. clesson-de/silverstripe-token-template-field

ActiveSilverstripe-vendormodule[Templating & Views](/categories/templating)

clesson-de/silverstripe-token-template-field
============================================

A Silverstripe CMS form field that allows users to compose template strings by chaining visual token pills.

1.0.2(2mo ago)088BSD-3-ClauseJavaScriptPHP ^8.1

Since May 1Pushed 2mo agoCompare

[ Source](https://github.com/clesson-de/silverstripe-token-template-field)[ Packagist](https://packagist.org/packages/clesson-de/silverstripe-token-template-field)[ RSS](/packages/clesson-de-silverstripe-token-template-field/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (2)Versions (5)Used By (0)

Silverstripe Token Template Field
=================================

[](#silverstripe-token-template-field)

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

Overview
--------

[](#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
--------

[](#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
------------

[](#requirements)

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

Installation
------------

[](#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
-----

[](#usage)

### Basic 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

[](#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

[](#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

[](#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

[](#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

[](#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
-------------

[](#api-reference)

MethodDescription`setAvailableTokens(array $tokens)`Set the available tokens. Values can be strings or `['label' => '...', 'color' => '#...']` arrays.`getAvailableTokens()`Returns the configured tokens array.`setShowFreeText(bool $show)`Show or hide the free text (ABC) button. Default: `true`.`setColorful(bool $colorful)`Enable individual pastel colors (`true`) or uniform grey (`false`). Default: `false`.`setReadonly(bool $readonly)`Set the field to readonly mode.`setDisabled(bool $disabled)`Set the field to disabled mode.`performReadonlyTransformation()`Returns a readonly clone of the field.`performDisabledTransformation()`Returns a disabled clone of the field.`static parse(string $template, array $values)`Replaces `{key}` placeholders in a template string with the given values.Stored Value Format
-------------------

[](#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
-------

[](#license)

BSD-3-Clause — see [LICENSE](LICENSE).

###  Health Score

39

—

LowBetter than 84% of packages

Maintenance86

Actively maintained with recent releases

Popularity9

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~7 days

Total

3

Last Release

70d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/52702628?v=4)[Clesson](/maintainers/clesson-de)[@clesson-de](https://github.com/clesson-de)

---

Top Contributors

[![clesson-de](https://avatars.githubusercontent.com/u/52702628?v=4)](https://github.com/clesson-de "clesson-de (4 commits)")

### Embed Badge

![Health badge](/badges/clesson-de-silverstripe-token-template-field/health.svg)

```
[![Health](https://phpackages.com/badges/clesson-de-silverstripe-token-template-field/health.svg)](https://phpackages.com/packages/clesson-de-silverstripe-token-template-field)
```

###  Alternatives

[silverstripe/cms

The SilverStripe Content Management System

5253.6M1.4k](/packages/silverstripe-cms)[dnadesign/silverstripe-elemental

Elemental pagetype and collection of Elements

1101.1M315](/packages/dnadesign-silverstripe-elemental)[symbiote/silverstripe-advancedworkflow

Adds configurable workflow support to the CMS, with a GUI for creating custom workflow definitions.

46302.4k9](/packages/symbiote-silverstripe-advancedworkflow)[silverstripe/login-forms

A collection of templates for the CMS login screens

191.4M30](/packages/silverstripe-login-forms)[symbiote/silverstripe-queuedjobs

A framework for defining and running background jobs in a queued manner

55894.5k105](/packages/symbiote-silverstripe-queuedjobs)[silverstripe/admin

SilverStripe admin interface

262.8M389](/packages/silverstripe-admin)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)