Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/kellymears/BlockCompose
View composer and attribute builder for Sage 10 and WordPress' Project Gutenberg editor.
https://github.com/kellymears/BlockCompose
Last synced: 3 months ago
JSON representation
View composer and attribute builder for Sage 10 and WordPress' Project Gutenberg editor.
- Host: GitHub
- URL: https://github.com/kellymears/BlockCompose
- Owner: kellymears
- Created: 2019-05-05T21:44:14.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2019-05-21T18:30:37.000Z (over 5 years ago)
- Last Synced: 2024-07-31T02:34:10.401Z (3 months ago)
- Language: PHP
- Homepage:
- Size: 63.5 KB
- Stars: 17
- Watchers: 5
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# BlockCompose
View composer and attribute builder for Sage 10 and WordPress' Project Gutenberg editor.
## Get Shit Done Again
Crying in the shower about how the first half of 2019 has gone? Well dry off, pump some jams and maybe throw a couple darts at your Mullenwag dartboard. Because it's time to feel _fluent_ again.
## Installation
- `composer require tiny-pixel/block-compose`
- Scaffolding: `app/Blocks` and `config/editor.php`.
### Configuration
For the time being the config file for the Block Compose library needs to be copied manually to `config/editor.php`.
The usage of this file is very straightforward and is commented in a Laravel style.
### Writing a Block View Composer
Minimally, a block view composer contains `name`, `editor_script` and `view` parameters accompanied by an `attributes` method.
```php
namespace App\Blocks;
use \TinyPixel\BlockCompose\Composer;
class Starter extends Composer
{
public $name = 'starter'; // block name
public $editor_script = 'sage/starter'; // registered script
public $view = 'blocks.starter'; // associate view
}
```
### View
Block attributes are made available in the view in this format: `$block->attributes->attribute_name`.
```php
@if(isset($block->attributes->mediaURL))
@endif
{!! $block->attributes->heading !!}
{!! $block->attributes->copy !!}
```
If you utilize `` in your custom blocktype in order to compose with nested blocks, that content is automatically pulled from the block data by the BlockComposer class and made accessible via `$block->content` in your view.
### The script
You are not required to write a `save()` method in your `registerBlockType()` script, with one exception: if you use InnerBlocks you must register a `save()` handle. It does not need to return anything substantive but I've found it requires at least one element to wrap it. This should suffice:
```js
// ...,
save: () => { return
}
```
Otherwise, this is a sufficient and functional example:
```js
import { __ } from '@wordpress/i18n'
import { registerBlockType } from '@wordpress/blocks'
import { RichText } from '@wordpress/editor'
registerBlockType('sage/card', {
title: __('Card', 'sage'),
icon: 'wordpress',
category: 'common',
attributes: {
heading: {
type: 'string',
},
copy: {
type: 'string',
},
},
edit: ({ className, setAttributes, attributes }) => {
return (
{ setAttributes({ copy: value }) }} />
)
},
save: () => { return null },
})
```
Honestly, not writing that save handler makes _a world of difference_. The vast majority of that is actually just HTML, really.
### Advanced Composition
You can utilize three optional methods to handle parsing your block data, block markup and view variable templating:
`with` allows for the modification of data directly before it is compiled with Blade
`withData` allows for the modification of the block source. Note that the block source is automatically inserted as a block attribute by BlockCompose (available as `$block->attributes->source` so there may not be much utility here for the time being.
```php
namespace App\Blocks;
use \TinyPixel\BlockCompose\Composer;
use \TinyPixel\BlockCompose\Traits\Compose;
class Card extends Composer
{
use Compose;
// ...
/**
* Manipulate view data
*
* @return array associative
*/
public function with($data)
{
return $data;
}
/**
* Manipulate source block data
*/
public function withData($block, $source)
{
return $block;
}
}
```
## Thanks for checking out the repo!
If you want to contribute that's totally awesome. Please be considerate in your PRs and issues. More important than anything else is that this repository remains a welcoming space for everyone to learn from, contribute to and utilize as a resource.
I hope this makes it easier for you to get rolling with the editor in a productive way. It's still not as fast as using something like, say, Advanced Custom Fields. But if you want to build with the editor directly that opens up a lot of really cool possibilities for you, your clients and the developer ecosystem.
If you use this work to make something cool or lucrative please let me know! I love that kind of stuff.
**MIT License.**
**© 2019 Kelly Mears**