WordPress Block Transforms

The year of Gutenberg of CSS-Tricks. At the end of last year, we set this goal. We are progressing much faster than expected, all new content is created in the Block Editor¹, and now everything has Block Editor enabled. This means when we open most of the old posts we see everything in the "classic" block. It looks like this:

The entire content of the post is in a single block, so it is not really leveraging the block editor. It's still "visible", like a block editor, but more like an old visual editor using TinyMCE. I've never used it because it forces the HTML to break in ways I don't like.

What I'm most worried about

Converting a classic block to a new block is as simple as selecting a classic block and selecting the "Convert to block" option.

How does the block editor handle blocking of old content when we tell it to do this from the Convert to Block option? What if the content is completely destroyed during the conversion process? Can we switch?

The answer is: It does quite well . But…there are still problems. Not a "error", but a case where our old content contains custom HTML, which doesn't know how to deal with it -- let alone how to convert it to the block we want. There is a way!

Basic block conversion

This is the origin of the idea of ​​"block conversion". All (well, most?) native blocks have "to" and "from" conversions. You may already be familiar with how it behaves in the UI. For example, paragraphs can be converted to references and vice versa. Here is a super meta screenshot about this paragraph:

These transformations are not magical; they are explicitly encoded. When registering a block, you specify the conversion. Suppose you are registering your own custom code block. You need to make sure you can convert it...

• From and to default built-in code blocks, and possibly some other blocks that may be useful.
• Return to the built-in code block.

It might look like this:

 <code>registerBlockType("my/code-block", { title: __("My Code Block"), ... transforms: { from: [ { type: "block", priority: 7, blocks: ["core/code", "core/paragraph", "core/preformatted"], transform: function (attributes) { return createBlock("my/code-block", { content: attributes.content, }); }, }, ], to: [ { type: "block", blocks: ["core/code"], transform: ({ content }) => createBlock("core/code", { content }), }, ], ...</code>

These are the conversions to and from other blocks . Fortunately, it's a very simple block and we're just moving the content around. More complex blocks may require passing more data, but I haven't handled this case yet.

Something more magical: Block conversion from original code

Here is the truth moment of the old content:

In this case, the creation of the block is not from other blocks, but from the original code. Literally, HTML is being viewed and decisions are being made about which blocks to create from HTML blocks. This is where the block editor does such a great job of selection, and where things can go wrong, make bad block selections, or break content.

In our old content, the code blocks ( very important things) in the post look like this:

 <code><code markup="tt">let html = `</code></code> cool `;

Sometimes block conversion processes these blocks, converting them into native code blocks. But there are some problems:

1. I don't want native code blocks. I want to convert this into our own new code block (there is a blog post here).
2. I need some information in these properties to inform the settings of the new block, such as the type of the code.
3. The HTML in our old code block is not escaped , I need it not to get stuck.

I don't have all the answers here because it's an evolving process, but I do have implemented some block conversions that run very well now. Here is what the "raw" conversion (as opposed to the "block" conversion) looks like:

 <code>registerBlockType("my/code-block", { title: __("My Code Block"), // ... transforms: { from: [ { type: "block", priority: 7, // ... }, { type: "raw", priority: 8, isMatch: (node) => node.nodeName === "PRE" && node.children.length === 1 && node.firstChild.nodeName === "CODE", transform: function (node) { let pre = node; let code = node.querySelector("code"); let codeType = "html"; if (pre.classList.contains("language-css")) { codeType = "css"; } if (pre.getAttribute("rel") === "CSS") { codeType = "css"; } if (pre.classList.contains("language-javascript")) { codeType = "javascript"; } if (code.classList.contains("language-javascript")) { codeType = "javascript"; } // ... other data wrangling... return createBlock("csstricks/code-block", { content: code.innerHTML, codeType: codeType, }); }, }, ], to: [ // ... ], // ... }</code>

The isMatch function runs on every HTML node it finds, so this is a great opportunity to return true from the function if you need it. Note that in the above code, I'm especially looking for something that looks like

<code>的HTML。当匹配时，转换运行，我可以返回一个`createBlock` 调用，该调用传入我使用JavaScript 从节点中提取的数据和内容。</code> Another example: Paste URL


<p>The "raw" conversion does not only happen when you "convert to block". This also happens when you paste the content into the block editor. You may have experienced this before. Suppose you copied some table markup from somewhere and pasted it into the block editor - it might be pasted as a table. The YouTube URL may be pasted into the embed. This kind of thing is why copy/paste from Word documents, etc. tends to work so well with the block editor.</p>



<p>Suppose you want to perform some special behavior when you paste a URL of some type into the editor. This is how I use a custom CodePen Embed block. I hope that if the codepen.io URL is pasted, it will use this custom block instead of the default embed.</p>



<p>Here is a "from" conversion that looks like this:</p>



{
  type: "raw",
  priority: 8, // higher number to beat out default
  isMatch: (node) =>
    node.nodeName === "P" &&
    node.innerText.startsWith("https://codepen.io/"),

  transform: function (node) {
    return createBlock("cp/codepen-gutenberg-embed-block", {
      penURL: node.innerText,
      penID: getPenID(node.innerText), // helper function
    });
  },
}


<h3 id="so">so……</h3>


<p>Is it messy? Something. But it is powerful and meets your needs. If you have an old website with a lot of custom HTML, short code, and more, then going into block conversion is the only way out.</p>



<p>I'm glad to master this, as I really like the block editor right now. It is a pleasure to write and build content with it. I like what Justin Tadlock says:</p>



<blockquote><p>The block system will not disappear. WordPress has gone beyond the stage where we should treat the block editor as a separate entity. It is an integral part of WordPress and will eventually touch more areas outside of editing screens.</p></blockquote>



<p>It will always exist. It is key to embrace the block editor and make it fit our wishes.</p>




<ol><li>Why do we call it? "Gutenberg" seems to be no longer suitable. It feels like it will fade away, even if its development is still in the Gutenberg plugin. I think I'd just call it a "block editor" unless specifically referring to the plugin.</li></ol>

The above is the detailed content of WordPress Block Transforms. For more information, please follow other related articles on the PHP Chinese website!