Block

Pagebuilding

Block

Automatic block registration & View rendering.

Introduction

These days Blocks are how you create content in WordPress.

A block is, simply put, an element you can use for your content anywhere on a WordPress site. A header, cover, menu, image and even a simple text segment are made up of blocks.

Missing features

There are a couple of things that we want to make easier for WordPress developers regarding blocks.

1. You have to manually register each block you have created. This leads to maintaining lists of blocks somewhere and adds another step to the process of creating blocks that could be automated.
2. We use Illuminate Blade as our templating engine and would love to have a seamless integration for this in our dynamic, also known as "server side rendered", blocks.

Our solution

To create a service that can find all blocks in a directory, parse additional PHP dependencies, allow for Views in the block.json file, register all blocks automatically and cache this work in production.

Getting Started

First off, make sure the module is installed and set up.

Next up, create a directory for your blocks.

Usually you would have your built blocks in /public/build/blocks/ and your raw blocks in /resources/blocks/.

If not, see Customizing paths.

Creating a new block

You can quickly scaffold a new block through the CLI!

wp artisan make:block <BlockName>

wp artisan make:block "My Block" --type=dynamic --description="My server-side rendered block"

Caching

You can cache all located blocks using wp artisan block:cache or as part of the wp artisan optimize command which is recommended in production. The cache file is /bootstrap/cache/block.php and can be deleted again using wp artisan block:clear

Dynamic Blocks with Views

To have a dynamic block server side render using Blade make sure the morningmedley/view package is installed first.

Then, add the view to block.json the same way you would a normal *.php template, but using viewRender instead of render like this:

block.json

{
  "$schema": "https://raw.githubusercontent.com/Morning-Train/Medley-Block/refs/heads/master/src/schemas/block.json",
  "apiVersion": 3,
  "name": "namespace/block",
  "editorScript": "file:./index.js",
  "render": "file:./render.php"
  "renderView": "template-name"
}

Here template-name refers to the blade template. So if you have a file called template-name.blade.php in your views folder this will be used.

tip

You may also use namespaces since renderView simply calls View::make with this name.

info

Notice the custom $schema url. This extends the WordPress block.json schema to include renderView.

Example Block View

/blocks/example-block/example-block.blade.php

<div {!! $blockProps !!}>
    <h1>{!! $attributes['title'] !!}</h1>
    {!! $content !!}
</div>

Within your template you will have the following variables available.

Variable name	Description
$attributes	An array containing all block attribute values.
$content	The data that save() produces.
$block	The current \WP_Block instance
$blockProps	The result of get_block_wrapper_attributes()

Adding PHP deps.

You can add a *.php file as a dependency for your block.

This is especially useful when you wish to View Compose a block.

block.json

{
  "$schema": "https://raw.githubusercontent.com/Morning-Train/Medley-Block/master/src/schemas/block.json",
  "apiVersion": 3,
  "name": "namespace/block",
  "editorScript": "file:./index.js",
  "renderView": "template-name",
  "phpScript": "file:./script.php"
  // This script is loaded whenever the block gets registered
  "viewPhpScript": "file:./view-script.php"
  // This script is loaded whenever the block gets registered on the frontend
  "editorPhpScript": "file:./editor-script.php"
  // This script is loaded whenever the block gets registered on an admin page OR during a REST call
}

View Composing

You can easily View Compose a block by adding a phpScript to it and compose there.

block.json

{
  "$schema": "https://raw.githubusercontent.com/Morning-Train/Medley-Block/master/src/schemas/block.json",
  "apiVersion": 3,
  "name": "namespace/block",
  "editorScript": "file:./index.js",
  "renderView": "template-name",
  "phpScript": "file:./script.php"
}

script.php

View::composer('template-name', function($view){
   $view->with('foo', 'bar');
});

tip

This also lets you compose with different data depending on frontend or admin.

This way you can use hardcoded dummy data in the editor and that way save some resources!

Advanced

Customizing paths

If your built blocks are located in a custom directory then you can set this through an environment variable BLOCK_COMPILED_PATH.

Otherwise, create a config file for blocks: config/block.php.

<?php return [
    'paths' => [
        resource_path("blocks"),
    ],
    'compiled' => env(
        'BLOCK_COMPILED_PATH',
        public_path("build/blocks"),
    ),
];

Registering blocks or paths at runtime

// Register a path containing multiple blocks
\MorningMedley\Facades\Block::registerBlocksPath(base_path('build/blocks'));
// Register a single block
\MorningMedley\Facades\Block::add(base_path('build/blocks/cover/block.json'));