README

Features

A modular approach to building pages in SilverStripe which allows model based page components.

Custom model based blocks
No limit to number of blocks
Easily block selection and editing
Use drag and drop GridField functionality to change and re-order blocks easily
Apply complex logic like forms to blocks
Versioning across blocks

Screen Shots

Block Selection

Installation

Add the following to your composer.json file and run /dev/buid?flush=all

{  
    "require": {  
        "cyber-duck/silverstripe-block-page": "4.0.*"
    }
}

Setup

Add Extension and Template Loop

The first step to adding block functionality is to apply the block page extension to your DataObject. This can be a normal DataObject or a Page.

Page:
  extensions:
    - BlockPageExtension

This will add a new tab to the CMS called content blocks. The second step is to apply the loop within your template for the blocks:

<% loop ContentBlocks %>
$Template
<% end_loop %>

Add Block Model and Template

The next step is to create a block. A block consists of 2 parts; a DataObject and a .ss template. Both these should have the same name.

EditorBlock.php
EditorBlock.ss

The model file can reside anywhere inside your code folder and should extend ContentBlock The base template for a block DataObject is as follows:

use CyberDuck\BlockPage\Model\ContentBlock;
use SilverStripe\Forms\HeaderField;
use SilverStripe\Forms\HTMLEditor\HTMLEditorField;

class EditorBlock extends ContentBlock
{
    private static $title = 'Editor';

    private static $description = 'Simple WYSIWYG editor block';
    
    private static $preview = '/themes/{YourTheme}/img/block/EditorBlock.png';

    private static $db = [
        'Content' => 'HTMLText'
    ];

    public function getCMSFields()
    {
        $fields = parent::getCMSFields();

        # HEADER - THIS FIELD IS REQUIRED
        $fields->insertBefore(HeaderField::create('BlockHeader', self::$title), 'Title')

        # FIELDS - YOUR FIELDS HERE
        $fields->addFieldToTab('Root.Main', HTMLEditorField::create('Content')); // example field

        return $fields;
    }
}

In the example above 1 custom block field is created called Content. You can replace this / add any other fields you want. There are 3 config properties used for a block used in the block selection screen:

$title - Block title
$description - Block description
$preview - Preview image for the block. You can point this to an image folder in your theme or similar. 360w x 150h.

Next in your theme folder create a folder at themes/{YourTheme}/templates/Block/ and add the EditorBlock.ss template within with the following content:

<div>
    $Content
</div>

Add Block YML Config

The final step to configuring your blocks is to set up the block YML config:

---
Name: block config
---
CyberDuck\BlockPage\Model\ContentBlock:
  blocks:
    - EditorBlock
  restrict:

Visit /dev/build?flush=all

Add Blocks in the CMS

Go the the CMS and visit your Page / Object editing screen and you will see a new tab called Content Blocks. Here you can create new blocks, edit blocks, and re-order blocks.

Extra Config

Restricting Blocks

You can restrict certain block selections to a particular page type by passing a restrict option

CyberDuck\BlockPage\Model\ContentBlock:
  blocks:
    - EditorBlock
    - HomeFeaturedBlock
  restrict:
    HomePage:
      - HomeFeaturedBlock

Creating a Block Holder Template

If you wish to wrap all blocks within a certain template you can create a ContentBlock_holder.ss template within the /Block/ folder.

<div id="block-$ID">
    $Template
</div>

The loop within your page needs to change slightly and call $TemplateHolder instead of template.

<% loop ContentBlocks %>
$TemplateHolder
<% end_loop %>

cyber-duck / silverstripe-block-page

Maintainers

Details