↓
 

Make Your WordPress Theme Fully Compatible with Gutenberg

Weaver Xtreme Theme Posted on by

It’s Time for Gutenberg

Let’s face it: the new WordPress Gutenberg editor is almost here, planned for inclusion in WP 5.0 sometime in 2018. Whatever the pros and cons of Gutenberg may be (even the final release name), the time has come to fully support Gutenberg with your WordPress theme. This article discusses the steps needed to add full Gutenberg compatibility for Weaver Xtreme 4.0, and has technical details that can easily be applied to make any theme Gutenberg ready.

This article is also a positive viewpoint about Gutenberg. There has been an incredible amount of negative reaction to Gutenberg. The reviews to the plugin tend to the negative. While there is a bit of a learning curve to adapt to the block content orientation, once the concept soaks in, Gutenberg is really quite easy to use. I’d guess I felt comfortable and compentent within a couple of hours of using it.

It is my opinion that much of the negative reaction is the essentially total lack of themes that actually support Gutenberg properly. Weaver Xtreme 4.0 changes all that. As the screenshots below demonstrate, the usability of Gutenberg is highly dependent on full theme integration, and until now, that simply has not been available for proper evaluation. No wonder the reaction has been so negative.

The Theme Integration Process

At this point, the details of this article apply to the most recent Gutenberg plugin available at the time of writing: 2.6. There are plenty of things still needed to make Gutenberg fully functional, it does appear that the basic elements and CSS class structure are fairly stable. We will try to update this article with any new details as Gutenberg evolves to the final WP 5.0 integrated version, but it seems very likely that most of this article will remain relevant. This paragraph will be updated to reflect which version of Gutenberg is relevant.

While the legacy TinyMCE editor can be styled fairly easy with the editor-style.css file, Gutenberg has as somewhat more powerful method to add styling.  Gutenberg requires styling at both the editor and front-end level by your theme to make a great user experience. Without such styling, your theme will be seriously deficient.

What do I mean by Full Gutenberg compatibility? If your theme does not provide BOTH front-end and back-end styling, it should not be considered Gutenberg compatible.

  1. The site visitor’s view (front-end) should match your theme’s standard styling 100%. This is mostly true now for most themes, but mostly with some noticeable deficiencies, especially for some Gutenberg blocks.
  2. The Gutenberg visual editor view should be as close to a 100% WYSIWYG display of the final, front-end view. This certainly is NOT true for nearly all existing themes.

 

In my opinion, any WordPress theme that does not meet the above two criteria is not fully Gutenberg compatible, and really will need to be updated in preparation for WP 5.0.

While these two rules apply to TinyMCE as well, it is even more important for Gutenberg because of the different blocks it supports. Theme Check does look for the tinyMCE editor styling file, but it is a RECOMMENDED check but not required. I hope editor styling becomes a more important part when Gutenberg is “official”.

To add theme support, I think the main goal is to achieve as much of a WYSIWYG experience for the editor. Block elements (such as Blockquote) will need styling so that the theme’s styling is matched by the editor. Perhaps adding support for the new .alignwide and .alignfull classes supported in the Gutenberg editor interface is one of the more challenging tasks. I hope this article will simplify that.

Here are a couple of screenshots that demonstrate exactly what I mean, using Weaver Xtreme 4.0 to demonstrate. Notice how the editor visual screenshot has all of the font styles, colors, background colors, image layout, and other HTML elements styled almost exactly the same as the final front-end view. This is what I consider to be full Gutenberg compatibility.

WSYSIWYG? Yes, with theme support. Compare Weaver Xtreme 4.0 vs. Twenty Seventeen 1.5

Weaver Xtreme Gutenberg Editor and Front End Screen Shots

Twenty Seventeen Gutenberg Editor and Front End Screen Shots

 

Weaver Xtreme Theme

Weaver Xtreme is the result of over 8 years of continuous development, and was the original options based theme. Options based themes provide the user with many options and capabilities to create their own design. This contrasts with design based themes where the theme developer provides almost all of the design for theme, while limiting options to a small number, perhaps including basic colors, fonts, and sidebar layouts.

Weaver Xtreme allows the beginning user a small set of choices, while supporting different levels of options. The the most flexible, the advanced user has over 600 options available, as well as making it easy to add custom CSS to specific elements of the theme.

Weaver Xtreme Gutenberg Demos

Here are a couple of pages show how some pages with Gutenberg look with Weaver Xtreme 4.0:

 

Get Weaver Xtreme 4.0 Alpha Test Version

Weaver Xtreme 4.0 is not quite ready for addition to the WordPress repository, but is available in a quite stable Alpha test version.

Click to get: Weaver Xtreme Version 4 Alpha Release

 

Steps Needed to Implement Full Gutenberg Compatibility

  • Add a front-end theme specific .css file to style Gutenberg blocks
    • Not all blocks will need specific styling
    • All blocks should have general consistency base styling (e.g., bottom margins)
    • Certain other CSS styles can be provided for custom styling
    • Most existing Gutenberg block styling works, but some will need override rules
    • Almost all other general HTML styling will be provided by the theme’s standard style.css file
  • Add static back-end .css file to style the Gutenberg Visual Editor
    • Many theme specific HTML elements must be styled: lists, block quotes, image layout, and more
    • Matching font styling (family, weight, style, other elements) must be provided for the editor
    • The width of the Gutenberg editor usually should be increased (it is quite narrow by default)
    • Images require the significant special attention
    • These styling rules can also be applied to the legacy TinyMCE visual editor fairly easily
  • Theme customizations  may require a dynamically generated .css file to style the visual editor
  • These two or three required CSS files are easily added using Gutenberg actions

 

Step by Step Implementation Details

 

  • Add a front-end theme specific .css file to style Gutenberg blocks

