PHPackages                             toastnz/blocks-layouts - 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. [Utility & Helpers](/categories/utility)
4. /
5. toastnz/blocks-layouts

ActiveSilverstripe-vendormodule[Utility & Helpers](/categories/utility)

toastnz/blocks-layouts
======================

Silverstripe content blocks module

6.1.10(4d ago)08.6k↑135.7%BSD-3-ClausePHPPHP >=8.3

Since Aug 25Pushed 4d ago3 watchersCompare

[ Source](https://github.com/toastnz/blocks-layouts)[ Packagist](https://packagist.org/packages/toastnz/blocks-layouts)[ RSS](/packages/toastnz-blocks-layouts/feed)WikiDiscussions m6 Synced 2d ago

READMEChangelog (10)Dependencies (24)Versions (74)Used By (0)

SilverStripe Blocks
===================

[](#silverstripe-blocks)

Simple content blocks system. Nothing fancy, easy to implement.

Requirements
------------

[](#requirements)

See composer.json

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

[](#installation)

Add the following to your `config.yml` (optional):

```
PageController:
  extensions:
    - Toast\Blocks\Extensions\PageControllerExtension
```

Use `Page` or other class that extends `SiteTree`.

In your `Layout/Page.ss` template, add the following:

```

    $ForTemplate

```

Configuration
-------------

[](#configuration)

### Add / remove available block classes

[](#add--remove-available-block-classes)

```
Toast\Blocks\Extensions\PageExtension:
  available_blocks:
    - Toast\Blocks\TextBlock
```

### Position page template content between blocks

[](#position-page-template-content-between-blocks)

```
Your\Page\Class:
  extensions:
    - Toast\Blocks\Extensions\PageContentBlockPageExtension
```

```

        {$ForTemplate}

```

### Add / remove available alternate block layouts

[](#add--remove-available-alternate-block-layouts)

"layout\_src": directory that holds folders of different layouts with .ss templates "layout\_icon\_src": directory that holds all the layout icons "layout\_dist\_dir": specificed the css for block layouts

CSS file will only be included with the syntax of 'theme/themename/dist/styles/$LayoutName-$BlockType.css"

```
Toast\Blocks\Extensions\PageExtension:
  layout_src: 'app/templates/Toast/Blocks'
  layout_icon_src: 'app/client/images/layout-icons'
  layout_dist_dir: 'theme/themename/dist/styles'
```

Ensure there are at least one CustomBlock.ss and 'customblock.svg' icon in each of the specified directory. Layout will be available for all subsites.

### .ss template naming

[](#ss-template-naming)

You may have multiple layouts, please ensure you have the block.ss created under a new layout folder in the src directory. e.g. 'app/templates/Toast/Blocks/**CustomLayoutNameOne**/ImageBlock.ss' or 'app/templates/Toast/Blocks/**CustomLayoutNameTwo**/ImageBlock.ss'

### Layout icon naming:

[](#layout-icon-naming)

Please ensure the layout icon are named after the block name are all in lowercase, e.g. customblock.svg. e.g. 'app/client/images/layout-icons/**customlayoutone**/customblock.svg' or 'app/templates/Toast/Blocks/**customlayouttwo**/customblock.svg'

### Icon extensions

[](#icon-extensions)

Allowed extension: 'jpg', 'jpeg', 'png', 'gif', 'bmp', 'svg'

### Per-layout configuration (labels, icons, disabling)

[](#per-layout-configuration-labels-icons-disabling)

Use `layout_config` on any block class to customise the label or icon shown in the CMS layout picker, or to disable a layout entirely. Keys are short layout folder names (e.g. `Default`, `Split`).

View the available icon classes here: `client/fonts/layout-icons/font/preview.html`

```
Toast\Blocks\TextBlock:
  layout_config:
    Default:
      label: 'Default'
      layout_icon_path: '[resources]/app/client/images/layout-icons/default/textblock.svg'
    Split:
      label: 'Split'
      layout_icon_class: 'layout-icons-text-columns'
      disabled: true
```

Supported keys per layout entry:

KeyTypeDescription`label`stringDisplay label shown beneath the icon in the CMS picker`layout_icon_path`stringPath to an SVG file. Supports the `[resources]` token. Highest priority.`layout_icon_class`stringCSS class for an icon font or sprite. Overrides directory discovery.`disabled`boolSet `true` to hide this layout from the CMS picker**Icon resolution priority:** `layout_icon_path` → `layout_icon_class` → auto-discovered SVG from `layout_icon_src` directory.

> Full class-name keys (e.g. `Toast\Blocks\Default\TextBlock`) are still supported for backward compatibility.

### Excluding layouts

[](#excluding-layouts)

Use `exclude_layouts` alongside `layout_config` to hide one or more layouts from the picker without specifying full config entries. This is the quickest way to remove a layout.

```
Toast\Blocks\MediaTextBlock:
  exclude_layouts:
    - ShortRounded
```

**Precedence rules:**

- `layout_config..disabled: true` takes precedence over `exclude_layouts`.
- `exclude_layouts` only hides layouts from the CMS picker — the `.ss` template file must still exist for the block to render correctly if a record already holds that layout value.
- YAML cannot create layouts. A `.ss` template file must exist for a layout to appear.

### Fallback when a saved layout is removed

[](#fallback-when-a-saved-layout-is-removed)

If a block record has a previously saved layout that is later excluded or disabled, the block will automatically fall back to the `Default` layout at render time and on next save. If `Default` is also unavailable, the first available layout is used instead.

When a content editor opens such a block in the CMS, a warning notice will appear above the layout picker advising them that the previous layout is no longer available and prompting them to select a replacement and save.

### Create a custom block

[](#create-a-custom-block)

Extend `Block` to create a new block type.

```