[ADR-0003] WYSIWYG Blocks Architecture
Turn P4 Blocks into WYSIWYG blocks.
Last updated
Turn P4 Blocks into WYSIWYG blocks.
Last updated
Status: accepted
Deciders: Development & Design teams
Many blocks look broken in the editor. The editing experience was just ported from the old Shortcake blocks but it's not consistent with the native WP editing experience, which is made of WYSIWYG blocks.
Turn P4 Blocks into WYSIWYG blocks:
Port the Twig template into its JSX equivalent. Try to simplify the templates as much as possible in the process.
Deliver React in the frontend site and use it to render the blocks.
Turn the LayoutSelector component options into for each block
Use the RichText component where possible for in-place editing.
We decided to include React in the Frontend in order to render the blocks. This avoids having duplicate template logic, otherwise we would have a JSX version of the block for the editor, and a Twig template for the frontend.
The save() method is a client-side method expected to output static content, which is persisted as the block's content in the database. The usual way of rendering a dynamic block in Gutenberg is returning null in the block's function, then using the component and render_callback() when in the PHP side. This is the way our blocks are currently rendered, thus it's the method we are deprecating in favor of the React approach.
As any changes in the block's save() method would trigger a in the block editor, we first needed to add a deprecated property to the block, to let WP know that we are OK with our block changing from null to something else.
To accomplish this, we created two components: frontendRendered and FrontendBlockNode.
is meant to replace the save() function in a block definition.
It returns a function with the same parameters as the save() function, so it takes two arguments: attributes and className.
So Wordpress will only render that div with its attributes in the frontend site, then it's our job to make React render something inside of it.
A WYSIWYG ("What You See Is What You Get") block is a block you can edit directly in place, in the preview mode.
The way to think about WYSIWYG controls is starting from the final result, for example, this is a Counter block:
To make it editable in-place, as it is, Wordpress provides two basic ways:
Making some texts editable by clicking on them (e.g.: title, caption)
Moving options to the sidebar, specially for any controls that are pure configuration and not visible, for example: progress bar vs dial styles, an API url, or the tags for an Articles block, etc.
This is pretty much the way native WP blocks work, the basic principle is: there should be nothing in the editor side that is not rendered in the frontend. No noise.
So how do we clean our UI to the point that there is nothing but the block itself (currently the "Preview")?
What style of counter do you need?
There is native Wordpress way of doing this, it's documented here:
Title and Description
These are pure texts, and they are rendered as-is on the frontend. In this case, these fields should be removed, and we should make the Title and
Completed, Target, Text and API URL
And that's it, the rest is the Preview, where we should get rid of the "Preview" title.
So, the end result after these conversions is:
Before taking a look at our block, let's have a look at WP's native Gallery:
This is the native Gallery block:
Another example:
Then most options live on the sidebar.
The Layout Selector should be converted to Block Styles:
The Title and Description, and Button Text can be edited in place, as they are not linked to any dynamic / automatic data from the site.
The Happy Point block is just a background. We should probably use the typical UI for uploading pictures in native WP components. Maybe we could add some placeholders to show how the form looks like in the Preview.
In this block, the two columns are independent but behave similarly. For the left column, selecting an issue will fill all the fields for you. The Select an issue field could be moved to the sidebar, along with the Issue Link Path (an URL) and the Select an Image button (or we can find a way to have that in the preview). Then the Issue Title, Issue Description and Issue Link Text fields could be editable in place.
The style options move to the sidebar:
As the slides move, I don't know if it makes much sense in trying to make the captions editable in place.
The Title and Description fields of the block can be editable in place. The video poster image option can probably stay as is, it's pretty consistent with some native WP blocks.
We could move the covers style to the side bar with the block styles option.
« Rows to display » dropdown menu could move to the side bar.
Title & description could be editable in place.
« select tags » + « select posts types» + « select posts » fields could move to the side bar.
The Background Image could possibly be selected in the editor with the same UI Wordpress provides for some of its blocks:
The Timeline Block relies heavily on a third party JS library. We can make the Title and Description editable. The rest of the options (Google Sheets URL, Language, Timeline navigation position, and Start at End) can be moved to the sidebar.
These would be the steps to turn the current form into a WYSIWYG one.
The Layout Selector can be converted into a Block Style.
Engaging Network Live Pages and Select Goal can be moved to the sidebar.
The Thank You message settings are not visible unless you submit the form. So we need to decide what to do with those options. Maybe we can have them in the sidebar and have a way to show the Thank You screen on the preview also.
So the function returns a which renders an empty div with some data attributes, which will be the placeholder for the block in the frontend site. This content is static and can be persisted safely to the database.
This is done in the file, which has a new entry point in our webpack config, and iterates through these placeholder divs to render the blocks inside using React.
This is not specific to this issue but this is a list of places in the UI in which we can inject things with Gutenberg:
For example, let's start analyzing the Counter block, from top to bottom:
This option changes the layout but is not a visible element of the frontend, so it should go on the sidebar. The old shortcake UI used to cover the editor, so you weren't able to actually see how the block would look while configuring it, now there is no need for so many thumbnails and explanations, since you'll be able to see the changes immediately.
So we should probably convert this Layout Selector component into "block styles" for all of our blocks.
the Description editable in the block's Preview.
These four settings are used to assemble the final text of the Counter block. As the text uses placeholders, we can't make it editable in the preview (imagine you type "%completed%" and it instantly turns into "500" or something), so these four options including their help text should be on the sidebar.
The media library UI for the native Gallery block has a slightly different look, we could investigate that to provide custom titles like "Create Gallery" in the UI.
There is no way to select focus points on the native Gallery. These are the options for links.
Then the Link, Open in new tab, Articles Count, Tags, Post Types and Ignore categories options, can be moved to the sidebar.
So the Title and Description in the current view would be editable.
The Title and Description can be edited in place. Rows to display, and Select Tags move to the sidebar. So the Title and Description fields are editable in place in the preview mode.
Again, Title and Description are editable in place. The rest of the options would move to the sidebar: Title and Description in the Preview mode. There is no preview for the Social media feed.
The "Layout Selector" moves to the sidebar using WP's "block styles". Then multiple columns can be added to the Columns block. The cheapest thing would be to add the "Add / Remove Column" options to the sidebar, but we have other alternatives:
For example, we could create something like this:
And then as you add columns, you'll be able to edit each column's properties. This requires a bit more research. This is the current preview, showing the possibly editable fields.
Again, the Title and Description fields are editable. The Name and Description fields are editable in-place for both the "Necessary" and "All Cookies" sections..
All titles and descriptions could be editable in place in the preview.
The current preview:
For the right column, selecting a campaign fills all the fields. The Select a tag field could be moved to the sidebar, along with the Campaign Button Link (an URL) and the Campaign Image button (or we can find a way to have that in the preview). Then the Campaign Description and Campaign Button Text fields could be editable in place.
Then these collapsible slides could be collapsible sections in the sidebar, with pretty much the same options.
Preview:
The Submenu block has no representation in the editor side right now. We could fix that by adding some placeholders (or actually making it work, maybe as a second iteration). The style chooser can use WP's style chooser mentioned at the top. Then the Title could be editable.
Currently, it has no output in the preview:
The Take Action Box gets all of its data from the Take Action Page option, which we could move to the sidebar:
All fields can be overridden, the Title, Excerpt, and Link Text can possibly be edited in place, the Link URL, Open in a New Tab and Select Tags fields can be moved to the sidebar.
As for the moment of writing this document, the preview does not seem to be working:
The Title, Description, Content Title, Content Description, Call To Action Text and Text Below Call To Action fields can be editable in place.
