Amp-wp: Gutenberg Integration Issues and Shortcomings

[swissspidy]

The current AMP Stories editor is tied closely to the existing post editor as it builds directly on top of it. Thanks to that we get many things for free, but it requires heavy customization and constantly leads to issues.

This issue tries to provide an overview of issues and shortcomings of both the current approach and the Gutenberg dependency in general.

---

Technical

Current and previous examples:

• The “More options” (three dots) menu in the block toolbar can only be extended, but not amended or entirely replaced
• The “More tools & options” (three dots) menu in the upper right corner can only be extended, but not amended or entirely replaced
• All stories-specific UI controls (i.e. toolbar shortcuts, elements box, ‘plus’ icon and reorder icon, as well as the main carousel) have to be inserted using DOM manipulation and are prone to breakage should the markup change
• None of the labels in the UI can be changed, e.g. “Duplicate Block” cannot be renamed to something like “Duplicate Page”
• Unneeded elements (e.g. block mover arrows, block inserters, menu items) have to be hidden via CSS (https://github.com/WordPress/gutenberg/issues/15265, https://github.com/ampproject/amp-wp/issues/3580, https://github.com/WordPress/gutenberg/issues/14215
• Regressions due to changed DOM structure or CSS (#3598, #3580, #2566, #2283)
• Undocumented/Unexpected component changes breaking layout (#3481, #3062, #2703, #2918)
• Normal user interactions suddenly causing unexpected behavior (https://github.com/WordPress/gutenberg/issues/15458, https://github.com/WordPress/gutenberg/issues/16673, https://github.com/WordPress/gutenberg/issues/15883, https://github.com/WordPress/gutenberg/issues/17359)
• It can take a long time to implement features upstream (https://github.com/WordPress/gutenberg/issues/16797)

UI / UX

• Individual block features (e.g. size controls for images) cannot easily be removed without re-implementing the whole block logic (e.g. overriding a block edit component)

[cathibosco]

Consider some of the following usability challenges and thoughts for AMP Stories built on Gutenberg as well:

• Accessibility issues inherent with media management and other aspects of editing

• Editing AMP Stories from a mobile device (is it possible with Gutenberg?)

• Tool bar and Sidebar separating a user's experience of accomplishing a goal or task in two locations (basically tool time is currently a challenge for users that we'll need to overcome)

• Global error handling and admin notification formats = challenges

• Publishing high quality AMP Stories for the web can integrate better with our blog pages and should be easier to share, interact with, and navigate throughout. Does Gutenberg help with this or hinder?

• Building stories right in the dashboard is a huge WIN for WP users and the open web

• Building stories in WP for mobile and desktop consumption is also a huge win for WP users and the open web

[miina]

Don't have a lot of (new) things to add to the extensive list already logged, great notes.

The main problem with the issues related to Gutenberg is that we can't predict the upcoming issues meaning that relying on Gutenberg results in the AMP Stories interface being partly out of our control. We can always adjust it to the current state but it's constantly changing, causing unexpected changes. Not having control over the issues in a tool we're building ourselves isn't probably the best.

Some additional (potentially repetitive) notes:

• New features are being added which are broken / not usable within AMP Stories UI, this means that we have to go through all the changes in Gutenberg to be up to date and aware of what's coming up (e.g. https://github.com/ampproject/amp-wp/issues/2180)

• The default block order is "reverse" in terms of how we're using it in AMP Stories, we have to consider that with navigation; changing the order (https://github.com/ampproject/amp-wp/issues/2057)

• In addition to hiding the features and elements with CSS that we don't need, we sometimes also need to filter the existing logic and add code to remove some features (e.g. https://github.com/ampproject/amp-wp/issues/2304)

• Hard to implement keypress events due to upstream logic which has its own handling and interferes with the handling inside inner elements (e.g. https://github.com/ampproject/amp-wp/pull/3013)

• We are sometimes blocked to develop features due to needing upstream changes first (which can take a long time as indicated by Pascal)

• Sometimes we need just a few changes in an existing component but since it's not extensible, we have to hide the existing element via CSS, then copy most of the logic from Gutenberg with the change we needed (e.g. block mover, previously also block navigation)

• A lot of CSS hackery to force displaying the block vertically.

• Unneeded block settings can't be removed / order changed, can only be hidden by CSS.

• A lot of deprecation logic needed when making changes in the source saved to the content (see https://github.com/ampproject/amp-wp/pull/2906)

• We are filtering the code of Gutenberg quite a lot for doing what we need to do, it can be hard to manage if changes in source needed (see https://github.com/ampproject/amp-wp/pull/2906 or https://github.com/ampproject/amp-wp/tree/develop/assets/src/stories-editor/deprecations/filters)

• We are not really in control of the UX since we can only use the spaces and sidebars and toolbars that are already there from Gutenberg. When we have wanted customization or changed the location of something, it has required hackery (e.g hiding the original element and then creating a new one to a different location as it was with the Block Navigation). In the very first version of the AMP Stories tool, quite a few design ideas were dismissed due to Gutenberg restrictions / having to use what's already available.

• Bugs that are out of our control but influence the UX nevertheless (e.g https://github.com/ampproject/amp-wp/issues/2221)

[jdelia]

Wondering if moving AMP Stories to a separate plugin and outside of Gutenberg editor would be a better option?

[swissspidy]

@jdelia Eventually it will be its own plugin, yes. Whether or not it's going to use Gutenberg is very much determined by this discussion here :-)

[rdm]

I came here looking for how to extend the amp plugin for custom block types built on gutenberg. Please bear with me while I try to express what I think I need to be asking for:

Gutenberg no longer uses the "gallery shortcode", and in amp this seems to correspond to class-amp-gallery-embed.php for gallery shortcode support, and class-amp-gallery-block-sanitizer.php for gutenberg galleries. However, when I run gutenberg's parse_blocks on a post which contains a gallery, a gallery block has a structure with:

• blockName ('core/gallery')
• attrs (which has ids for the images, and maybe ampLightbox=>true)
• innerBlocks (empty in the cases I am working with)
• innerHTML
• innerContent (basically the innerHTML)

Meanwhile the AMP_Gallery_Block_Sanitizer (from gallery-block-sanitizer.php) basically ignores all of this and just parses this innerHTML of this block, based on conventions implemented by the default wordpress gallery implementation. (Possibly this was relevant before gutenberg and what I am seeing here is, thus, legacy code?)

(I was hoping to see that AMP_Gallery_Block_Sanitizer was instead using the values I see in the attrs element returned by gutenberg's parse_blocks() ... and it's seems likely that the current approach offers better support for non-gutenberg content, but...)

Anyways... I need to deploy on a wordpress instance galleries which are not the default wordpress galleries and which can't follow the conventions which the amp plugin is looking for (for reasons not relevant to amp plugin development). And, the gutenberg block system also means that I'm not going to be using shortcodes. So, I am looking for how to extend this plugin to handle custom gutenberg blocks. (And, I'm going to have to do similar work for facebook instant articles... that's not relevant here, except in the sense that it looks like the gutenberg modularity concepts have not yet been used in the way I had hoped to see them used...) But, ... I am unsure about what questions I should be asking.

((Probably, though, I need to know how to build and deploy my own sanitizers, and the calling conventions of the sanitizers? This isn't really a bug report, nor a feature request, but it does seem related to gutenberg integration issues.... so, also... are there good docs for wordpress developers on building our own sanitizers?))