Create an API for defining blocks in the editor.

[BE-Webdesign]

This can serve as a discussion for creating an API for the editor. Share your thoughts 😄

[BE-Webdesign]

Here are things I think the API should do/have:

• Be extensible
• Be easy to use
• Code should be easy to read and understand.
• Have great documentation/tutorials
• Provide a way to register types of blocks
• Create a separation between the blocks and their actual presentation. ( Blocks should be plain ole JavaScript objects that could then render themselves into what is needed. Most likely TinyMCE and DOM nodes. )

Addendum ( Block Types should most likely be registered server side and exposed to the client. )

[aduth]

Related controls discussion: #16

Taking a few of the current mockups as a basis, I've identified some/all of the pieces a developer should expect to be able to implement:

• Label
  • To be shown in insertion dialog
• Icon
• Block controls
• Inline controls (optional)
  • In the case of the quote mockup, one should expect to be able to format text. Is this merely supporting nested plain text block?
  • It's possible that some blocks may want to support only a subset of formatting options
• Children
  • Given sub-note of inline controls, perhaps blocks could allow nested block descendants
  • Future support of a "Columns" block?
• Custom editor-specific form
  • In the case of the quote mockup, the quote and citation may be separate fields
• Transform support
  • Mockup
  • e.g. change plain text to heading or quote
• Advanced settings popover ("Inspector")
  • Shown in early mockups for image settings, assumed to be the gear icon in the current image mockup

Below are a few of my early prototypes which include rough implementations of some or all of these requirements:

• https://github.com/aduth/wp-block#usage
• https://github.com/WordPress/gutenberg/blob/2a5a9f2/tinymce-per-block/src/blocks/text-block/index.js#L17-L53

Given discussion at aduth/wp-block#1, I've also been wondering if we could optionally / alternatively support server-side block registration options, with the following goals in mind:

• Sanitize block attribute values based on defined types
• Scaffold UIs based on defined block attribute types
  • These would admittedly not be as great a user experience, but seems to be an easy way for developers to make quick early iterations of a block, or for freelancers/agencies who can't necessarily justify creating extremely polished block UIs
• Allow blocks to be exposed through REST API or elsewhere in PHP, as current proposals expect registration to occur within browser client

We could look to Shortcake and JS Widgets for inspiration on implementing / consolidating server-side registration if it's a path we want to pursue (cc @westonruter @mattheu @danielbachhuber )

• https://github.com/xwp/wp-js-widgets/blob/f261e9f/core-adapter-widgets/text/class.php#L97-L114
• https://github.com/xwp/wp-js-widgets/blob/fd8c3c4/php/widgets/class-wp-js-widget-text.php#L66-L130
• https://github.com/wp-shortcake/Shortcake/blob/master/dev.php

Less obvious, but if we decide to add a new syntax for blocks, we'll also want to consider how to add backwards compatibility support for e.g. captioned images (currently shortcode) which should either be supported by or transparently upgraded to the new recommended block. This might need to be a separate issue.

[aduth]

Getting into a little more detail, for both block and inline controls, we'll have the following requirements (some assuming we follow proposed block comment syntax):

• Label
  • Used as tooltip / title
• Icon
  • Simplest would be a string reference to icon name of either the Dashicon or Gridicon (whatever we settle on)
  • Optionally supporting image URL, similar to register_post_type's menu_icon
  • Perhaps too complex for the sake of optimization, but in my latest prototype I'd made this a reference to a virtual DOM component primarily to avoid over-including unused icons
• Is selected?
  • Could either be associated with some attribute of a block, or simply passed a function and expected to return a truthy value (arguments include block attributes, children, ...)
• Click/tap behavior
  • For inline controls, it's likely we'd need to execute some command on the TinyMCE instance (regardless of whether we take approach of single or multiple instances)
  • For block level controls, this may either change content of the block or affect its attributes

[westonruter]

We could look to Shortcake and JS Widgets for inspiration on implementing / consolidating server-side registration if it's a path we want to pursue

Just to note here that JS Widgets 0.4 was recently released and it includes full integration with Shortcake so that all widgets defined as “JS widgets” are automatically also available as Shortcake post elements (content blocks). Likewise it introduces icons for widgets (current Dashicons).

The server-side registration ensures that that the widgets (blocks) can be exposed in the REST API and that the widget instance data is guaranteed to be JSON-representable so that the data can be manipulated directly with JS (see WP-CORE#35574, WP-CORE#33507). The widget also then defines the interface for manipulating the data, sanitizing the data, and rendering the data with PHP. The shortcode on the other hand only addresses the last piece, the rendering of the data. The Shortcake plugin was developed to implement the shortcode UI which essentially is a JS-driven version of what widgets historically handled with PHP (WP_Widget::form() and WP_Widget::update()), and thus JS Widgets is able to provide the plumbing for how Shortcake manages a widget shortcode's state.

[jasmussen]

In the case of the quote mockup, one should expect to be able to format text. Is this merely supporting nested plain text block?

We should probably not tackle nested blocks for the editor focus. This will absolutely become necessary for the customization focus, but probably best as something to keep in mind but not work on.

Incidentally you pointed out an error in the mockups. Yes, you should be able to format quotes. The omission of controls was in error. Here's an updated mockup:

It's possible that some blocks may want to support only a subset of formatting options

Absolutely. Headings probably shouldn't have any formatting at all. I'm sure there will be other blocks with unique requirements.

[Lewiscowles1986]

Are there plans for what to do with oEmbed content like if someone posts a link to a YT in a paragraph?

I'd think it's safer to

• simply split the paragraph into two paragraphs with an oEmbed in-between if oEmbed link not at start or very end of content
• simply end the paragraph before the oEmbed if there is no text after the oEmbed link
• prepend the oEmbed if it's at the start of a paragraph

[jasmussen]

Are there plans for what to do with oEmbed content like if someone posts a link to a YT in a paragraph?

Some discussion here: #81 (comment)

See also #24 (comment)

[aduth]

Are there plans for what to do with oEmbed content like if someone posts a link to a YT in a paragraph?

I was going to mention that in complementing discussion in #81, it would be nice to support blocks registering as being associated with a particular oEmbed URL pattern, such as to allow a YouTube block to enable the user to configure features like start time and autoplay. However, in looking at a few examples, it's not commonly supported to customize the embedded URL to affect these changes. In YouTube's case, you'd have to modify the markup of the embedded frame returned, or for Vimeo passing as arguments to the oEmbed request itself. Which is to say, neither of these services would allow you to control their embed behavior by the URL we'd expect to be saved in post content.