Download the PHP package restruct/silverstripe-simpler without Composer

Simpler Silverstripe

Maintained by Restruct. If this module saves you time, you can support ongoing maintenance.

Makes SilverStripe Admin development simpler by re-introducing traditional basics.

Requirements

• Silverstripe 5 or 6 (silverstripe/framework ^5 || ^6)
• PHP 8.1 or newer
• Optional: lekoala/silverstripe-pure-modal for SimplerModalField / SimplerModalAction (^1.2 on Silverstripe 5, ^2 on Silverstripe 6)

Installation

Version compatibility

main is the maintained line: one release line serves both Silverstripe 5 and 6, so there is no separate Silverstripe 6 branch. Silverstripe 4 reached end of life in April 2025 and is no longer supported or tested here; projects still on it can stay on the 0.x tags, which remain available. Upgrading from 0.3.x: see CHANGELOG.md.

composer.json is the source of truth for exact constraints; this table is a quick reference.

Features

Total sizes:

• DOM events only: ~5kb (always loaded)
• Import map with Vue only: ~5kb + 162kb = ~167kb (for your own Vue components)
• Modal via PHP: ~5kb + 162kb + 42kb = ~209kb (import map auto-injected)
• Modal via JS config: same, but requires AdminExtension in config

1. DOM events (always loaded)

Listen for dynamically inserted content (Ajax, React components):

Note: An xhr_buffer element (<template id="xhr_buffer">) is automatically created on page load. This hidden element is used to parse AJAX HTML through jQuery before inserting into Vue/DOM, which triggers Entwine-style listeners that don't fire when content is inserted directly by Vue.

Event types:

• LOAD - Initial DOMContentLoaded
• MUTATION - MutationObserver detected DOM changes
• MOUNT - React Form component mounted (on specific element)
• UNMOUNT - React Form component will unmount

jQuery $ alias (opt-in)

This module does not set window.$ by default (anymore, to avoid conflicts). If you want the $ shorthand, either:

1. Add to your own JS file: window.$ = window.$ || window.jQuery;
2. Or use Requirements: Requirements::customScript('window.$ = window.$ || window.jQuery;', 'jquery-alias');

2. Vue 3 components (via import map, opt-in)

IMPORTANT: If using Vue components (SimplerModalField, EditProtectedTextField, or your own), you MUST add AdminExtension to LeftAndMain. Components will trigger a warning if the import map is not available on initial page load.

For using Vue 3 in your own code, add the extension:

This injects an import map that makes Vue available via import { createApp } from 'vue'. The extension automatically uses the dev build (with warnings/devtools) or prod build based on environment.

Option A: Self-contained ES module file

Create a JS file (not webpack-bundled) and load it as a module:

Load via Requirements with type="module":

Option B: Inline in SilverStripe template

Mix SS template tags directly with Vue - ideal for injecting server data into Vue components:

Key patterns:

• Use $Variable.JSON.RAW for objects/arrays/booleans (raw JSON, no escaping)
• Use "$Variable.JS" for strings (JS-escaped, in quotes)
• Use $ID or $HexID to make element IDs unique when template is used multiple times
• Mix <% if %> SS conditionals with Vue v-if directives as needed
• Use {$T('Label')} or $fieldLabel('Name') for translated strings in HTML

Entwine compatibility note: Vue components inside CMS forms can trigger Entwine's MutationObserver bug (el.getAttribute is not a function). See "Known Issues" section below for details and workarounds.

3. Modal dialog (Vue 3 + Bootstrap modal, opt-in)

Silverstripe 5 and 6. The CMS ships Bootstrap 4 CSS on Silverstripe 5 and Bootstrap 5 CSS on Silverstripe 6. simpler-modal.js bundles both modal implementations and picks the one matching the page's CSS at runtime, so the same code works on either. To close the modal from HTML you put in bodyHtml, use data-simpler-dismiss (Bootstrap's own data-dismiss="modal" and data-bs-dismiss="modal" are honoured on both majors too).

Note: The Vue import map is automatically injected when using SimplerModalField/Action PHP classes.
Manual setup only needed if using simpler.modal directly from JavaScript.

To use simpler.modal from your own JS, you need both the Vue import map and simpler-modal.js:

Option A: Via PHP (in your Controller or Extension):

Use requireModal() rather than your own Requirements::javascript(..., ['type' => 'module']) for the modal: when the screen is reached through CMS navigation (menu, tab or breadcrumb, all AJAX), the admin loads the response's scripts as classic scripts, where a module fails ("Cannot use import statement outside a module"). In an AJAX request requireModal() therefore adds simpler-modal-loader.js, a classic script that imports the module (and does nothing when the modal is already on the page). The import map still has to be on the page from the first full load, which is what AdminExtension on LeftAndMain does.

Option B: Via YAML config (always loaded in admin):

