A WordPress plugin for enhancing the editorial experience, including some common customizations for the Gutenberg editor.
The purpose of this plugin is to tailor the Gutenberg editor experience to be better suited to editors using their WordPress theme. Features added as a part of this plugin fall into two categories: block modifications (including new blocks and updates to core blocks) and editor plugins.
-
Image Block (replaces the core image block)
- Adds support for the
Alt TextandCreditattachment fields in the media library - Updates the default caption state to pull from the
Captionattachment field - Adds support for the custom Modal Gallery component in the main Editorial theme
- Removes unneeded features from core image block, including border styles
- Adds support for the
Note that you can continue to extend core block functionality in your theme by using WordPress's blocks.registerBlockType and editor.BlockEdit filters.
Our main Gutenberg "plugin" adds two panels to the main sidebar of posts: the Article Topper & Bylines panels.
The article topper panel controls article post metadata concerned with the article topper. This includes:
Topper type: The look and feel of the topper, be it text-only or a site-width featured imageNavigation theme: When paired with dark background image toppers, an already dark-themed nav can appear invisible. This option allows for lighter navigation themesOverline: Choose a primary category for your article to allow for better recirculation amongst common themes
The bylines panel allows editors to assign multiple authors to the author byline. This process starts with the Authors section under Posts, where you can create author profiles.
These authors also serve as taxonomies for your articles, so archive pages full of an author's own content are auto-generated on your behalf.
This plugin exposes a few functions that can be used to retrieve relevant values handled by the plugin. See the Theme API section for information about the available functions.
By default, all features of this plugin are enabled once the plugin is activated. However, you are able to configure the plugin's functionality (including disabling certain features) via a configuration file that can be added to your theme.
To set up a configuration file, add a ups-editorial.php file to your theme's root that returns an array containing the relevant configuration options:
<?php
/**
* Configuration for the ups-editorial plugin.
*/
return array(
'bylines' => true,
'article_topper' => true,
);Allowed types: boolean
Default value: true
Enable or disable the plugin's Author taxonomy, as well as the control mechanism for setting bylines for an individual post.
Allowed types: boolean
Default value: true
Enable or disable the registration of fields for article toppers and the Gutenberg panel that controls those fields.
There are a few globally-available functions that can be used by your theme to retrieve data defined by this plugin's functionality. These functions are defined in the Template.php file at the root of the plugin directory, and exist under the Upstatement\Editorial namespace.
It is recommended that your theme implement these functions wrapped by a function_exists check to prevent undefined errors in the case that the plugin is disabled. For example:
if ( function_exists( 'Upstatement\Editorial\get_post_bylines' ) ) {
$bylines = \Upstatement\Editorial\get_post_bylines();
...get_post_bylines( WP_Post $post = null, string $field = null) : array | nullRetrieve the byline for a post.
post
Post to retrieve authors for. Leave blank to use the current global post.
field
The field to return for each author. This can be any property from a WP_Term object. Leave blank to return the entire WP_Term object.
Returns an array consisting of author data. If field is blank, this will be an array of WP_Term objects. If a field is specific, this will be an array of values for that field.
get_post_overline( WP_Post $post = null ) : WP_Term | nullRetrieve the overline category for a post.
post
Post to retrieve the overline for. Leave blank to use the current global post.
Returns the WP_Term object of the category term identified as the overline, or null if none is set.
This is a known issue with Wordpress Gutenberg where post meta doesn't save until the Update button is pressed. We're currently tracking the main issue at WordPress/gutenberg#14900, but until then you can try one of the following steps:
-
After updating the sidebar content, press the
Updatebutton and then thePreviewbutton. -
Press the
Previewbutton twice. Sometimes the meta is only available for every-other preview. -
Attempt a hard refresh in the preview window (command+shift+R in Google Chrome).
When changing the saved markup of existing or new components, you are likely to come across an issue with block validation.
This error occurs when the markup of a block on last save doesn't match the markup of the block when it loads within the editor.
If this error was intentional, the easiest way to bypass the issue is:
-
In the top right corner of the block, press the three dots.
-
Select the
Attempt block recoveryoption. This will re-render the block markup according to the latest version of the save function. -
Updatethe post to save the latest block markup.
If the error was unintentional, your console will be the best place to identify what went wrong. That may look something like this:
Block validation: Block validation failed for `ups/image` Content generated by `save` function:
<figure class="wp-block-image">
<img src="/good-image.png" alt="A good image" />
<figcaption>This is the caption</figcaption>
<cite>This is a new citation</cite>
</figure>
Content retrieved from post body:
<figure class="wp-block-image">
<img src="/good-image.png" alt="A good image" />
<figcaption>This is the caption</figcaption>
</figure>In the case above, there was a new
citeelement added to the markup after the block was already saved to the post. At this point you can either (1) choose theAttempt block recoveryoption to update the markup, (2) remove and recreate the block, or (3) revert the save function to remove theciteelement.
The Github repository includes a docker setup that will allow you to run a basic WordPress installation with the Upstatement Editorial plugin installed. You'll need to ensure that you have Docker Desktop installed on your machine first.
To start working locally, you'll need the following things on your machine:
- nvm to manage the Node version this project is running on.
- composer to manage PHP dependencies and autoloading.
Once the above are installed, you can get set up with the following steps:
-
Ensure you're running the expected version of Node:
nvm install
-
Install Node dependencies:
npm install
-
Watch the plugin files for changes:
npm run start
-
Start the docker containers (note that the
-dflag will run the container in the background):docker-compose up -d --build
You can build the static front-end assets at any time with the following script:
npm run buildDuring the development of this plugin, we found the following resources to be useful: