Download the PHP package restruct/silverstripe-simpler without Composer

Simpler Silverstripe

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

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 + 24kb = ~191kb (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)

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):

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

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. Static session helpers

6. 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().

7. Configuration summary

8. 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

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

• Branch ss5: SilverStripe 5 (Vue 3)
• Tag 0.1.9: SilverStripe 5 (Vue 2, legacy)
• main: SilverStripe 6