Add Gutenberg support to the plugin

[benlk]

Changes

• [x] registers a Gutenberg block

To do list

• [x] Actual block output
• [x] Differentiate in-editor vs rendered content (saves unnecessary content loading in editor, avoids possible conflicts between Pym and Gutenberg's React stuff)
• [x] #33: move pymsrc script tags to the footer
• [x] #35: move new pym.Parent script tags to the footer
• [x] Block and shortcode must have same output, but block uses the argument parent_id instead of id in order to avoid conflicts with React
  • [x] can the "anchor" item in the Gutenberg settings be used to set the parent ID?
  • [x] tests to make sure that stuff is output correctly
• [x] Add support for ~Gutenberg~ WordPress alignment classes
• [x] Add support for Gutenberg full-width output https://wordpress.org/gutenberg/handbook/extensibility/theme-support/#wide-alignment
• [x] find a test theme that implements the alignfull and alignwide classes, for testing purposes: https://wordpress.org/themes/atomic-blocks/
• [ ] Add support for converting a Pym iframe into a generic embed iframe via a transform: https://wordpress.org/gutenberg/handbook/block-api/#transforms-optional
• [x] Make the block in the editor the form, instead of the block-properties dialog box?
• [x] Move advanced options to the "advanced" section of the block-properties dialog box?

[benlk]

With the following post_content:

<!-- wp:shortcode -->
[pym src="https://f.benlk.com/graphics/heartbeat-abortion-bills/child.html"]
<!-- /wp:shortcode -->

<!-- wp:paragraph -->
<p>the preceding is a shortcode block.</p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p>The following is the Pym Embed:</p>
<!-- /wp:paragraph -->

<!-- wp:pym-shortcode/pym {"src":"http://blog.apps.npr.org/pym.js/examples/table/child.html","align":"full"} /-->

The following output:

<div id="pym_1" class="pym  "></div>
<script>var pym_1 = new pym.Parent('pym_1', 'https://f.benlk.com/graphics/heartbeat-abortion-bills/child.html', {})</script>

<p>the preceding is a shortcode block.</p>
<p>The following is the Pym Embed:</p>
<div id="pym_0" class="pym alignfull "></div>
<script src="http://pym-shortcode.test/wp-content/plugins/pym-shortcode/js/pym.v1.min.js"></script><script>var pym_0 = new pym.Parent('pym_0', 'http://blog.apps.npr.org/pym.js/examples/table/child.html', {})</script>

Why does the first one have a later ID? Does the block renderer run before the shortcode renderer? How can it be assured that the script source is output before any and all tags?

[benlk]

Long long debug output

```html wp> global $wp_filter; var_dump( $wp_filter['the_content'], true ); object(WP_Hook)#1139 (5) { ["callbacks"]=> array(5) { [8]=> array(3) { ["00000000430b60a000000000382d9011run_shortcode"]=> array(2) { ["function"]=> array(2) { [0]=> object(WP_Embed)#1440 (7) { ["handlers"]=> array(2) { [10]=> array(1) { ["youtube_embed_url"]=> array(2) { ["regex"]=> string(51) "#https?://(www.)?youtube\.com/(?:v|embed)/([^/]+)#i" ["callback"]=> string(24) "wp_embed_handler_youtube" } } [9999]=> array(2) { ["audio"]=> array(2) { ["regex"]=> string(41) "#^https?://.+?\.(mp3|ogg|flac|m4a|wav)$#i" ["callback"]=> string(22) "wp_embed_handler_audio" } ["video"]=> array(2) { ["regex"]=> string(41) "#^https?://.+?\.(mp4|m4v|webm|ogv|flv)$#i" ["callback"]=> string(22) "wp_embed_handler_video" } } } ["post_ID"]=> NULL ["usecache"]=> bool(true) ["linkifunknown"]=> bool(true) ["last_attr"]=> array(0) { } ["last_url"]=> string(0) "" ["return_false_on_fail"]=> bool(false) } [1]=> string(13) "run_shortcode" } ["accepted_args"]=> int(1) } ["00000000430b60a000000000382d9011autoembed"]=> array(2) { ["function"]=> array(2) { [0]=> object(WP_Embed)#1440 (7) { ["handlers"]=> array(2) { [10]=> array(1) { ["youtube_embed_url"]=> array(2) { ["regex"]=> string(51) "#https?://(www.)?youtube\.com/(?:v|embed)/([^/]+)#i" ["callback"]=> string(24) "wp_embed_handler_youtube" } } [9999]=> array(2) { ["audio"]=> array(2) { ["regex"]=> string(41) "#^https?://.+?\.(mp3|ogg|flac|m4a|wav)$#i" ["callback"]=> string(22) "wp_embed_handler_audio" } ["video"]=> array(2) { ["regex"]=> string(41) "#^https?://.+?\.(mp4|m4v|webm|ogv|flv)$#i" ["callback"]=> string(22) "wp_embed_handler_video" } } } ["post_ID"]=> NULL ["usecache"]=> bool(true) ["linkifunknown"]=> bool(true) ["last_attr"]=> array(0) { } ["last_url"]=> string(0) "" ["return_false_on_fail"]=> bool(false) } [1]=> string(9) "autoembed" } ["accepted_args"]=> int(1) } ["gutenberg_wpautop"]=> array(2) { ["function"]=> string(17) "gutenberg_wpautop" ["accepted_args"]=> int(1) } } [9]=> array(1) { ["do_blocks"]=> array(2) { ["function"]=> string(9) "do_blocks" ["accepted_args"]=> int(1) } } [10]=> array(4) { ["wptexturize"]=> array(2) { ["function"]=> string(11) "wptexturize" ["accepted_args"]=> int(1) } ["shortcode_unautop"]=> array(2) { ["function"]=> string(17) "shortcode_unautop" ["accepted_args"]=> int(1) } ["prepend_attachment"]=> array(2) { ["function"]=> string(18) "prepend_attachment" ["accepted_args"]=> int(1) } ["wp_make_content_images_responsive"]=> array(2) { ["function"]=> string(33) "wp_make_content_images_responsive" ["accepted_args"]=> int(1) } } [11]=> array(2) { ["capital_P_dangit"]=> array(2) { ["function"]=> string(16) "capital_P_dangit" ["accepted_args"]=> int(1) } ["do_shortcode"]=> array(2) { ["function"]=> string(12) "do_shortcode" ["accepted_args"]=> int(1) } } [20]=> array(1) { ["convert_smilies"]=> array(2) { ["function"]=> string(15) "convert_smilies" ["accepted_args"]=> int(1) } } } ["iterations":"WP_Hook":private]=> array(0) { } ["current_priority":"WP_Hook":private]=> array(0) { } ["nesting_level":"WP_Hook":private]=> int(0) ["doing_action":"WP_Hook":private]=> bool(false) } ```

Looks like yes, the block renderer does run before the shortcode renderer.

[benlk]

Hrm, how might this work:

1. Add a filter to the_content that checks for the presence of the string 'pym', and if it is there, sets a global "maybe" variable to true
2. In the pym renderer, if it is called, if the tag doesn't have its own pymsrc, set a global definitely variable to true. If pymsrc is set, then instead output the pymsrc's tag
3. In a filter running on the_content that runs at a very late priority, like 100, if $maybe and $definitely, prepend the_content with a script tag that registers Pym.

Alternately:

1. Everytime we would output a <script>var pym_1 = new pym.Parent('pym_1', 'https://f.benlk.com/graphics/heartbeat-abortion-bills/child.html', {})</script> , instead of outputting it then, add it to the footer with a generated callback function that has the correct variables inserted into its call!

[benlk]

Gonna open a separate issue for this problem, because that makes it easier to discuss separately from "should we implement blocks".

[benlk]

Can the Gutenberg anchor item be used to set the parent ID?

In theory, yes.

In practice:

• the magic used to support anchor appears to require that the save method on the block be implemented in a way that returns code to be saved in the post_content, which effectively prevents its use on dynamic bocks and serverside-rendered blocks like the Pym Embed block. https://github.com/WordPress/gutenberg/issues/6356
• there's a grand total of one reference implementation of a block that supports the anchor feature, and that's the heading block. And there are no implementation details there.

So:

• [x] remove anchor support declaration
• [x] create our own UI to pass that ID
• [x] create issue about later implementing anchor support with a migration function

[benlk]

Things that I'm going to spin off into separate issues:

• [x] Add support for converting a Pym iframe into a generic embed iframe via a transform: https://wordpress.org/gutenberg/handbook/block-api/#transforms-optional: https://github.com/INN/pym-shortcode/issues/37
• [x] Add support for converting the shortcode block containing a Pym iframe into a Pym Block, because https://github.com/WordPress/gutenberg/issues/8569 seems like there might be motion on that in Gutenberg: https://github.com/INN/pym-shortcode/issues/38

Left for this PR:

• [x] making sure that the README/Changelog is accurate.
• [x] documenting the block stuff
• [x] making sure that none of the browser console errors when using Gutenberg are the result of this plugin

[benlk]

On the subject of the browser console errors, hard to tell.

• [x] the block should save something in the post content that isn't just an empty block. Like, at barest minimum, the URL.

It's disconcerting to deactivate the plugin and see nothing where a block used to be, just an empty "Classic" editor.

[benlk]

• [ ] https://github.com/WordPress/gutenberg/blob/master/packages/i18n/README.md
• [x] make the activation script in the footer pluggable, for https://github.com/INN/pym-shortcode/issues/19

[benlk]

Internationalization is blocked by insufficient Gutenberg docs; see https://github.com/INN/pym-shortcode/issues/40.

[benlk]

Okay, state of this PR:

Changes

• Adds a "Pym Embed" block for use in Gutenberg. PR #34 for issue #28.
• Shortcode now gains an align="" parameter, so that WordPress's generated alignment CSS classes can be used on embeds. By enabling this in the shortcode, the Gutenberg Block also gains support for alignment. PR #34
• Script tags for embeds are no longer output by the_content(), instead being output during wp_footer() by closures hooked on the 'wp_footer' action. PR #34 for issues #33 and #35.
• The source URL for pym.js is no longer output by the_content(), instead being output during wp_footer by an action dedicated to the task. If different shortcodes and/or blocks on the page specify different source URLs for Pym.js, all are output (after removing duplicates), but a message is logged in the browser console. If WP_DEBUG is set, this message is also logged to the server log, with the post ID specified. PR #34 for issues #33 and #35. See https://github.com/INN/pym-shortcode/tree/master/docs#ive-set-a-different-pymsrc-option-but-now-im-seeing-a-message-in-the-console
• The script tag used to run new pym.Parent is now configurable. By replacing the pluggable function pym_shortcode_script_footer_enqueue() with your own function, you can now use alternate forms of embed code that may be required for PJAX sites or custom versions of Pym.js. This resolves issue #19.
• Docs improvements:
  • docs in README.md are merged into the docs in docs/readme.md.
  • all parameters of the shortcode/block are now documented
  • new and improved content hierarchy in the docs

New issues created

to be addressed before the next release

• rename plugin https://github.com/INN/pym-shortcode/issues/39

deferred

• add internationalization https://github.com/INN/pym-shortcode/issues/40
• add block transforms from shortcode https://github.com/INN/pym-shortcode/issues/38
• add block transform to generic embed https://github.com/INN/pym-shortcode/issues/37
• use gutenberg native anchor support https://github.com/INN/pym-shortcode/issues/36

[benlk]

Changes to docs:

• [x] TOC
• [x] flag the one required option vs the many optional options