Add API documentation for blocks and element #302

aduth · 2017-03-21T12:42:06Z

Closes #104
Related: #300

This pull request includes a proposal for block APIs, previewed at the links below:

Most ideas are arrived at from conversation at #104, particularly expressed at:

The blocks documentation includes an example of implementing a Gravatar block that I think highlights some common but challenging requirements that motivate some of the API decisions (distinct editor interface, reusable markup between editor UI and published content, "secret" block state).

youknowriad · 2017-03-21T12:51:59Z

modules/blocks/README.md

+
+Because many blocks share the same complex behaviors, the following components are made available to simplify implementations of your block's `edit` function.
+
+### `Editable`


If I understand correctly, if you use the Editable component you get the format toolbar for free. This is handy and I'm all for it but, we'll have some issues here: Positioning the toolbar won't be easy to do, also imagine a component uses more than on Editable. From the mockups sometimes the toolbar is shown just above the input, and sometimes it's next to the block controls.

Positioning the toolbar won't be easy to do

What challenges do you foresee with positioning?

imagine a component uses more than on Editable

The rough idea would be that for any editable region that receives focus, we can bubble or otherwise make aware to the toolbar renderer that we're in the context of an editable field. "bubble or otherwise make aware" might be the challenge here, but thinking of the toolbars as handled at a more framework-level should at least give us some options to move this out of sight of the block implementer.

The positioning challenge:

If I understand properly, the inline toolbar is rendered by the Editable component while the block toolbar is rendered by the Editor (parent of blocks). So the challenge is to position the inline toolbar next to the block toolbar when we don't really know the width of the block toolbar (probably need JS positionning)

youknowriad · 2017-03-21T12:52:12Z

modules/blocks/README.md

