Gutenberg Integration

[swissspidy]

The WP Team List plugin would be a great candidate to highlight the UX of the new Gutenberg WordPress editor.

For this, we need a couple of things:

• REST API endpoints to list users according to our queries
  wp/v2/users might not work because of the permissions checks. Our controller could be a GET only wrapper of WP_REST_Users_Controller.
• JavaScript templates to render the team list in the editor (WYSIWYG!)
• Integrate Gutenberg's i18n component and figure out how to let users properly translate the plugin
  This might not even be possible right now because of core and meta limitations
• PHP part to render the block server-side

Things like user role arguments etc. can be set up as block settings in the sidebar. Any change to the block settings results in a new REST API query and a re-render of the block with the JS template.

This might be a great opportunity to integrate some more powerful features like #44, #25, and #43.

The serialized team list block could look like this:

<!-- wp:required/team-list {"linkToPage":10, "numberOfItems": 10, "roles": ["editor", "author"]} /-->

No need for any content between the comments, or perhaps just for the title.

A project like https://github.com/ahmadawais/Gutenberg-Boilerplate could help with getting things done here, but the documentation on how to create new blocks is rather straightforward itself.

I'd love to use JSX for this (see https://gist.github.com/aduth/fb1cc9a2296110a62b96383e4b2e8a7c for an example), as it's more close to Gutenberg itself and people don't need to learn two things.

We just need to set up Babel for this (which we already use in other projects) and leverage the transform-react-jsx plugin, see https://github.com/WordPress/gutenberg/tree/master/element#jsx.

Oh, and tests would be great too if possible.

[swissspidy]

Just to clarify, this is quite a large task. Let's break it down into smaller chunks so we can more easily split it into multiple issues later.

Note: all the estimated hours are with some buffer time in it, because you never know ™.

REST API endpoints

WP_REST_Users_Controller is quite heavy. Since we only need a few fields for each user, it's easier to roll our own endpoint that is inspired by the existing controller, but completely new.

Estimated: 4h

JavaScript template

We have an existing template file that themes can override. We need to port this to JavaScript, albeit with some adjustments.

Leveraging JSX here would be great in order to have the same structure for everything. But an underscore template might work as well in the beginning. Ideally themes could filter this template too.

Estimated: 6h (perhaps less when not using JSX etc)

I18N

I18N is something that we do during development anyway. However, we'd need to do something special to make it actually translatable for users on WordPress.org. Just creating a POT file is not enough.

Possible solution: noop __() calls in a PHP file with the same strings as in the JS and then calling setLocaleData() from Gutenberg's i18n module with these translations. Probably not worth the effort as I suspect there to be many changes in that regard in the future.

Estimated: 4h

Registering the block with Gutenberg

This includes things like block settings, calling the REST API (can check out the Latest Posts block for inspiration), rendering the block after changes, and making sure it can be properly edited by users. It should serialize to something like in the example above.

Estimated: 8h (less when not using JSX, Webpack, etc.)

Server-side block rendering

Using the new WP_Block_Type_Registry class, we need to make sure that when displaying the team list on the front end, you'll get the same result as in the editor with the live preview.

This would be a simple class implementing a render method that's gonna be called by WP_Block_Type.

For this, we could even use the same REST API endpoint and just do an internal request (i.e. no HTTP involved) with the attributes from the block to keep things DRY. In theory, we could also use that internal REST API request in the existing shortcode. Perhaps that would result in some updated PHP template.

Estimated: 4h

Multiple roles and custom orders

The features I mentioned in the issue — #25, #43, #44 — can be mostly implemented while doing the above enhancements.

Estimated: 2h

Tests

Well … We could write some PHPUnit tests for the REST API endpoint and the WP_Block_Type registration stuff.

On the JS side of things, Gutenberg doesn't yet have many tests for all the blocks / components. Most tests for the blocks are about the serialization stuff, which we shouldn't have to worry about.

Even some simple tests showing that our custom React component (if we add one) renders properly would be cool, see https://github.com/WordPress/gutenberg/blob/2beeb4c37e9f6798d846167e64ad46e422b5d38f/blocks/block-description/test/index.js for an example. However, it's best to wait for this. I can imagine the whole setup to be a bit clunky.

Estimated: 4h (PHP only)

[swissspidy]

Thanks to wp-cli/scaffold-command#96 this got significantly easier.

@grappler @ocean90 Maybe one of you wants to give this a try at some point? 🙂