0.2.0

What's new in Irving 0.2.0

This update includes major improvements to the way developers can build layouts for Irving sites using WordPress.

Introducing Irving Templates

WP-Irving now includes a new templating system that can be used to configure Irving layouts which automatically get injected with WordPress data. Templates are formatted as JSON files that define the structure of components that should be returned in default and page properties of a REST API response from the /irving/v1/components endpoint.

Ex: Template for defining the default page layout structure

{
    "defaults": [
        { "name": "template-parts/header" },
        { "name": "irving/body-wrapper" },
        { "name": "template-parts/footer" }
    ]
}

Ex: Template for a post page layout (i.e., single.json):

{
    "page": [
        {
            "name": "irving/body-wrapper",
            "children": [
                {
                    "name": "irving/post-title",
                    "theme": "heading",
                    "config": {
                        "tag": "h1"
                    }
                },
                { "name": "irving/post-featured-media" },
                { "name": "irving/post-byline" },
                { "name": "irving/post-timestamp" },
                { "name": "irving/post-content" }        
            ]
        }
    ]
}

Template hierarchy

Irving now automatically loads templates based on the site URL, using the template hierarchy familiar in traditional WordPress theme development. By default, WP-Irving will try to load template files from the current theme's templates directory. For example, a request for a post page would use a /templates/single.json file, if present. An archive page would load /templates/archive.json, etc.

Additionally, WP-Irving includes support for a special default.json template for defining components that should only be loaded on full page renders and don't change when navigating between pages.

The location where WP-Irving loads templates from can be filtered using the wp_irving_template_path hook,

Ex: Loading templates from a custom path.

add_filter(
	'wp_irving_template_path',
	get_stylesheet_directory() . '/my/custom/template/path'
);

Template parts

To make it easy to create repeatable template patterns, WP-Irving will automatically replace any objects in a template file named with a template-parts/{name} pattern with data in a name.json file in the theme's template-parts directory.

The location where template parts are loaded from can be filtered using the wp_irving_template_part_path hook.

Ex: Loading template parts from a custom path.

add_filter(
	'wp_irving_template_part_path', 
	get_stylesheet_directory() . '/my/custom/template-part/path'
);

Core component types

To aid in quickly creating layouts, the WP-Irving plugin now includes a set of registered component types, which can used in template files, that automatically pull in data from WordPress so you don't have to write a lot of back-end code to get your templates up and running. The full list of available component types can be found here: https://github.com/alleyinteractive/wp-irving/tree/master/inc/components/components.

Register custom component types

In addition to the core components, projects can create and register their own component types using the WP_Irving\Components\register_components() function.

Ex:

<?php
/**
 * Example component registration.
 */

WP_Irving\Components\register_component(
	'namespace/example-component',
	[
		// Define default configuration schema for the component.
		'config'            => [
			'property' => [
				'type'    => 'bool',
				'default' => false,
			],
		],
		'config_callback'   => function ( $config ) {

			/*
			 * Add custom logic that hydrates the component's 
			 * configuration properties with WP data.
			 */

			return $config;
		},
		'children_callback' => function ( $children, $config ) {

			/*
			 * Add custom logic that modifies the component's
			 * children array based on configuration properties.
			 */

			return $children;
		},
	]
);

You can also register components using the WP_Irving\Components\register_component_from_config() function and pass a path to a JSON file defining the component's schema (see examples of registering from JSON schema in the core components library).

Admin bar

This release includes support for the WP admin bar out of the box and includes helpful tools to clear cache from the admin bar. (#168, #203)