Writing Overview | Dynamic Tokens Proposal | HTML Templating

🚧👷‍♂️

What are Shortblocks?

Blocks are big; Shortblocks are small.

Shortblocks is the official name for a concept which has evolved from many different names. You may have heard or read about one of the following terms:

• Shortcodes 2.0 — The most succinct way to convey what this feature is.
• Dynamic tokens — References that these are placeholders whose content is to be supplied by the server or some other system at view time rather than edit time.
• Bits — Codename for the project while being researched and explored.
• Pips — A fun proposal taking inspiration from dice which are blocks containing pips.
• Personalized tags, template placeholders, custom fields, bindings, etc… — Speak to the nature of the fact that these are inline placeholders representing some externally-sourced data. These were never part of the proposal, but stem from various independent implementations of the idea.

Blocks introduced the concept of rich, higher-level, semantic content types realized through a serialization into and out of HTML. When blocks and the Block Editor were developed, the focus was on representing and editing these types: paragraphs, callouts, multimedia, polls, star ratings, columns, big things. But this drew focus away from the little things, things which Shortcodes had previously provided (ideally), things like:

• Show a given time in a localized form for the reader’s timezone.
• Include the post author inside part of a post template, embedded within a sentence, e.g. “This post was written by [post author] on [publish date].”
• Reference a custom field value within a post.
• Specify an image source as a specific filename based on the theme directory.

Shortblock principles

Shortblocks are a horizontal concern across all block types. No developer building blocks should have to be aware of Shortblocks or eagerly build in any support in order to allow them. Shortblocks are inserted by writers and editors where they want them, not where plugin developers and designers anticipate or direct.

Shortblocks are small. The content supplied to replace Shortblocks may contain helpful HTML markup; for example, a countdown Shortblock may wrap its time string in a <time> element, and may separate parts of the time in <span> elements. However, if a Shortblock attempts to produce too much markup then WordPress may reject or modify the output to prune it. Full-page layouts, galleries, and data tables are relegated to the realm of Blocks. It is not possible to nest Shortblocks inside of Shortblocks; they are atomic elements without inner content.

Shortblocks appear inside the editor as placeholders and it is possible to “reveal” the rendered contents of the Shortcodes inasmuch as that is possible at edit time. There are therefore two views of Shortblocks within the editor: one highlights the placeholder aspect while the other previews the output.

Shortblocks are parameterized by various arguments which are colocated with the Shortcode and edited through rich UI controls in the editor, akin to how the Link format is parameterized by a URL and whether to open the link in a new window. Clicking on a Shortblock opens the modal with its controls.

Shortblocks are discoverable through registration just as Blocks are. A Shortblock search and auto-completing hotkey make it easy to find and insert Shortblocks anywhere in a document, whether inside a RichText element or a Plaintext control.

Shortblock providers return HTML templates or plain strings and never escape for HTML. Safe escaping is managed by WordPress so developers don’t have to and to avoid problems with double-escaping and HTML composition. Properly escaping is confusing, so Shortblocks are safe by default. This also means that Shortblocks which return HTML markup, and which are found in plaintext contexts, will have that markup stripped out when rendering; this avoids extraneous rendering of unwanted HTML syntax.

Contrast to Shortcodes

Shortcodes have notable shortcomings, primarily that:

• Nesting is optional and unspecified. They suffer from the dangling-else problem.
• Shortcodes mix the language of HTML with another language on top or underneath it. The render of a document depends on whether HTML is processed before or after Shortcodes are processed. Being able to cross HTML boundaries introduces the ambiguity.
• Historically, Shortcodes were used to carry far more than their weight on a page render. Their over-use led to information loss when content was exported or when necessary plugins were unavailable.

Shortblocks are intended to fulfill the purpose of the Shortcode but to avoid bringing foward their largely unsolvable baggage.

Technical considerations

Shortblock registration

Shortblock providers are registered on the server and will be used to replace Shortblocks on render.

function shortblock_provider_localized_time( $shortblock_name, $attributes, $context ) {
	$time = $attribute['time'];

	switch ( $context['location'] ) {
		case 'attribute':
			return date( 'c', $time );

		case 'data':
			return new WP_HTML_Template(
				'<time datetime="</%machine>" data-unixtime="</%time>"></%human></time>',
				array(
					'machine' => date( 'c', $time ),
					'time'    => $time,
					'human'   => localized_date( $time ),
				)
			);
	}
}

register_shortblock(
	'my/localized-time',
	array(
		'category'    => 'formatting',
		'description' => 'Presents a given time in a localized way.',
		'provider'    => 'shortblock_provider_localized_time',
		'attributes'  => array(
			'time' => array( 'type' => 'number' )
		)
	)
);

Editor previews

The editor should be able to provide a preview of a Shortblock. In some cases this should be readily available, such as when using a post author Shortblock or including a custom field within a specific post. In other cases there is no intrinsic preview, apart from using auto-generated data, such as when building an email newsletter with recipient placeholders. In still more cases, a preview may be available but misleading, such as when the rendering of the Shortblock depends on the privileges of the requesting user, or based on some other complicated inputs.

Therefore Shortblocks provide an endpoint for requesting sample renders. The caller may supply additional $context to the provider function if it’s important to mock a specific context for rendering, such as for a public vs. logged-in view.

Discoverability

Registered Shortblocks are available via an API endpoint listing the available Shortblocks, descriptions, categories, and attribute schemas.