+- `tagName: string` - An alternative to defining `edit` and `save` behaviors, if passed a [tag name](https://developer.mozilla.org/en-US/docs/Web/API/Document/createElement#Parameters), delegates default behavior of an editable field on that node type. Typically used for simple, text-heavy elements (paragraphs, headings) to avoid excess meta storage of text.
+- `controls: string[]` - Slugs for controls to be made available to block. See also: [`wp.blocks.registerControl`](#wpblocksregistercontrol-slug-string-settings-object-)
+
+### `wp.blocks.registerControl( slug: string, settings: Object )`


I'm not certain yet about the needs of the controls API, I mean maybe we would want a control to be more than just a button (imagine an interaction directly on the toolbar), do you think we could have a render method that takes precedence over the other attributes (something like the edit for blocks)

It's a good point to raise. A few from the mockups that might be hard to implement with this direction:

Linking: Presumably need to be able to render some tooltip. setAttributes of the onClick callback can at least be asynchronous from current API proposal. Some general render-like behavior could be a good fit. But in that case would a control need its own state (shown/hidden)?

Floating toolbars on "Image in gallery selected"

Distinct toolbar buckets, like "Early Admin UI Concept" image advanced options button. This would be much simpler if we simplify distinction between block-level and inline controls (advanced options as button grouped with rest of alignment, maybe with some separator).

Some related Slack discussion: https://wordpress.slack.com/archives/C02QB2JS7/p1490119310980240

The tricky bit is that you might often want to make an image linked, but you rarely want to make it bold, whereas an image caption you'd often want to make both linked, and bold.

We might end up with something close to what TinyMCE and Calypso has currently, a permanently visible toolbar. But let's not throw in the towel quite yet.

What if we did something like this? Image selected, most inline tools are grayed:

When focus is on the caption:

In this mockup I unified the toolbar and separated with lines, to simplify the silhouette.

The tricky bit is that you might often want to make an image linked, but you rarely want to make it bold, whereas an image caption you'd often want to make both linked, and bold.

Ah yeah, this is a good one. It could work to apply "Link" as a block-level control, but the downside of this is that when writing in the caption, you'd have two separate "Link" buttons: one for linking the block (image), one for linking the selection in caption. Seems more appropriate to move "Link" from a block-level control to specific to either selected image / caption.

As far as I see there will be three toolbars:

"Blocks" toolbar visible when any block is focused.

"Inline" toolbar visible when a text/html block is selected. This includes all blocks with editable HTML, like image, etc.

"Custom" toolbar that is optional and would have block specific controls.

There would be some crossover/relationship between the toolbars. If a button is present in the "higher level" toolbar it is skipped in the "lover level" one. For example a link button in the "blocks" toolbar would cause the same button to be skipped in the "inline" and "custom" toolbars.

Another example is aligning the text in the image caption in the above mockup. The four alignment buttons work on the whole block if the caption is not focused, but would work on the text when it is focused. If that block didn't have alignment buttons in the "blocks" toolbar, they may be present in the "inline" toolbar or the "custom" toolbar.

This will ensure good compatibility between core and plugins that add buttons to the toolbars.

youknowriad

Really great work. 👍 for me, I think these are still moving parts and we may want to introduce more flexible APIs (though I agree that the more we keep it minimal, the best is).

Even for contributors to the project, this gives a nice path to build the first blocks/controls. We’ll discover the limits and iterate over time

youknowriad · 2017-03-21T13:04:54Z

modules/blocks/README.md

+		return el( 'form', { onSubmit: setEmail }, children );
+	},
+	save: function( block ) {
+		return GravatarImage( { email: block.attributes.email } );


How would you imagine us getting the HTML from this? we render it to a dom node and user innerHTML? or maybe we'd use renderToString?

maybe we'd use renderToString

Probably more like this.

Demonstrate markup attributes retrieval

aduth · 2017-03-24T17:20:19Z

I've updated the blocks documentation to lean more heavily on inferring block attribute values from the markup itself, removing all reference to storage in post meta and replacing the Gravatar example with one which shows a random categorized image from lorempixel.com.

I've been toying with conveniences for querying values from markup in a separate project hpq, which is already currently integrated in limited form in the text block implementation.

There are a few things noted in the course of the discussion here that will likely need to be revisited, notably controls. That said, I'm inclined to move forward with this as a v1 direction unless anyone objects.

Needed primarily as solution to excess meta storage. Could still be useful as convenience for core block types, but let’s revisit it when deemed necessary.

youknowriad · 2017-03-27T09:17:05Z

Let's get this merged 🚢

youknowriad reviewed Mar 21, 2017

View reviewed changes

aduth mentioned this pull request Mar 21, 2017

Editor Blocks API proposal #300

Closed

youknowriad reviewed Mar 21, 2017

View reviewed changes

aduth mentioned this pull request Mar 22, 2017

Create an API for defining blocks in the editor. #104

Closed

aduth force-pushed the add/block-api-documentation branch from 067f98c to 9deb645 Compare March 22, 2017 14:16

mtias added [Type] Developer Documentation Documentation for developers Framework Issues related to broader framework topics, especially as it relates to javascript labels Mar 23, 2017

aduth mentioned this pull request Mar 23, 2017

Add Block: Image #310

Closed

aduth added 3 commits March 24, 2017 13:04

Add blocks and elements documentation

d6d15a2

Replace Gravatar example with random image

3760dc9

Demonstrate markup attributes retrieval

Prescribe comment metadata attribute behavior

6700d02

aduth force-pushed the add/block-api-documentation branch from 9deb645 to 6700d02 Compare March 24, 2017 17:10

aduth added 2 commits March 24, 2017 13:16

Rename "name" as "title", use consistently

46689f4

Document icon usage for blocks

18c427a

aduth added 2 commits March 24, 2017 13:22

Clarify expected encodeAttributes behavior

4dde9a9

Remove tagName from supported block properties

1058509

Needed primarily as solution to excess meta storage. Could still be useful as convenience for core block types, but let’s revisit it when deemed necessary.

aduth mentioned this pull request Mar 25, 2017

The Parser does not appear to be working correctly anymore??? Help needed! #326

Closed

youknowriad mentioned this pull request Mar 25, 2017

Plugin: Quote Block Initial Attempt #327

Closed

aduth merged commit dfee479 into master Mar 27, 2017

aduth deleted the add/block-api-documentation branch March 27, 2017 13:29

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add API documentation for blocks and element #302

Add API documentation for blocks and element #302

aduth commented Mar 21, 2017

youknowriad Mar 21, 2017

aduth Mar 21, 2017

youknowriad Mar 21, 2017

youknowriad Mar 21, 2017

aduth Mar 21, 2017 •

edited

Loading

jasmussen Mar 21, 2017 •

edited

Loading

aduth Mar 21, 2017

azaozz Mar 21, 2017 •

edited

Loading

youknowriad left a comment

youknowriad Mar 21, 2017

aduth Mar 21, 2017

aduth commented Mar 24, 2017

youknowriad commented Mar 27, 2017


		Because many blocks share the same complex behaviors, the following components are made available to simplify implementations of your block's `edit` function.

		### `Editable`

Add API documentation for blocks and element #302

Add API documentation for blocks and element #302

Conversation

aduth commented Mar 21, 2017

youknowriad Mar 21, 2017

Choose a reason for hiding this comment

aduth Mar 21, 2017

Choose a reason for hiding this comment

youknowriad Mar 21, 2017

Choose a reason for hiding this comment

youknowriad Mar 21, 2017

Choose a reason for hiding this comment

aduth Mar 21, 2017 • edited Loading

Choose a reason for hiding this comment

jasmussen Mar 21, 2017 • edited Loading

Choose a reason for hiding this comment

aduth Mar 21, 2017

Choose a reason for hiding this comment

azaozz Mar 21, 2017 • edited Loading

Choose a reason for hiding this comment

youknowriad left a comment

Choose a reason for hiding this comment

youknowriad Mar 21, 2017

Choose a reason for hiding this comment

aduth Mar 21, 2017

Choose a reason for hiding this comment

aduth commented Mar 24, 2017

youknowriad commented Mar 27, 2017

aduth Mar 21, 2017 •

edited

Loading

jasmussen Mar 21, 2017 •

edited

Loading

azaozz Mar 21, 2017 •

edited

Loading