Basic usage

All options

Loading content via AJAX

All properties reset to defaults when the modal gets closed.

4. PHP FormField classes (drop-in PureModal replacement)

SimplerModalField and SimplerModalAction extend lekoala/silverstripe-pure-modal classes but render via simpler.modal instead of the CSS checkbox mechanism.

Requires: lekoala/silverstripe-pure-modal

PureModal must be manually installed to use these classes
Install via: composer require lekoala/silverstripe-pure-modal

How it differs from PureModal

PureModal renders inside the CMS form (as FormField), which means forms in modal become nested forms (invalid HTML). PureModal elegantly works around this using iframes.

SimplerModal takes a different approach: the modal is appended to document.body (outside the CMS form hierarchy), so forms inside work correctly without needing an iframe. This allows SimplerModalAction to render actual SilverStripe forms that submit directly.

Usage

The modal's form posts only its own fields to the record's edit form, through lekoala/silverstripe-cms-actions (doCustomAction). The record method (here translate($data)) gets that data alone: the edit form is neither validated nor saved for this request, so the method validates its own input. For this the action adds a hidden, validation-exempt stand-in button to the edit form (SimplerModalExemptAction, rendered as nothing).

How it works

The PHP classes render a button with a data-simpler-modal attribute containing JSON config:

A generic click handler in simpler-modal.js parses this config and opens the modal:

Migration from PureModal

Simply change the imports - the API is compatible:

All existing code continues to work - same API, better rendering.

5. GridField modal components

Two components for modals in GridField context (not available in PureModal or cms-actions):

GridFieldToolbarModalAction (toolbar buttons)

For toolbar buttons that open a modal with form fields, submitting through GridField action routing:

Key difference from SimplerModalAction:

• SimplerModalAction is for DataObject edit forms (getCMSActions())
• GridFieldToolbarModalAction is for GridField toolbars (action routing via StateID)

Why this exists: Neither lekoala/silverstripe-pure-modal nor lekoala/silverstripe-cms-actions provide this functionality. PureModalAction only works in detail forms, and GridFieldTableButton only supports basic JS prompt()/confirm() dialogs.

Error handling

The AJAX handler reads the response body on HTTP errors and displays it in the modal. Throw HTTPResponse_Exception to show a meaningful error:

Full page reload (X-Reload header)

By default, on success the modal reloads only the parent GridField. To force a full page reload (e.g., when other tabs also need refreshing), set the X-Reload header:

GridFieldModalButton (per-row column buttons)

For per-row buttons in a GridField column that open a view-only modal:

Options (all fluent): setColumnName() (default ModalAction), setButtonClasses() (default btn btn-sm btn-outline-info), setModalSize() (sm/lg/xl or a CSS width), setShowCloseButton() (default true) and setCloseButtonText() (default Sluiten).

The button is rendered inside <span class="action">: the .action ancestor keeps a click from opening the row's record, while the button itself must not carry action, because silverstripe/admin turns every .grid-field .action button into an AJAX GridField reload (#5, changed in 1.0.0).

GridFieldToggleFieldButton (row toggle buttons)

For per-row buttons that cycle a field through values (boolean or multi-state):

Advanced options:

6. Static Session helpers

The helpers use the session of the current request (Controller::curr()->getRequest()->getSession()), looked up on every call, so they also follow the request in a long-running process (queue runner, worker). Before 1.0.3 the first session was kept for the rest of the process (#7).

7. HeadRequirements (import maps, early scripts)

For scripts that must be in <head> (import maps, early config):

Also available as template globals: $HeadReq_importMap(), $HeadReq_js(), $HeadReq_customScript().

8. Configuration summary

9. Development

Local git checkout

When developing this module locally (checked out as git repo instead of installed via composer), you need to add the autoload path to your project's composer.json:

Then run composer dump-autoload. This is required because composer doesn't automatically discover classes in local module directories - it only knows about paths defined in its autoload config.

Building assets

client/dist is committed; CI rebuilds it and fails if it differs from what client/src produces.

Tests

The PHP tests need a Silverstripe host project (they cannot run from the module directory alone). Require the module there through a Composer path repository with "symlink": true - /tests is export-ignore, so a dist install has no tests - plus silverstripe/recipe-testing and, for the modal field tests, lekoala/silverstripe-pure-modal. .github/workflows/ci.yml builds exactly such a host for each supported Silverstripe major and is the reference setup.

Known Issues

Entwine + Vue Conflict

Vue components in CMS forms can trigger TypeError: el.getAttribute is not a function due to Entwine's MutationObserver not filtering non-Element nodes.

Solution: This module includes automatic error suppression in simpler-silverstripe.js that allows Vue to work in CMS forms.

See docs/ENTWINE_VUE_CONFLICT.md for details, alternatives, and future investigation options.

Version notes

See Version compatibility above.