It is important to note that Gutenberg creates blocks mostly by wrapping each block in HTML comments. These comments provide  some meta-data for the styling of the block content. That styling is applied as appropriate to the content of each block. But the front-end output from Gutenberg is pure HTML – no JavaScript is needed to display the page/post content. Thus, getting that content to match the theme is up to the theme implementation.

Gutenberg will load its own stylesheet to provide default styling for the essential HTML code used to define each block. This includes lists, normal images, blockquotes, pull quotes, headings, columns, separators, audio, video, code, preformatted, tables, verse, buttons, text columns, cover images, and probably more as Gutenberg continues development. It is almost certain that the default Gutenberg styling for at least some of these elements will differ from the default styling of the theme. Thus, it is essential that the theme provide its own styles to override the default Gutenberg styles. While this could be in the theme’s style.css, it is probably more convenient to have a separate theme Gutenberg front-end style sheet. This stylesheet can also be used to provide styling directly to the Gutenberg editor.

Example Theme Front-end Block Styling .css file

This post provides and example of a theme Gutenberg stylesheet for the front-end display. This example represents the actual stylesheet used by Weaver Xtreme at the time this article was written. It is likely it will  be upated as Gutenberg evolves.

Example Front End styling: Example Theme Block Styles for Gutenberg

  • Add static back-end .css file to style the Gutenberg Visual Editor

The Gutenberg editor also requires some styling to make the page or post style correctly within the editor. This involves using class wrappers that are specific to the content of the editor at edit-run time. In addition to the back-end styling, you also need to include the previous front-end theme specific front-end stylesheet.

Example Theme Back-end Editor Styling .css file

This post provides and example of a theme Gutenberg stylesheet for the back-end editor display. This example represents the actual stylesheet used by Weaver Xtreme at the time this article was written. It is likely it will be upated as Gutenberg evolves.

Example Back-End Editor  styling: Example Theme Editor Styling for Gutenberg

The Gutenberg editor styling rules can also be applied to the legacy TinyMCE visual editor fairly easily

Gutenberg wraps the page/post content with more classes than TinyMCE, but in reality the same HTML elements must be styled in a very similar fashion for the two editors. With TinyMCE, may elements are styled directly (e.g., hr{background-color:#CCCCCC;}) or with a prefix class (e.g., .mceContentBody table {border: 2px solid #888 !important;}). For most styling rules, there is little change for Gutenberg: (e.g., hr{background-color:#CCCCCC;} or .mce-content-body table {border: 2px solid #888 !important;}). Often, you just need .mceContentBody or .mce-content-body.

  • Dynamically generated editor .css file for Theme Customizations

If you theme has Customizer options, you may need to add an additional dynamically generated CSS file for the editor. Presumably your theme would already do that for the front end view. For Gutenberg, this should be a file best saved in /wp-content/uploads.

  • These required CSS files are easily added using Gutenberg actions

Use these specific actions invoked by Gutenberg to add your style files to the editor and front end.

// =============================== >>> ACTION: weaverx_enqueue_gutenberg_style <<< ================================

/**
 * Action:	Enqueue style sheets and fonts for Gutenberg Editor only.
 *
 * @since 4.0
 *
 */
function weaverx_enqueue_gutenberg_block_editor_assets() {
	// add our element styles to gutenberg. enqueues for editor only

	/* replace the default editor-style.css with custom CSS generated on the fly by the php version */
	if (weaverx_getopt('_hide_editor_style'))
		return;

	$style_file = get_template_directory_uri() . '/assets/css/gutenberg-blocks'.WEAVERX_MINIFY.'.css';
	wp_enqueue_style( 'weaverx_gutenberg_block', $style_file, array(),WEAVERX_VERSION );

	$editor_file = get_template_directory_uri() . '/assets/css/gutenberg-base-editor-style'.WEAVERX_MINIFY.'.css';

	// enqueue style file
	wp_enqueue_style( 'weaverx_gutenberg_fonts', WEAVERX_GOOGLE_FONTS_URL);	// load the Google Fonts the theme uses so they are avilable to the editor
	wp_enqueue_style( 'weaverx_gutenberg_base_style', $editor_file, array(), WEAVERX_VERSION);

	$updir = wp_upload_dir();

	$css_file = trailingslashit($updir['basedir']) . 'weaverx-subthemes/gutenberg-editor-style-wvrx.css';	// generated CSS files won't be minified

	$css_path = trailingslashit($updir['baseurl']) . 'weaverx-subthemes/gutenberg-editor-style-wvrx.css';

	if ( weaverx_f_exists( $css_file ) ) {	// add dynamically generated editor CSS if the file exists
		$path = str_replace(array('http:','https:'),  '', $css_path);		// strip the http: if there, just use the //
		wp_enqueue_style( 'weaverx_gutenberg_wvrx_style', $css_path, array(), WEAVERX_VERSION);	// fixup CSS for current theme settings
	}
}

add_action( 'enqueue_block_editor_assets', 'weaverx_enqueue_gutenberg_block_editor_assets' );	// Gutenberg invokes this action

/**
 * Action:	Enqueue style sheets for Gutenberg Editor and Front end.
 *
 * @since 4.0
 *
 */
function weaverx_enqueue_gutenberg_block_assets() {
	// enqueue for BOTH editor and front-end
	$style_file = get_template_directory_uri() . '/assets/css/gutenberg-blocks'.WEAVERX_MINIFY.'.css';
	wp_enqueue_style( 'weaverx_gutenberg_block', $style_file, array(),WEAVERX_VERSION );
}

add_action( 'enqueue_block_assets', 'weaverx_enqueue_gutenberg_block_assets' );				// Gutenberg invokes this action

Comments are closed.

↑