Baseline Status In A WordPress Block

You already know about Baseline, proper? And you will have heard that the Chrome team made a web component for it.

Right here it’s!

In fact, we might merely drop the HTML element into the web page. However I by no means know the place we’re going to make use of one thing like this. The Almanac, obs. However I’m positive there are occasions the place embedded it in different pages and posts is sensible.

That’s precisely what WordPress blocks are good for. We are able to take an already reusable element and make it repeatable when working within the WordPress editor. In order that’s what I did! That element you see up there may be the <baseline-status> web component formatted as a WordPress block. Let’s drop one other one in only for kicks.

Fairly neat! I noticed that Pawel Grzybek made an equivalent for Hugo. There’s an Astro equivalent, too. As a result of I’m pretty inexperienced with WordPress block growth I believed I’d write a bit up on the way it’s put collectively. There are nonetheless tough edges that I’d wish to easy out later, however it is a adequate level to share the fundamental concept.

Scaffolding the challenge

I used the @wordpress/create-block bundle to bootstrap and initialize the challenge. All meaning is I cd‘d into the /wp-content/plugins listing from the command line and ran the set up command to plop all of it in there.

npm set up @wordpress/create-block

The baseline-status.php file is the place the plugin is registered. And sure, it’s seems utterly the identical because it’s been for years, simply not in a type.css file like it’s for themes. The distinction is that the create-block bundle does some lifting to register the widget so I don’t must:

<?php
/**
 * Plugin Identify:       Baseline Standing
 * Plugin URI:        https://css-tricks.com
 * Description:       Shows present Baseline availability for internet platform options.
 * Requires at the least: 6.6
 * Requires PHP:      7.2
 * Model:           0.1.0
 * Creator:            geoffgraham
 * License:           GPL-2.0-or-later
 * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
 * Textual content Area:       baseline-status
 *
 * @bundle CssTricks
 */

if ( ! outlined( 'ABSPATH' ) ) {
  exit; // Exit if accessed immediately.
}

operate csstricks_baseline_status_block_init() {
  register_block_type( __DIR__ . '/construct' );
}
add_action( 'init', 'csstricks_baseline_status_block_init' );

?>

The actual meat is in src listing.

The create-block bundle additionally did some filling of the blanks within the block-json file based mostly on the onboarding course of:

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 2,
  "identify": "css-tricks/baseline-status",
  "model": "0.1.0",
  "title": "Baseline Standing",
  "class": "widgets",
  "icon": "chart-pie",
  "description": "Shows present Baseline availability for internet platform options.",
  "instance": {},
  "helps": {
    "html": false
  },
  "textdomain": "baseline-status",
  "editorScript": "file:./index.js",
  "editorStyle": "file:./index.css",
  "type": "file:./style-index.css",
  "render": "file:./render.php",
  "viewScript": "file:./view.js"
}

Going off some tutorials revealed proper right here on CSS-Tips, I knew that WordPress blocks render twice — as soon as on the entrance finish and as soon as on the again finish — and there’s a file for each within the src folder:

• render.php: Handles the front-end view
• edit.js: Handles the back-end view

The front-end and back-end markup

Cool. I began with the <baseline-status> internet element’s markup:

<script src="https://cdn.jsdelivr.web/npm/[email protected]/baseline-status.min.js" kind="module"></script>
<baseline-status featureId="anchor-positioning"></baseline-status>

I’d hate to inject that <script> each time the block pops up, so I made a decision to enqueue the file conditionally based mostly on the block being displayed on the web page. That is taking place in the primary baseline-status.php file which I handled sorta the identical approach as a theme’s features.php file. It’s simply the place helper features go.

// ... identical code as earlier than

// Enqueue the minified script
operate csstricks_enqueue_block_assets() {
  wp_enqueue_script(
    'baseline-status-widget-script',
    'https://cdn.jsdelivr.web/npm/[email protected]/baseline-status.min.js',
    array(),
    '1.0.4',
    true
  );
}
add_action( 'enqueue_block_assets', 'csstricks_enqueue_block_assets' );

// Provides the 'kind="module"' attribute to the script
operate csstricks_add_type_attribute($tag, $deal with, $src) {
  if ( 'baseline-status-widget-script' === $deal with ) {
    $tag = '<script kind="module" src="' . esc_url( $src ) . '"></script>';
  }
  return $tag;
}
add_filter( 'script_loader_tag', 'csstricks_add_type_attribute', 10, 3 );

