Skip to content

Latest commit

 

History

History
217 lines (146 loc) · 8.33 KB

blocks.md

File metadata and controls

217 lines (146 loc) · 8.33 KB

Blocks

Blocks are small, reusable content patterns based on the Visual Framework. Blocks may appear within the Gutenberg editor, sidebar widgets, or rendered elsewhere in a template. Blocks added in the Gutenberg editor can be configured individually. See the individual README files for a detailed spec.

There are three types of blocks:

  1. Plugin Blocks
  2. ACF Blocks 2.1 ACF Blocks (JSON)
  3. React Blocks

Additional topics on this page:

Plugin Blocks

The VF-WP plugin defines a custom post type vf_block and a set of PHP classes. Individual blocks inherit the VF_Plugin class. Blocks registered this way have default metadata assigned to their respective posts. Block defaults can be configured under WP Admin > Content Hub > Blocks on a per-site basis.

Plugin block example

Plugin blocks are best suited for retrieving and caching HTML from the Content Hub. They allow for customizable API settings with per-site defaults. They can be enabled or disabled individually via their own WordPress plugin.

Available plugin blocks:

†1 The Example plugin block is used for development testing and should not be activated on live websites. †2 The Latest Posts plugin block was deprecated and replaced with an ACF block better suited for local WordPress content.

ACF Blocks

ACF blocks are registered for use in the Gutenberg editor using the Advanced Custom Fields plugin. Unlike plugin blocks, their default configuration cannot be defined on a per-site basis. They are defined using the VFWP_Block class.

ACF block example

ACF blocks are best suited for single instances of local content and easy development. They are located in the parent or child themes.

Available ACF blocks:

Block
Activity List Badge Banner Box
Button Card Details Divider
Embed Figure Hero Intro
Latest Posts Lede Links List Masthead
Page Header Profile Search Section Header
Social Icons Summary Tabs †3

ACF blocks from plugins:

†3 The Tabs ACF block was deprecated and replaced with a React block listed below.

External resources:

ACF Blocks (JSON)

WordPress 5.8 and ACF 6.0 support file based config via block.json. VF-WP blocks should prefer this format instead of the older PHP configuration.

See the debug test block for an example of configuration. The minimum JSON required is:

{
  "name": "vfwp-example",
  "title": "Example",
  "apiVersion": 3,
  "acf": {
    "mode": "preview"
  }
}

The default category is vf/wp. Other default values can be found in theme-block.php default_config method.

Standard block config options are available. For example to support inner blocks:

{
  "supports": {
    "jsx": true
  }
}

Additional VF-WP configuration options are:

{
  "vfwp": {
    "containerable": true,
    "iframeRender": false
  }
}

containerable - allow full-width layout (default: false)

iframeRender - render the block inside an iframe in the editor (default: true)

External resources:

React Blocks

React blocks are registered for use in the Gutenberg editor using JavaScript & React. They are provided by the VF Gutenberg plugin.

React block example

React blocks are best suited for advanced editor requirements that cannot be achieved using ACF blocks alone; block transforms, and managing multiple <InnerBlocks />, for example.

Available React blocks:

  • VF Cluster
  • VF Embed
  • VF EMBL Grid
  • VF Grid Column †4
  • VF Grid
  • VF Tabs Section †4
  • VF Tabs

Legacy React Blocks

Before ACF blocks were possible, the ACF blocks listed above were implemented as React blocks. Those older versions have since been deprecated but remain in the code to avoid breaking existing usage. They are hidden from the block inserter. They should be removed entirely in future following an audit. They used Nunjucks templates from the Visual Framework making them difficult to update.

†4 Restricted to their respective parent innner blocks.

Blocks in the Gutenberg Editor

ACF and plugin blocks in the Gutenberg editor use the acf/vfwp- and acf/vf- prefixes:

<!-- wp:acf/vf-members {"id":"block_5eb936165175f","name":"acf/vf-members"} /-->

The block id attribute must be unique per instance in the post content. When inserting blocks programmatically, generate a random ID using uniqid('block_') in PHP, or acf.uniqid('block_') in JavaScript.

Plugin blocks can be configured individually by adding the data and mode attributes with field_defaults set to 0.

For example:

<!-- wp:acf/vf-members {"id":"block_5eb937ea938af","name":"acf/vf-members","data":{"field_defaults":"0","field_vf_members_limit":"2","field_vf_members_order":"DESC","field_5ea988878eacf":"default","field_5ea983003e756":"0","field_vf_members_variation":"s"},"mode":"preview"} /-->

The JSON data format is used by ACF and plugin blocks to allow sever-side PHP templates. Those templates can be re-used outside of the Gutenberg editor. React blocks managed their own HTML and are only usable in the editor.

React blocks can be identified with the vf/ prefix:

<!-- wp:vf/members {"ver":"1.0.0"} /-->

These blocks are best configured using the Gutenberg front-end editor.

Blocks in Theme Templates

Plugin blocks can be hard-coded into theme templates:

$vf_members = VF_Plugin::get_plugin('vf_members');
if ($vf_members) {
  VF_Plugin::render($vf_members);
}

The block defaults from the related post metadata are be used.

It is possible to use ACF blocks in templates:

acf_render_block(array(
  'id'   => uniqid('block_'),
  'name' => 'acf/vfwp-box',
  'data' => array(
    /* ... */
  )
));

Although this method is not officially documented.

It is also possible to do:

get_template_part('blocks/vfwp-box/template');

However, the corresponding template would require additional logic to determine whether it is an ACF or template include.

For example:

$is_block = isset($block['id']);

It may be simpler to use two different templates.