WordPress.org

Templates Edit

A block template is defined as a list of block items. Such blocks can have predefined attributes, placeholder content, and be static or dynamic. Block templates allow to specify a default initial state for an editor session.

The scope of templates include:

  • Setting a default state dynamically on the client. (like defaultBlock)
  • Registered as a default for a given post type.

Planned additions:

  • Saved and assigned to pages as “page templates”.
  • Defined in a template.php file or pulled from a custom post type (wp_templates) that is site specific.
  • As the equivalent of the theme hierarchy.

API API

Templates can be declared in JS or in PHP as an array of blockTypes (block name and optional attributes).

const template = [
  [ 'block/name', {} ], // [ blockName, attributes ]
];
'template' => array(
    array( 'block/name' ),
),

Top ↑

Custom Post types Custom Post types

A custom post type can register its own template during registration:

function myplugin_register_book_post_type() {
    $args = array(
        'public' => true,
        'label'  => 'Books',
        'show_in_rest' => true,
        'template' => array(
            array( 'core/image', array(
                'align' => 'left',
            ) ),
            array( 'core/heading', array(
                'placeholder' => 'Add Author...',
            ) ),
            array( 'core/paragraph', array(
                'placeholder' => 'Add Description...',
            ) ),
        ),
    );
    register_post_type( 'book', $args );
}
add_action( 'init', 'myplugin_register_book_post_type' );

Locking Locking

Sometimes the intention might be to lock the template on the UI so that the blocks presented cannot be manipulated. This is achieved with a template_lock property.

'template_lock' => 'all', // or 'insert' to allow moving

Options:

  • all — prevents all operations.
  • insert — prevents inserting new blocks, but allows moving existing ones.

Top ↑

Existing Post Types Existing Post Types

It is also possible to assign a template to an existing post type like “posts” and “pages”:

function my_add_template_to_posts() {
    $post_type_object = get_post_type_object( 'post' );
    $post_type_object->template = array(
        array( 'core/paragraph', array(
            'placeholder' => 'Add Description...',
        ) ),
    );
    $post_type_object->template_lock = 'all';
}
add_action( 'init', 'my_add_template_to_posts' );

Top ↑

Nested Templates Nested Templates

Container blocks like the columns blocks also support templates. This is achieved by assigned a nested template to the block.

$template = array(
    array( 'core/paragraph', array(
        'placeholder' => 'Add a root-level paragraph',
    ) ),
    array( 'core/columns', array(), array(
        array( 'core/image', array( 'layout' => 'column-1' ) ),
        array( 'core/paragraph', array(
            'placeholder' => 'Add a inner paragraph',
            'layout' => 'column-2'
        ) ),
    ) )
);