// Enqueues the scripts and kinds for the again finish
operate csstricks_enqueue_block_editor_assets() {
  // Enqueues the scripts
  wp_enqueue_script(
    'baseline-status-widget-block',
    plugins_url( 'block.js', __FILE__ ),
    array( 'wp-blocks', 'wp-element', 'wp-editor' ),
    false,
  );

  // Enqueues the kinds
  wp_enqueue_style(
    'baseline-status-widget-block-editor',
    plugins_url( 'type.css', __FILE__ ),
    array( 'wp-edit-blocks' ),
    false,
  );
}
add_action( 'enqueue_block_editor_assets', 'csstricks_enqueue_block_editor_assets' );

The ultimate consequence bakes the script immediately into the plugin in order that it adheres to the WordPress Plugin Directory guidelines. If that wasn’t the case, I’d most likely maintain the hosted script intact as a result of I’m utterly bored with sustaining it. Oh, and that csstricks_add_type_attribute() operate is to assist import the file as an ES module. There’s a wp_enqueue_script_module() motion accessible to hook into that ought to deal with that, however I couldn’t get it to do the trick.

With that in hand, I can put the element’s markup right into a template. The render.php file is the place all of the front-end goodness resides, in order that’s the place I dropped the markup:

<baseline-status
  <?php echo get_block_wrapper_attributes(); ?> 
  featureId="[FEATURE]">
</baseline-status>

That get_block_wrapper_attibutes() factor is beneficial by the WordPress docs as a option to output all of a block’s info for debugging issues, equivalent to which options it must assist.

[FEATURE]is a placeholder that can ultimately inform the element which internet platform to render details about. We might as properly work on that now. I can register attributes for the element in block.json:

