NATIVE BLOCKS ARE IN A BETA PHASE.

Native blocks

Version 2.4.0 introduces a highly requested feature: custom blocks using WordPress core. Instead of relying on an additional plugin like Advanced Custom Fields or Metabox, users are now able to create blocks with custom fields using Blockstudio by itself.

Internally, Blockstudio native blocks are using Gutenberg components like TextControl or RangeControl for its fields, ensuring that users benefit from the constant updates made to the Gutenberg project.

block.json

Traditionally, Blockstudio blocks have been registered using file headers . While this approach allows for clean single block components, new block properties (added by WordPress) have to be added to the plugin manually.

By adopting the block.json standard of registering block types, native blocks will move together with WordPress core and support new features without requiring plugin updates.

Registering blocks via file headers for ACF and MB blocks will be supported for the foreseeable future.

Arrow Forward Circle

ACF is also preparing an upgrade to the common block.json standard. (which Blockstudio will support once it is stable)

Schema

To improve development with autocomplete and validation in your IDE, Blockstudio introduces its own schema:

View Blockstudio schema

blockstudio schema

The Blockstudio schema is an (always up-to-date) copy of the WordPress core block.json schema with two differences:

  • Attributes are removed (see how to register custom attributes for more information)
  • Additional blockstudio property that houses all plugin features like field schemas without interfering with potential future core properties

Registering blocks

Setup

Native blocks are registered like so:

Blockstudio\Build::init( [ 'dir' => get_template_directory() . '/native-blocks', 'type' => 'native' ] );

Files

To register native blocks, you will need two files in a given sub folder of the directory that was passed to the Build::init function.

  • block.json: the place where all your metadata about the block is stored.
  • index.php or index.twig: this file will be rendered inside the editor and on the frontend.
{ "$schema": "https://app.blockstudio.dev/schema", "apiVersion": 2, "name": "blockstudio/native", "title": "Native Block", "category": "text", "icon": "star-filled", "description": "Native Blockstudio block.", "keywords": [ "block", "native" ], "version": "1.0.0", "textdomain": "blockstudio", } <h1>My first native block.</h1>

And that's it! You've successfully created your first native block with Blockstudio. Please note that the id property needs to be unique.

Attributes

Of course, blocks without dynamic data are kinda boring! Attributes allow you to add data to your blocks and are comparable from custom fields that you know from solutions like ACF or Metabox.

Registering

Custom attributes are registered using the blockstudio property inside the block.json file.

{ "$schema": "https://app.blockstudio.dev/schema", "apiVersion": 2, "name": "blockstudio/native", "title": "Native Block", "category": "text", "icon": "star-filled", "description": "Native Blockstudio block.", "keywords": [ "block", "native" ], "version": "1.0.0", "textdomain": "blockstudio", "supports": { "align": true }, "blockstudio": { "attributes": [ { "id": "message", "type": "text", "label": "My message" } ] } }

And that's it! You've just registered your first custom attribute:

text field

Rendering

Inside template files, all attributes can be accessed using the $attibutes or $a variables and the respective ID of the field.

// index.php <h1><?php echo $attributes['message']; ?></h1> <h1><?php echo $a['message']; ?></h1> // index.twig <h1>{{ attributes.message }}</h1> <h1>{{ a.message }}</h1>

Attribute values render false if the field is empty or no option has been selected.

<?php if ($a['message']) : ?> <h1><?php echo $a['message']; ?></h1> <?php endif; ?>

Block attributes

The $attibutes or $a variables only give you access to data registered in the blockstudio property. To access information about standard block data like alignment or typography, simply use the $block or $b variables.

// index.php <h1>The block is aligned: <?php echo $block['align']; ?></h1> <h1>The block is aligned: <?php echo $b['align']; ?></h1> // index.twig <h1>The block is aligned: {{ block.align }}</h1> <h1>The block is aligned: {{ b.align }}</h1>

Field types

Group

group field

Group multiple fields in an (optionally) collapsible container.

Properties

title: string

opened: boolean

icon: string

initialOpen: boolean

attributes: array
Accepts all other field types besides another group.

Example

{ "blockstudio": { "attributes": [ { "id": "controls", "type": "group", "label": "My group", "attributes": [ { "id": "message", "type": "text", "label": "My message" } ] } ] } }

To access attributes inside groups, simply prepend the group ID to the inner attribute ID.

<h1><?php echo $attributes['group_message']; ?></h1> <h1><?php echo $a['group_message']; ?></h1>

Text

text field

Enter and edit a single line of text.

Properties

default: string

Textarea

textarea field

Enter and edit multiple lines of text.

Properties

default: string

rows: number

Number

number field

Enter and edit a number.

Properties

default: number

dragDirection: string

dragThreshold: number

hideHTMLArrows: boolean

isShiftStepEnabled: boolean

required: boolean

max: number

min: number

shiftStep: number

step: number

Range

range field

Set a numerical value between two points.

Properties

default: number

beforeIcon: string

afterIcon: string

allowReset: boolean

initialPosition: number

isShiftStepEnabled: boolean

marks: object (label: string, value: number)

max: number

min: number

railColor: string

resetFallbackValue: number

showTooltip: boolean

shiftStep: number

step: number

trackColor: string

withInputField: boolean

Toggle

toggle field

Toggle between a true or false value.

Properties

default: boolean

Checkbox

checkbox field

Choose one or multiple options from a set.

Properties

default: boolean

options: object (label: string, value: string)

Select

select field

Choose a single or multiple options from a dropdown list.

Properties

default: string

multiple: boolean

options: object (label: string, value: string, disabled: boolean)

Radio

radio field

Choose one option from a set.

Properties

default: string

options: object (label: string, value: string)

Combobox

combobox field

An enhanced dropdown list that also allows you to search for items.

Properties

default: string

options: object (label: string, value: string)

Color

color field

Choose a color and display a palette of colors.

Properties

default: string

options: object (name: string, value: string, slug: string)

clearable: boolean

disableCustomColors: boolean

Gradient

gradient field

Choose a gradient and display a palette of gradients.

Properties

default: string

options: object (name: string, value: string, slug: string)

clearable: boolean

disableCustomGradients: boolean