A plugin to list and preview components from the active theme's component library in the WordPress admin. Also provides helper functions for loading components in your theme so you can build with components atomically, similar to how you can work with components in React.
This plugin will add a new area to the WordPress admin called
"Component Library." By default, this area will be accessible to anyone with
the manage_options
capability, but this is filterable.
Upon visiting the Component Library page, any components configured in the
active theme's components
folder within the root of the theme according to
the standards laid out below will be displayed with information from the
README and one or more live previews based on values in the examples
key in
the component.json
file in the component folder.
In order for this plugin to pick up and display your components, you need to establish the following directory structure:
- wp-content
- themes
- {theme-name}
- components
- {group name} (optional)
- {component-name}
- component.json - A JSON file containing a title for the component, props for the component, and example data for admin previews. See below for more info.
- README.md - An explanation of what the component is, what props it accepts, and how it should be used.
- style.scss - Optional. A stylesheet that defines styles for the component. See the Loading Styles section below for more info.
- template.php - The file that renders the component.
- {group name} (optional)
- components
- {theme-name}
- themes
For examples, look in the components directory.
A JSON file with three top-level keys: examples
, props
, and title
.
An array of objects, each of which should have a title
property that defines
the title for the example in the admin, and a props
property that contains
an object with key/value pairs for prop values.
An array of objects defining props for the component, the spec for which is as follows:
Property | Default | Required | Type | Description |
---|---|---|---|---|
allowed_values | [] | No | array | If the type is set to enum , the list of allowed values. |
default | '' | No | string | The default value to use if none is provided in component props. |
description | Yes | string | The description of the component to display in the admin. | |
required | false | No | bool | Whether a value for the prop is required or not. |
type | 'string' | No | string | The prop type. Possible values are 'array', 'bool', 'enum', 'number', 'object', 'string'. |
A string that names the component when it is viewed in the admin. For example, "Button."
Titles may include subgroups separated by a /
, for example, "Elements/Button". This will organize the display of components in the component viewer by those subgroups.
All supported core blocks include a raw
prop that you can include into your component.json
file if you would like to extend the functionality of the block within your theme/plugin utilizing the block's original attributes.
Many of the core blocks implicity pass their HTML attributes as potential props that can be utlized by a component, but aren't explicitly defined in the examples. This is to provide support for updates within WordPress that may introduce new functionality in the future.
Only props that are explicitly declared in your component.json
file will be passed to template.php
. You can add a temporary logging statement to the wpcl_component()
function to debug potential props.
Potential enchancement: expose this information 👆️ if a constant is declared similar to WP_DEBUG.
An example component.json
can be found in
tests/components/button/component.json.
The file that describes your component. The examples and props sections of the
documentation will be dynamically compiled from the definitions in
component.json
, but the README will be used for a long description of what
the component is used for.
An example README.md
can be found in
tests/components/button/README.md.
A stylesheet that contains styles that are scoped to the component. Whether and how you work with these stylesheets is up to you, as they will need to be integrated into your theme's asset builder. However, globbing them using node-sass-glob-importer is a good idea, as it will allow you to create styles for new components simply by adding a stylesheet to a directory rather than needing to import the stylesheet into an index file.
An example style.scss
can be found in
tests/components/button/style.scss.
The template file behaves like a normal template file called by
get_template_part
. It has access to all of the same variables. However, the
props system will enforce props rules and set default values for you, so the
$args
variable that contains the arguments for the template is a little
smarter than the WordPress default.
An example template.php
can be found in
tests/components/button/template.php.
This plugin contains a number of helpful functions for use in writing WordPress templates using components that you define according to the specs above.
The primary function used for working with components. Accepts two arguments: a component name and an optional array of props. Loads and outputs the component's template file after getting values for all props, either from what was provided in the props array, or using default values for each prop.
wpcl_component( 'button', [ 'href' => 'https://www.example.org', 'text' => 'Visit example.org' ] );
Accepts an array of key/value pairs to set as attributes on an HTML element
and safely outputs them. Optionally, you can pass the $args
variable as the
second parameter and the function will intelligently merge props with default
values. It is recommended to use this approach for attributes on the root
element of a component to enable support for setting the id
and class
props.
The class
attribute accepts either a normal string of classes, or an array of
arguments in the same fashion as the
classnames npm package.
This is useful for applying multiple classes, conditional classes, derived
classes, and merging a set of classes with class names that may have been passed
to a component via props.
<a
<?php
wpcl_attributes(
[
'class' => [ 'class-1', [ 'class-2', 'class-3' ], [ 'class-4' => $maybe_include ] ],
'href' => 'https://www.example.org/',
],
$args
);
?>
>
Safely converts a markdown string to HTML and outputs it.
wpcl_markdown( '## This will become an h2' );
Attempts to render core/*
blocks using components defined in the theme. If no component
is found, then the block's normal renderer is used instead.
You can also call this function recursively if your block contains innerBlocks
that you would also like to handle.
// single.php or in The Loop™. Defaults to blocks from post_content
wpcl_blocks();
// Or call it anywhere, passing in block definitions from a function like parse_blocks()
wpcl_blocks( $blocks );
If you are using styles that are scoped to your components (e.g., a style.scss
file in each component directory) you will need to make sure that you are
running a build of those component styles that is loaded in the admin via the
admin_enqueue_scripts
hook so the styles are previewable in the admin view.
The admin views for this plugin are produced using components built using this
plugin, which allows us to "eat our own dog food," or use the plugin to develop
the plugin. In order to switch the behavior of the plugin from previewing
components in the active theme to previewing the components that are used in
this plugin, simply append &dogfooding=1
to the admin URL for the components
view.