[WIP] Introduce amp-story support via Gutenberg blocks

[westonruter]

👉 Development of has been picked up in #1884.

---

As a developer for the AMP for WordPress plugin, I need introductory support for managing AMP stories via Gutenberg blocks.

• AC1: Introduce a general structure and schema to what a block is, in relationship to new "presentation types" inside Gutenberg.
• AC2: Propose a UI that could work using this general structure.
• AC3: Store the "AMP story" as a custom post type.
• AC4: Inform Implement AMP Stories #968 of any progress, and break out any new tasks as needed.

Subtasks:

• Create system for editing AMP Story grid layers while they appear on top of each other (see [amp-stories sub-task] Grid layers layout #1347);
• Add default background settings (color) for AMP Story Page block (see [amp-stories sub-task] Add background color to amp-story-page block #1380);
• Animations for frontend (see [amp-stories sub-task] Add front-end animation. #1385);
• UI fixes (see [amp-stories sub-task] UI fixes. #1388);
• the “Classic Editor” option should not be available for AMP Stories;
• Fix selection of layers (selectBlock);
• Finalize styling;

---

❗️ Note that no design/UX have been incorporated into this PR yet. As of now it is purely an exploration into the technical details of using Gutenberg blocks for implementing an AMP Story editor.

This PR introduces an amp_story custom post type, and when editing this post there are <amp-story-page> and <amp-story-grid-layer> blocks that can be added, with generic blocks allowed in the latter as depicted in the AMP Story docs:

Inspired by the color scheme above, the blocks are color-coded (for testing, except got the blue and green colors reversed) as followed:

A custom template is made available for the amp_story post type which renders out the standalone <amp-story>:

See #968.

[westonruter]

Rebased to fix merge conflicts.

Some problems with the current implementation:

• After inserting an amp-story-page it is difficult to add the first amp-story-grid-layer block inside of it.
• It is difficult to select the amp-story-page block to insert a new amp-story-grid-layer block inside of it. There should be a block template for amp-story-page.
• I can erroneously insert an amp-story-page block inside of an amp-story-grid-layer block.
• I can erroneously insert an amp-story-grid-layer block inside of another amp-story-grid-layer block.
• I can erroneously insert an amp-story-grid-layer as a root block, not under an amp-story-page.

[westonruter]

I thought I found a solution to the problem to being able to erroneously be able to insert an amp-story-page at any level other than the root by specifying the allowedBlocks as well as the parent block: 9cd428e. However, this resulted in an infinite recursion error:

Maximum update depth exceeded. This can happen when a component repeatedly calls setState inside componentWillUpdate or componentDidUpdate. React limits the number of nested updates to prevent infinite loops.

"Invariant Violation: Maximum update depth exceeded. This can happen when a component repeatedly calls setState inside componentWillUpdate or componentDidUpdate. React limits the number of nested updates to prevent infinite loops.
    at invariant (https://src.wordpress-develop.test/wp-content/plugins/gutenberg/vendor/react-dom.24169eaf.js:59:15)
    at scheduleWork$1 (https://src.wordpress-develop.test/wp-content/plugins/gutenberg/vendor/react-dom.24169eaf.js:16799:11)
    at Object.enqueueForceUpdate (https://src.wordpress-develop.test/wp-content/plugins/gutenberg/vendor/react-dom.24169eaf.js:11914:5)
    at t.Component.forceUpdate (https://src.wordpress-develop.test/wp-content/plugins/gutenberg/vendor/react.832d746b.js:542:16)
    at t.value (https://src.wordpress-develop.test/wp-content/plugins/gutenberg/build/components/index.js?ver=1531156454:37:139734)
    at updateClassInstance (https://src.wordpress-develop.test/wp-content/plugins/gutenberg/vendor/react-dom.24169eaf.js:12340:18)
    at updateClassComponent (https://src.wordpress-develop.test/wp-content/plugins/gutenberg/vendor/react-dom.24169eaf.js:13731:20)
    at beginWork (https://src.wordpress-develop.test/wp-content/plugins/gutenberg/vendor/react-dom.24169eaf.js:14402:14)
    at performUnitOfWork (https://src.wordpress-develop.test/wp-content/plugins/gutenberg/vendor/react-dom.24169eaf.js:16441:12)
    at workLoop (https://src.wordpress-develop.test/wp-content/plugins/gutenberg/vendor/react-dom.24169eaf.js:16480:24)"

So I've reverted that.

Opened issue in Gutenberg to allow for parentless-blocks: WordPress/gutenberg#7845

[westonruter]

It is difficult to select the amp-story-page block to insert a new amp-story-grid-layer block inside of it. There should be a block template for amp-story-page.

I believe this is mostly fixed by cd9cdbe.

[jwold]

@westonruter I've been thinking through the UI implications a bit today. I'm not quite sure about the layers aspect, so I'd like to chat about that further. You can see some of my sketches below:

[westonruter]

Regarding the sidebar tabs, I think “Document” and “Block” should remain for consistency. I'm not even sure there is an API to change those in Gutenberg. The Block tab would be whatever is currently selected, whether that be a page, layer, or content. That being said, last time I checked it was somewhat difficult in Gutenberg to select the nesting blocks for page and layer so there should perhaps be additional helpers added for selecting the parent blocks. So if you are selecting a paragraph, there could be tabs to navigate up to the layer and up to the page. But then again, this really should be facilitated by Gutenberg itself out of the box.

Do pages need settings?

Yes, they do. A page can have various attributes that need to be managed in the sidebar: https://www.ampproject.org/docs/reference/components/amp-story#attributes_1

It's interesting how you have the pages displayed one at a time as opposed to being shown in a vertically-stacked list. I think that could work, but it might also make it harder to get a high-level overview of all the pages in a document, as well as re-ordering the pages using the normal Gutenberg re-ordering controls. I think such a stacked UI would be better for layers on a page as opposed to the pages themselves.

[jwold]

Quick question @westonruter, could Layer and Page settings be included in the same area? Trying to understand why they would need to be selected differently or have settings in different areas.

It seems they always have a direct relationship to each other. Are there situations where a page could have 2 layers? Or a layer is across 2 pages?

[felikscat]

Hi,
I say shortly and I will have hope you are understand. They need to work in model:
Matrix in Matrix to be safe :)

If you will have any question or needs please let me know I will help with pleasure.

Of course my job I will do also but just let me know what to do to do not double our yobs.

Thanks and to hear you

Also I have names If You know what I mean

[westonruter]

@jwold A page can have one or more layers. It has to have at least one layer, but it can have any number. A layer cannot span pages. So there is a direct hierarchical relationship.

[felikscat]

Hi, I say shortly and I will have hope you are understand. They need to work in model: Matrix in Matrix to be safe :) If you will have any question or needs please let me know I will help with pleasure. Of course my job I will do also but just let me know what to do to do not double our yobs. Thanks and to hear you

…

On Wed, Jul 25, 2018 at 4:22 PM Joshua Wold ***@***.***> wrote: Quick question @westonruter <https://github.com/westonruter>, could Layer and Page settings be included in the same area? Trying to understand why they would need to be selected differently or have settings in different areas. It seems they always have a direct relationship to each other. Are there situations where a page could have 2 layers? Or a layer is across 2 pages? — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#1215 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AIGXa0Z6WThQ7nTeoIyPjQGku04L6ZnDks5uKH8ggaJpZM4Uqjed> .

[westonruter]

@bigmazi I have no idea what you are talking about.

[postphotos]

@jwold and @westonruter, this is looking great so far! Just like our conversation the other day, still have lots of questions around how elements might be moved (sub-blocks?) inside the <amp-story> block, or (almost based on that diagram) it looks like there's a whole new instance of the Gutenberg editor that manages the <amp-story>. In short, If we can give the author a full screen, ot at least large/obvious interface tools that feel intuitive, we'll make the experience in managing these feel as native as possible.

Thanks to you both!

[jwold]

@westonruter and @postphotos I'd love some feedback on this idea (and anyone else who can weigh in)

First, here's the screenshot:

Second, here's my video walkthrough: https://v.usetapes.com/LERPRZwnLk

[westonruter]

@jwold It may be that the need for the tabs here is due to Gutenberg not making it super easy to select parent blocks when nesting blocks. Let's say that we do need the tabs for now to work with that. I think, however, we only need one tab/shortcut: select the page block. And this may be something to propose to fix in Gutenberg itself. It may be that the nesting hierarchy should be exposed in the sidebar, header where each nested level gets its own Block tab (horizontal space availability notwithstanding):

But, given that there can and would be multiple layers, how would you select a specific layer to manipulate? I don't see a way in your mock to manipulate layers yet. If you select the page and open the block settings sidebar there at this point could be a list of the layers in the page. Inside of the sidebar the user could reorder the layers, remove layers, or add new layers (including a final CTA layer). I think this would be easier to work with than try to replicate the block reordering controls for manipulating layer ordering.

This WordPress/gutenberg#7931 issue in [Component] Nested / Inner Blocks may be relevant here as well, since we will probably want to disable the reordering controls for the layer blocks. We'd also potentially need to change the orientation of the reordering controls inside a layer for the blocks when the horizontal template is selected.

[jwold]

@westonruter and @postphotos I'd love some feedback on where I've landed so far with the AMP Stories. Here's a brief video: https://v.usetapes.com/GXK3Q9MvsR

And here's the full wireframe:

[westonruter]

@jwold looking good! Some feedback:

Note that we do not need this button since Gutenberg provides an insertion button itself as standard. Due to child block restrictions, only a page would be available to insert at this point.

We can actually have a new story page created with a layer and paragraph as its initial contents, so the user would not have to insert an initial layer. The PR actually is doing that now via:

https://github.com/Automattic/amp-wp/blob/6e97ede63a98dfb4b8f2ec5541b33e9e64338b97/blocks/amp-story/amp-story-page.js#L14-L27

Tapping the layer would select the layer on the page, to show that layer in isolation and allow its elements to be manipulated. So then to get back to the view of all layers combined, how would the user do this? The button in the layer looks like a radio.

Something else to think about: what is the experience of a user who opens up an existing AMP story to edit? Let's say that this story has a few pages, and on the first page there are 5 layers. What happens when the user clicks on the story with the intention of editing what they click? Should that result in the top-most layer automatically being selected and the others hidden? But then what if they wanted to edit something that appears in the background? That could be jarring as then the thing they want to edit would then just disappear. Also, perhaps upon selecting a page that the sidebar would need to be shown (even if it was closed) so that they could see what the layers are.

[jwold]

@westonruter great points that you brought up. I'm still thinking through them.

In the meantime you can see an updated wireframe that takes into account some of your thoughts:

cc @amedina

[jwold]

Tapping the layer would select the layer on the page, to show that layer in isolation and allow its elements to be manipulated. So then to get back to the view of all layers combined, how would the user do this? The button in the layer looks like a radio.

I was thinking that the radio like button would serve like in Illustrator or Photoshop where it's a target/highlight button to show all elements in that layer. The reason is because I want to be able to edit and change the settings in layers WITHOUT having all the view change everytime I click a different layer, I only want it to change when I change a setting. This is important because I'll likely (as a user) want to click through layers and look at all the options, and having the view changing when I did this would be weird.

In addition, I was thinking "show all layers" would work well to allow users to see all the layers beyond just the one they've highlighted.

What happens when the user clicks on the story with the intention of editing what they click? Should that result in the top-most layer automatically being selected and the others hidden? But then what if they wanted to edit something that appears in the background? That could be jarring as then the thing they want to edit would then just disappear.

Could this be solved by having the other layers go to 50% opacity? They'd still be there, just not fully visible.

Also, perhaps upon selecting a page that the sidebar would need to be shown (even if it was closed) so that they could see what the layers are.

Agreed

[jwold]

@westonruter What would happen if I were to move a layer up and down inside of the AMP Story Page on the left, should it also move the layers around on the sidebar?

[westonruter]

Page 1 of 1

I think in the editor, the pages should be all visible and seen by scrolling down in the window, similar to how slides are presented in presentation apps when in edit mode.

Select to show layer

Actually I think it would be “select to edit layer”. Also, it would have the effect of isolating the layer.

In addition, I was thinking "show all layers" would work well to allow users to see all the layers beyond just the one they've highlighted.

So that would have the effect of clearing the selected radio button? What if there was an actual button that said “Edit” and then this switched do “Done”?

Could this be solved by having the other layers go to 50% opacity? They'd still be there, just not fully visible.

Potentially, yes. We'd also need the non-edited layers to be essentially inert, so that in addition to opacity:0.5 they'd need to be read-only and pointer-events:none so that you click through any layers on top of the layer you're editing.

What would happen if I were to move a layer up and down inside of the AMP Story Page on the left, should it also move the layers around on the sidebar?

I don't think there would be up/down arrows for layers in the editor. The only way to re-order them would be via the sidebar. The arrows with the blocks in the editor would only be for the blocks inside of a layer.

[westonruter]

Related Gutenberg issue: WordPress/gutenberg#7694 (Blocks: Consider a "passthrough" supports for nested block wrappers). This would seem to be seems to be key for the layer blocks.

[jwold]

@westonruter just thinking through another example of an AMP Story. A few questions came up, welcome your thoughts! https://d.pr/v/uZrEQN

cc @amedina

[westonruter]

Another related issue: WordPress/gutenberg#6459 (Show block breadcrumbs for selected block when inline toolbars are enabled)

[westonruter]

@jwold I think the first slide should have the “Your 5-minute fix” and other content as the bottom third of the same layer that has the WaPo logo in the first layer. I don't think these would be pulled from the metadata for the page automatically as a special case for AMP Story, as part of the template. If such automatic-population were desired, then they should create a Gutenberg block for surfacing that information from the post metadata. This is something I know is needed by Gutenberg more broadly for customization, to be able to construct a template entirely with blocks (e.g. title, byline, date, etc).

Something that @mtias pointed out as well that we should think about is how the background image is achieved. In particular, Gutenberg has the Cover Image block currently which allows you to put text over an image:

Nevertheless, the Cover Image block is not flexible enough for replicating that amp-story-page in that AMP Story. In particular, there aren't controls for managing the font size or positioning of the text. The Cover Image block could be decomposed into Image block and a Heading block if Gutenberg allowed them to be layered on top of each other.

The vertical centering of the text on the grid layer is achieved with a custom stylesheet that is doing the following (so is not strictly part of the format):

The caption at the bottom of the page is indeed a separate layer, and it is positioned on the bottom again with custom CSS not unique to the AMP story format:

The text is centered vertically on the last slide with the same custom CSS associated with the text-slide class as per above. The button at the bottom is actually placed by the amp-story-cta-layer.

[googlebot]

So there's good news and bad news.

👍 The good news is that everyone that needs to sign a CLA (the pull request submitter and all commit authors) have done so. Everything is all good there.

😕 The bad news is that it appears that one or more commits were authored or co-authored by someone other than the pull request submitter. We need to confirm that all authors are ok with their commits being contributed to this project. Please have them confirm that here in the pull request.

Note to project maintainer: This is a terminal state, meaning the cla/google commit status will not change from this state. It's up to you to confirm consent of all the commit author(s), set the cla label to yes (if enabled on your project), and then merge this pull request when appropriate.

[googlebot]

A Googler has manually verified that the CLAs look good.

(Googler, please make sure the reason for overriding the CLA status is clearly documented in these comments.)

[googlebot]

So there's good news and bad news.

👍 The good news is that everyone that needs to sign a CLA (the pull request submitter and all commit authors) have done so. Everything is all good there.

😕 The bad news is that it appears that one or more commits were authored or co-authored by someone other than the pull request submitter. We need to confirm that all authors are ok with their commits being contributed to this project. Please have them confirm that here in the pull request.

Note to project maintainer: This is a terminal state, meaning the cla/google commit status will not change from this state. It's up to you to confirm consent of all the commit author(s), set the cla label to yes (if enabled on your project), and then merge this pull request when appropriate.

[westonruter]

Just noticed that the poster image warning is being added to non-story posts incorrectly.

• Limit warning to amp_story post type, and also improve the message to be just, “You must provide a featured image.”

[westonruter]

Closing in favor of #1884 which picks up where this PR left off.