Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/helick/blocks
Easily create Gutenberg blocks with Carbon Fields
https://github.com/helick/blocks
composer wordpress wordpress-plugin
Last synced: 2 days ago
JSON representation
Easily create Gutenberg blocks with Carbon Fields
- Host: GitHub
- URL: https://github.com/helick/blocks
- Owner: helick
- License: mit
- Created: 2019-06-19T17:51:47.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2019-11-26T20:56:28.000Z (almost 5 years ago)
- Last Synced: 2024-08-20T15:26:28.121Z (3 months ago)
- Topics: composer, wordpress, wordpress-plugin
- Language: PHP
- Homepage:
- Size: 48.8 KB
- Stars: 6
- Watchers: 1
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Helick Block
[![Latest Version on Packagist][ico-version]][link-packagist]
[![Total Downloads][ico-downloads]][link-downloads]
[![Software License][ico-license]](LICENSE.md)
[![Quality Score][ico-code-quality]][link-code-quality]
The package assists you in easily creating Gutenberg blocks with Carbon Fields.
## Requirements
Make sure all dependencies have been installed before moving on:
* [PHP](http://php.net/manual/en/install.php) >= 7.1
* [Composer](https://getcomposer.org/download/)
* [Carbon Fields](https://docs.carbonfields.net/#/quickstart) >= 3.0
## Install
Install via Composer:
``` bash
$ composer require helick/blocks
```
## Usage
Within your theme declare your block, attach its fields, and provide data for your template:
``` php
use Carbon_Fields\Field;
use Helick\Blocks\Block;
use WP_Query;
final class ExampleBlock extends Block
{
/**
* The block's display name.
*
* @var string
*/
protected $name = 'Example';
/**
* The block's description.
*
* @var string
*/
protected $description = 'This is an example block';
/**
* The block's template.
*
* @var string|string[]
*/
protected $template = 'partials/blocks/example.php';
/**
* Fields to be attached to the block.
*
* @return array
*/
public function fields(): array
{
return [
Field::make('text', 'heading', 'Heading'),
Field::make('image', 'image', 'Image'),
Field::make('rich_text', 'content', 'Content'),
Field::make('association', 'associations', 'Associations')
->set_types([
[
'type' => 'post',
'post_type' => 'post',
]
])
];
}
/**
* Data to be passed to the rendered block.
*
* @param array $fields
*
* @return array
*/
public function with(array $fields): array
{
return [
'associations' => $this->queryAssociations($fields['associations'])
];
}
/**
* Query the associations.
*
* @param array $associations
*
* @return WP_Query
*/
private function queryAssociations(array $associations): WP_Query
{
$associationIds = array_column($associations, 'id');
$associationIds = array_map('intval', $associationIds);
return new WP_Query([
'no_found_rows' => true,
'post__in' => $associationIds,
'orderby' => 'post__in',
]);
}
}
```
Create your block template:
``` php
= esc_html($fields['heading']) ?>
= wp_get_attachment_image($fields['image'], 'full') ?>
= apply_filters('the_content', $fields['content']) ?>
have_posts()) : ?>
```
Finally, register your block in theme's `functions.php`:
``` php
ExampleBlock::boot();
```
## Caching
The easiest and probably the best method is to cache the **complete HTML output**, and PHP's output buffering functions will help us implement that without moving too much code around:
``` php
use Carbon_Fields\Field;
use Helick\Blocks\Block;
use Exception;
final class ExampleBlock extends Block
{
// Your block declaration goes in here ...
/**
* Render the block.
*
* @param array $fields
* @param array $attributes
* @param array $blocks
*
* @return void
*
* @throws Exception
*/
public function render(array $fields, array $attributes, array $blocks): void
{
// Compose the render arguments
$args = compact('fields', 'attributes', 'blocks');
// Generate cache key based on the given arguments
$cacheKey = sprintf('example_block_%s', hash('md5', wp_json_encode($args)));
$cacheGroup = 'blocks';
// Check whether we have the block's cached output
$output = wp_cache_get($cacheKey, $cacheGroup);
// If nothing is found, catch the block render output
if (false === $output) {
ob_start();
try {
parent::render($fields, $attributes, $blocks);
} catch (Exception $e) {
// In case something goes wrong we clear the output buffer
ob_end_clean();
// Re-throw an exception so we don't cache the actual error output
throw $e;
}
$output = ob_get_clean();
// Cache the block's output for 5 minutes (300 secs)
wp_cache_set($cacheKey, $output, $cacheGroup, 5 * MINUTE_IN_SECONDS);
}
echo $output;
echo "";
}
}
```
With this way we're only storing the actual output in our cache, no posts, no metadata, no terms. Just the HTML.
You can also inspect your cache by using [WP CLI](https://wp-cli.org/):
``` bash
# Get the block's output from the object cache
$ wp cache get example_block_098f6bcd4621d373cade4e832627b4f6 blocks
...your block's output...
# Remove the block's output from the object cache
$ wp cache delete example_block_098f6bcd4621d373cade4e832627b4f6 blocks
Success: Object deleted.
```
## Contributing
Please see [CONTRIBUTING](CONTRIBUTING.md) and [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md) for details.
## Security
If you discover any security related issues, please email [email protected] instead of using the issue tracker.
## Credits
- [Evgenii Nasyrov][link-author]
- [All Contributors][link-contributors]
## License
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.
[ico-version]: https://img.shields.io/packagist/v/helick/blocks.svg?style=flat-square
[ico-license]: https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square
[ico-code-quality]: https://img.shields.io/scrutinizer/g/helick/blocks.svg?style=flat-square
[ico-downloads]: https://img.shields.io/packagist/dt/helick/blocks.svg?style=flat-square
[link-packagist]: https://packagist.org/packages/helick/blocks
[link-code-quality]: https://scrutinizer-ci.com/g/helick/blocks
[link-downloads]: https://packagist.org/packages/helick/blocks
[link-author]: https://github.com/nasyrov
[link-contributors]: ../../contributors