README

A grid-based content block system for SilverStripe 6. Editors compose pages from Section → Row → Column → content block instead of one long HTML field, and the column widths they pick are emitted as your CSS framework's own classes — Bootstrap, Tailwind, Bulma, or an adapter you write yourself.

Why

Elemental-style modules give editors a flat list of blocks and leave layout to the developer. Page builders give editors full layout control and leave the design system behind. This module sits between the two: the hierarchy is fixed and validated on the server, but within it editors control widths, offsets, and per-breakpoint visibility — and every choice resolves to classes your theme already ships.

A hierarchy that cannot be broken. Sections hold rows, rows hold columns, columns hold content. Enforced at write time and at drop time, not just in the UI.
Framework-agnostic output. One config-driven adapter turns a column of width 8 into col-md-8 (Bootstrap), md:col-span-8 (Tailwind), is-8-tablet (Bulma), or whatever your own framework spells it — each at that framework's own breakpoint, since the viewport names come from the adapter too.
Responsive per column. One default layout per column, plus overrides only for the breakpoints that differ.
Versioned like the rest of the CMS. Draft/live, publish-with-the-page, per-element history, and a read-only grid in the history viewer.
Drag and drop across containers. Move a block into another column, a column into another row, a row into another section — with optimistic updates and rollback on failure.
Shared blocks. Maintain a piece of content once in a central library and place it on any number of pages. Edit it anywhere, publish it on its own schedule, detach it when one page needs to diverge. (guide)
Multi-locale ready. Optional Fluent integration gives each locale its own isolated grid.

The content model

Page
└── Section          zone-scoped band; the only thing allowed at page level
    └── Row          horizontal group
        └── Column   carries width / offset / visibility per viewport
            └── Content block   any ContentElement subclass

Writing a Section automatically creates the Row and Column beneath it, so a new section is usable immediately. Sections carry a zone (main, sidebar, …), which is how one page can host several independent grids.

That same tree in the editor — a section holding a centred 8-of-12 intro row above a row of three 4-column cards:

Responsive layout, per column

Each column stores one default layout plus overrides for the breakpoints that differ. Editors pick which viewport they are editing from the adapter's own breakpoints, and the picker reports which ones carry overrides and offers to reset them:

Nothing is written for a viewport that matches the default, so a column that never changes stores no overrides at all.

The grid editor guide walks through the rest of the editing experience.

Requirements

PHP ^8.3
silverstripe/framework ^6.0, silverstripe/cms ^6.0, silverstripe/admin ^3.0, silverstripe/versioned ^3.0, silverstripe/vendor-plugin ^3.0
unclecheese/display-logic ^4.0, wedevelopnl/silverstripe-media-field ^6.0.0-rc3
Node >= 26 — only if you build the frontend bundle yourself; the package ships a compiled one

Optional:

silverstripe/reports — adds the Grid Elements and Shared Blocks reports to CMS Reports
tractorcow/silverstripe-fluent — multi-locale support, one isolated grid per locale (guide)

Conflict: this module conflicts with dnadesign/silverstripe-elemental and replaces its functionality. Coming from Elemental? See the migration guide.

Getting started

1. Install.

composer require wedevelopnl/silverstripe-grid

2. Choose a CSS framework adapter. SS_GRID_ADAPTER is required and has no default — an unset, empty, or invalid value throws when the container boots, which will also abort dev/build. Set it to a bundled preset (bootstrap, tailwind, or bulma, case-insensitive) or to the FQCN of your own adapter:

SS_GRID_ADAPTER="bootstrap"

3. Enable the editor on your page types.

# app/_config/grid.yml
Page:
  extensions:
    Grid: WeDevelop\Grid\Extensions\GridPageExtension

4. Render the grid in the page template.

<% loop $GridZone('main') %>$Me<% end_loop %>

5. Build the database.

vendor/bin/sake db:build --flush

That is a complete integration. Open a page in the CMS and the grid editor is on its Content tab.

From here, the two things most projects do next are adding their own content blocks and overriding the module's templates in their theme.

Documentation

The full map, with a line on what each document covers, is in docs/.

Start here

The grid editor — what the CMS editing experience looks like and what every control does

Building with it

Shared blocks — content maintained once and placed on many pages
Custom content elements — subclass ContentElement, add CMS fields and templates
Template integration — the holder chain, zones, theme overrides, extension hooks
Internationalization — translating strings, adding a locale, the PHP and JS collectors

Integrating

Migrating from Elemental / ElementalGrid — the BuildTask-based upgrade from SilverStripe 5
Fluent (multi-locale) — setup, copy/clear behaviour, and the locale-aware migration task

Architecture

Backend architecture — data model, API layer, services, validation
Grid Adapter System — writing an adapter for another CSS framework
Drag and Drop — the frontend dnd-kit integration and backend reorder pipeline

Contributing

Contributing guide — dev environment, tests, coverage, QA, and PR conventions
E2E fixture protocol — YAML schema, post-actions, dev fixture endpoint

Changelog

See CHANGELOG.md for release history.

License

BSD-3-Clause. See LICENSE.

Maintainers

WeDevelop — development@wedevelop.nl

wedevelopnl / silverstripe-grid

Maintainers

Package info

Statistics

Security

README

Why

The content model

Responsive layout, per column

Requirements

Getting started

Documentation

Changelog

License

Maintainers