hex-digital / sage-blade-block-renderer
Generate blade partials to render native gutenberg blocks with Sage 10
Fund package maintenance!
jamiewarb
Installs: 2 188
Dependents: 0
Suggesters: 0
Security: 0
Stars: 5
Watchers: 3
Forks: 0
Open Issues: 0
Type:package
Requires
- php: ^7.3|^8.0
Requires (Dev)
README
The Blade Block Renderer for Sage allows the easy registration of blade partials for the render function
of native Gutenberg blocks.
Useful when you want to edit a block in React, but render with Blade.
Features
- 🔥 Use all your blade components and PHP functions immediately in your native Gutenberg blocks.
- 🔥 Instantly generate a working render_callback, powered by Blade with a native Sage 10 feel for passing view data.
- 🔥 All blocks support
InnerBlocks
content
Requirements
- Sage >= 10.0
Installation
Install via Composer:
$ composer require hex-digital/sage-blade-block-renderer
Usage
Create your native block
Create your Gutenberg block as you normally would, with one small change.
Instead of adding HTML to the save
function of your block, instead define it as one of the following:
// If you have InnerBlocks content: save: function (props) { return <InnerBlocks.Content/>; } // If there is no InnerBlocks content: save: function() { return null; }
And that's it! When your block is saved, Gutenberg will save the settings to the database. When it comes time to render your block, the settings will be given to the Blade Block Renderer, and your blade template will be used, along with any attributes, classNames or Inner Blocks given.
If you prefer to use Blade for both the edit
and save
HTML, you would benefit from using
Log1x's ACF Composer package instead. This similarly
provides Blade support for blocks, but utilises ACF's Blocks instead, which will be much more powerful.
Rendering a Block with a blade-powered render callback
To create your first rendered block, start by running the following generator command from your theme directory:
$ wp acorn blade-block Example
This will create app/BladeBlocks/Example.php
which is where you will create and manage your first blade block:
<?php namespace Example; use BladeBlock\BladeBlock; class Example extends BladeBlock { /** * The block slug. Should match the slug given to your registered block. * * @var string */ public $slug = 'example'; /** * Data to be passed to the block before rendering. * * @param BladeBlock $block * @return array */ public function with($block) { return [ 'data' => 'dummy data', ]; } }
You'll see it has a familiar with()
function for passing data to your block. However,
it is also given the block object as the first parameter.
This allows you to get any attribute, setting or content from the block, as required.
For example, $block->content
will give the Inner Blocks content, and $block->image_id
would give
the value of an attribute called image_id
that was defined on the block in JavaScript.
A View
is also generated in the resources/views/blocks
directory:
<div class="{{ $block->classes }}"> @if ($data) <p>{!! $data !!} @else <p>No data found!</p> @endif @if ($content) {!! $content !!} @endif </div>
The $content
variable will contain the HTML for any InnerBlocks added in the editor.
The $blockClass
variable will contain the base class for the block, for use with BEM class naming.
This is in the form "wp-block-$prefix-$slug"
E.G. wp-block-hex-page-header
.
These can then be outputted as required into the blade partial.
All block data is available on the $block
object, which is the same as that passed to the
BladeBlock with()
function. All data returned from the with()
function is also available.
Block Preview View
In the view file, you can use $block->preview
for conditionally modifying your block when shown in the editor.
You can also load a different blade partial by duplicating your existing view and prefixing it with preview-
(e.g. preview-example.blade.php
).
However, if you're using the blade partial for both the edit
and save
HTML, you would benefit from using
Log1x's ACF Composer package instead. This similarly
provides Blade support for blocks, but utilises ACF's Blocks instead, which will be much more powerful.
Modifying your Block
Your Block has a few options available to it to modify. Add these as member variables to your generated block class to define and use them.
Your block's class will default to "wp-block-$prefix-$slug"
, where the prefix has the trailing slash trimmed.
This block class is available in the view as $blockClass
for easy use with BEM class naming.
/** * The block prefix. Should match the prefix given to your block * * @var string */ public $prefix = 'hex/'; /** * The block slug. Should match the slug given to your registered block. * * @var string */ public $slug = ''; /** * The block view. Same format as given to the blade `include()` function. A dot-separated path where the root is `resources/views`. * If left blank, defaults to `'blocks.' . $this->slug`. * * @var string */ public $view;
Bug Reports
If you discover a bug in Sage Blade Block Renderer, please open an issue.
Contributing
Contributing, whether through PRs, reporting an issue, or suggesting an idea, is encouraged and extremely appreciated.
License
We provide the Sage Blade Block Renderer under the MIT License.