"attributes": { "showBaselineStatus": {
  "featureID": {
  "kind": "string"
  }
},

Now we are able to replace the markup in render.php to echo the featureID when it’s been established.

<baseline-status
  <?php echo get_block_wrapper_attributes(); ?> 
  featureId="<?php echo esc_html( $featureID ); ?>">
</baseline-status>

There will likely be extra edits to that markup slightly later. However first, I must put the markup within the edit.js file in order that the element renders within the WordPress editor when including it to the web page.

<baseline-status { ...useBlockProps() } featureId={ featureID }></baseline-status>

useBlockProps is the JavaScript equal of get_block_wrapper_attibutes() and could be good for debugging on the again finish.

At this level, the block is totally rendered on the web page when dropped in! The issues are:

• It’s not passing within the function I wish to show.
• It’s not editable.

I’ll work on the latter first. That approach, I can merely plug the fitting variable in there as soon as every little thing’s been attached.

Block settings

One of many nicer facets of WordPress DX is that we’ve got direct entry to the identical controls that WordPress makes use of for its personal blocks. We import them and lengthen them the place wanted.

I began by importing the stuff in edit.js:

import { InspectorControls, useBlockProps } from '@wordpress/block-editor';
import { PanelBody, TextControl } from '@wordpress/parts';
import './editor.scss';

This offers me just a few useful issues:

• InspectorControls are good for debugging.
• useBlockProps are what could be debugged.
• PanelBody is the primary wrapper for the block settings.
• TextControl is the sphere I wish to go into the markup the place [FEATURE] at the moment is.
• editor.scss supplies kinds for the controls.

Earlier than I get to the controls, there’s an Edit operate wanted to make use of as a wrapper for all of the work:

export default operate Edit( { attributes, setAttributes } ) {
  // Controls
}

First is InspectorTools and the PanelBody:

export default operate Edit( { attributes, setAttributes } ) {
  // React parts want a mother or father aspect
  <>
    <InspectorControls>
      <PanelBody title={ __( 'Settings', 'baseline-status' ) }>
      // Controls
      </PanelBody>
    </InspectorControls>
  </>
}

Then it’s time for the precise textual content enter management. I actually needed to lean on this introductory tutorial on block development for the next code, notably this section.

export default operate Edit( { attributes, setAttributes } ) {
  <>
    <InspectorControls>
      <PanelBody title={ __( 'Settings', 'baseline-status' ) }>
        // Controls
        <TextControl
          label={ __(
            'Characteristic', // Enter label
            'baseline-status'
          ) }
          worth= '' 
          onChange={ ( worth ) =>
            setAttributes( { featureID: worth } )
          }
        />
     </PanelBody>
    </InspectorControls>
  </>
}

Tie all of it collectively

At this level, I’ve:

• The front-end view
• The back-end view
• Block settings with a textual content enter
• All of the logic for dealing with state

Oh yeah! Can’t neglect to outline the featureID variable as a result of that’s what populates within the element’s markup. Again in edit.js:

const { featureID } = attributes;

In brief: The function’s ID is what constitutes the block’s attributes. Now I must register that attribute so the block acknowledges it. Again in block.json in a brand new part:

"attributes": {
  "featureID": {
    "kind": "string"
  }
},

Fairly simple, I feel. Only a single textual content area that’s a string. It’s presently that I can lastly wire it as much as the front-end markup in render.php:

<baseline-status
  <?php echo get_block_wrapper_attributes(); ?>
  featureId="<?php echo esc_html( $featureID ); ?>">
</baseline-status>

Styling the element

I struggled with this greater than I care to confess. I’ve dabbled with styling the Shadow DOM however solely academically, so to talk. That is the primary time I’ve tried to type an internet element with Shadow DOM elements on one thing being utilized in manufacturing.

In the event you’re new to Shadow DOM, the fundamental concept is that it prevents kinds and scripts from “leaking” in or out of the element. This can be a huge promoting level of internet parts as a result of it’s so darn straightforward to drop them into any challenge and have them “simply” work.

However how do you type a third-party internet element? It will depend on how the developer units issues up as a result of there are methods to permit kinds to “pierce” by the Shadow DOM. Ollie Williams wrote “Styling in the Shadow DOM With CSS Shadow Parts” for us some time again and it was tremendous useful in pointing me in the fitting course. Chris has one, too.

A couple of different extra articles I used:

First off, I knew I might choose the <baseline-status> aspect immediately with none lessons, IDs, or different attributes:

baseline-status {
  /* Types! */
}

I glanced on the script’s source code to see what I used to be working with. I had just a few mild kinds I might use immediately on the kind selector:

baseline-status {
  background: #000;
  border: stable 5px #f8a100;
  border-radius: 8px;
  coloration: #fff;
  show: block;
  margin-block-end: 1.5em;
  padding: .5em;
}

I seen a CSS coloration variable within the supply code that I might use instead of hard-coded values, so I redefined them and set them the place wanted:

baseline-status {
  --color-text: #fff;
  --color-outline: var(--orange);

  border: stable 5px var(--color-outline);
  border-radius: 8px;
  coloration: var(--color-text);
  show: block;
  margin-block-end: var(--gap);
  padding: calc(var(--gap) / 4);
}

Now for a difficult half. The element’s markup seems near this within the DOM when totally rendered:

<baseline-status class="wp-block-css-tricks-baseline-status" featureid="anchor-positioning"></baseline-status>
<h1>Anchor positioning</h1>
<particulars>
  <abstract aria-label="Baseline: Restricted availability. Supported in Chrome: sure. Supported in Edge: sure. Supported in Firefox: no. Supported in Safari: no.">
    <baseline-icon aria-hidden="true" assist="restricted"></baseline-icon>
    <div class="baseline-status-title" aria-hidden="true">
      <div>Restricted availability</div>
        <div class="baseline-status-browsers">
        <!-- Browser icons -->
        </div>
    </div>
  </abstract><p>This function will not be Baseline as a result of it doesn't work in a number of the most widely-used browsers.</p><p><a href="https://github.com/web-platform-dx/web-features/blob/predominant/options/anchor-positioning.yml">Study extra</a></p></particulars>
<baseline-status class="wp-block-css-tricks-baseline-status" featureid="anchor-positioning"></baseline-status>

I needed to play with the concept of hiding the <h1> aspect in some contexts however thought twice about it as a result of not displaying the title solely actually works for Almanac content material once you’re on the web page for a similar function as what’s rendered within the element. Another context and the heading is a “want” for offering context so far as what function we’re taking a look at. Possibly that may be a future enhancement the place the heading could be toggled on and off.

Voilà

Get the plugin!

That is freely accessible within the WordPress Plugin Listing as of right now! That is my very first plugin I’ve submitted to WordPress alone behalf, so that is actually thrilling for me!

Future enhancements

That is removed from totally baked however undoubtedly will get the job executed for now. Sooner or later it’d be good if this factor might do just a few extra issues:

• Reside replace: The widget doesn’t replace on the again finish till the web page refreshes. I’d like to see the ultimate rendering earlier than hitting Publish on one thing. I received it the place typing into the textual content enter is immediately mirrored on the again finish. It’s simply that the element doesn’t re-render to point out the replace.
• Variations: As in “massive” and “small”.
• Heading: Toggle to cover or present, relying on the place the block is used.