Skip to content

Latest commit

 

History

History
177 lines (123 loc) · 7.63 KB

blocks.md

File metadata and controls

177 lines (123 loc) · 7.63 KB
Raw

Creating Custom Blocks

🚩 Important: Advanced Custom Fields PRO is required to develop custom blocks in Hozokit.

Gutenberg has become the default editor for WordPress in favour of it's previous iteration where markup and text where mixed in a single text area input. Gutenberg relies on blocks and typically these would be written in React.

In this case ACF is used to register custom blocks using custom fields, removing the need to write them in React. ACF PRO is required to develop custom custom blocks.

Creating a custom block in Hozokit

To create a custom block, there are a few steps that need to be followed:

  1. Verify if the ACF PRO plugin is active.
  2. Register the block.
  3. Create markup files for the block.
  4. Add block as an ACF field.

We'll go through each step, along with example to create a custom block.

Verify if the ACF PRO plugin is active

The first step is to make sure ACF PRO is one of your active plugins. Navigate to WordPress' admin panel and select plugins on the left hand side menu.

Once plugins are listed, ACF PRO should be listed as well but if not please install it before moving to the next steps.

If installed, activate the plugin. Once activated it's ready to go.

Register the block

Each block must be registered in Hozokit in order to be made available in Gutenberg.

Open wp-content/themes/hozokit/plugins/blocks/blocks.php in your editor, this is the file where all custom blocks are described. In its current state, it should look similar to the following:

// A Hozokit function to used to render a block.
$render_callback = 'hozokit_block_render';

// The description of a block.
$example_block = array(
  'name'            => 'example-block',
  'key'	            => 'example-block',
  'title'           => __('Example'),
  'description'     => __("Renders an example block with text."),
  'render_callback' => $render_callback,
  'category'        => 'hozokit',
  'icon'            => 'admin-comments',
  'keywords'        => array( 'example', 'content' ),
);

// An array where all custom blocks are added to.
$blocks = array(
  $example_block,
  // more blocks here.
);

Let's go through each part of the file. The first element is $render_callback, this makes use of a Hozokit function (hozokit_block_render) which makes sure the block is setup, and looks for it's corresponding .twig template file in the correct place. More on this later. This line does not need to be changed.

Next there is a description of a block, each custom block is defined in an array and takes a few parameters. The ones descripted in $example-block are enough to start with but a list of accepted parameters are available in ACF's Documentation.

The key attribute is the one used to find the correct block .twig template to render its markup. For example, the key is set as example-block and the folder in templates/blocks needs to be named the same. e.g templates/blocks/example-block.

Finally, there is a $blocks array. All blocks described in this file need to be added to it. Adding them here will make sure ACF is aware of them.

Create markup files for the block

Part of the process of creating a custom block is writing the markup that will get rendered on the page where the block is included.

As mentioned in the previous section, the markup of a block will live inside templates/blocks/you-custom-block. To add markup to the registered example-block, a folder with the same name needs to be created in templates/blocks.

Hozokit will use the name of the key defined earlier for the block in blocks.php to find the correct template.

Inside the templates/blocks/example-block folder, two files should be created: an index.twig and an style.scss. One will house the markup whilst the other will be used for styling.

Styles get compiled into a single style.css file so it is reccommended that each block and component has its own class.

Let's have a look at each file, index.twig will include the html for the component, using Twig:

{% block example %}
  <section class="example">
    <h1>hozokit</h1>
    <p>An example component.</p>
  </section>
{% endblock %}

This markup could be moved into it's own component in components/example, one or multiple components can be included in the file and be interpolated with other tags in example-block's index.twig:

{# This markup will be rendered in the block. #}
<div class="hozokit-example-block">
  {% include 'example/index.twig' %}

  <div>
      <p>A call to action message.</p>
      {% include 'button/index.twig' %}
  </div>
</div>

In the example above the block was developed further to make use of components. An optional Twig block is available to create extra information when the component is previewed in Gutenberg (in the admin).

Add the preview block with the desired markup to a preview.twig file (located at /templates/blocks/example-block) in the block. A preview file is specific to a block and is not available to components.

{% block preview %}
  {% if is_preview %}
    <section>
      <p>This is an example preview of a block.</p>
    </section>
  {% endif %}
{% endblock %}

Then include the preview file in the block template (index.twig):

{# An optional preview file can be included, this will show on Gutenberg only. #}
{% include 'blocks/example-block/preview.twig' %}

{# This markup will be rendered in the block. #}
<div class="hozokit-example-block">
  {% include 'example/index.twig' %}

  <div>
      <p>A call to action message.</p>
      {% include 'button/index.twig' %}
  </div>
</div>

Finally styles for the block itself can be added to style.scss:

.hozokit-example-block {
  color: red;
}

Add block as an ACF field

The last step required for the block to be made available in Gutenberg is to create a custom field for the block.

In WordPress' Dashboard, navigate to Custom Fields, and add a new field group. The group may or may not have fields in it. However the Location (show this field group if) must be set to:

Block is equal to Example

The block will be listed under the Hozokit section in Gutenberg once the field group is published.

If the field group contains fields, these can be edited once a block is added in the Gutenberg editor.

The value can then be used in the block as needed with the fields associative array.

{{ fields.field_name }}
<div class="hozokit-example-block">
  {# Makes use of the text field part of the example block. #}
  <h2>{{ fields.text }}</h2>

  {% include 'example/index.twig' %}

  <div>
      <p>A call to action message.</p>
      {% include 'button/index.twig' %}
  </div>
</div>

Conclusion

These are the fundamentals to create custom blocks with Hozokit. Please reach out if there are further questions. Additionally, please feel free to submit a PR to extend this documentation.