Block: Hand-picked Posts

[jwold]

Feature description

Display a number of hand-picked posts as a content block. Similar to Recent Posts, this will display the posts as individual cards.

---

Do not alter or remove anything below. The following sections will be managed by moderators only.

Acceptance criteria

Adding the block

• The block can be added from the block library, and should appear under Material Blocks
• The icon should be library_books from: material.io/resources/icons
• The description for the block: Display a list of your hand-picked posts.
• Block preview in the block library: None

Editing the block

• Before you can see any posts you must pick from a list of published posts
• In this edit window you should see the block title, icon, and description
• In this edit window you should have the ability to search, and scroll through a list of posts.
• Entering a query for a post should narrow the selection in the scrollable window to results matching the query.
• Pressing the checkmark icon or the post title should change it to a selected post
• Selected posts should be visible in the middle of the edit window as a list of posts, they should also appear in the scrollable area as check marked.
• Selected posts can be cleared individually or all at once
• This edit window may be returned to at any time by pressing the pencil icon in the block block toolbar
• Once you've selected the posts, you can select the done button to move onto a preview of the block.
• There is no maximum for how many posts can be selected.
• The fonts, radius, colors, and icon type can be changed from the Customizer

Previewing the block

• The posts will appear as cards, which default to a Masonry style, 3 columns, and text above media
• Within the block preview you may not interact with the preview, other than testing the ripple effect.
• From the block toolbar you may change the width of the block between Normal Width, Wide Width, and Full Width

Block settings

• From the block sidebar you may set the styles between Masonry, List, and Grid
• On list mode images should be cropped to square
• Columns may be adjusted from 2-4
• Content layout may be adjusted between text above media, text over media, text under media. These will adjust the placement of the headline and subtitle in relation to the post image. These variants should be matched in the web component demo. https://material-components.github.io/material-components-web-catalog/#/component/card?type=basic
• The block elevation can be changed from outlined to elevated
• The post meta settings can be enabled or disabled: post date, post content, featured image, comments count, post author.
• The excerpt is controlled by a slider input, with a default value of 20 words, a min of 10, and a max of 30.
• Post order defaults to newest first, but can also be set by alphabetical, or most comments.
• You can also edit the posts selected in the block settings sidebar.

Prototype:

Figma link

Implementation brief

• In JavaScript:
  • Register a new Gutenberg block called "Recent Posts" under the "material" category
  • Since this block is sharing some functionality and components from the "Recent Posts" block, that block will need to be refactored to allow sharing of the components which are:
    • assets/src/block-editor/blocks/recent-posts/components/inspector-controls.js: This component will need a toggle to show the 'Filtering' panel for category when used in the Recent Posts block and showing the selection of individual posts in the left hand side panel when used in the Hand-picked Posts block.
    • assets/src/block-editor/blocks/recent-posts/components/style-icons.js
  • The edit property of the block will render a Placeholder component that will be allow the user to select individual posts and manage them (removal). When the user will finish the posts selection he will click on a done button which will remove the Placeholder component and use the ServerSideRender component to render the selected posts in a similar fashion as with the Recent Posts block. The ServerSideRender handover the rendering to PHP. An example of implementation can be found in the code of the Woocommerce Handpicked products block
• The Placeholder component allowing the selection of the posts should save the posts ids inside an a block attributes so the PHP backend will create a WP_Query based on these ids to get the list of posts
• The CSS from the "Recent Posts" block will also need to be moved to a common location to be shared with this block.
• In PHP, a new class for this block similarly to the php/blocks/class-recent-posts-block.php class should be created. The 2 classes should be refactored extend a base class that will allow sharing the common feature of this 2 classes as nearly all the functionality will be the same except for the arguments of the WP_query.

QA testing instructions

Note 1: With most of these changes you'll also want to see if the frontend is working, and not just the Gutenberg preview. It's possible there are discrepancies.

Note 2: For now we're just testing with the theme set in the staging env,

Adding the block

• Add a new block and search for a few posts from the search window, select a few of them.
• Remove your search query and select a few posts from the scrollable list. Ensure the list is long enough to scroll through and that it functions as expected.
• Try clear all with the selected posts
• Try removing a few of the posts
• Select done
• Go to post-settings and see if the above steps all work from the sidebar
• Try coming back to this window via the pencil icon

Previewing the block

• Ensure the ripple effect works as expected

• Verify that posts function in all 3 styles and all 3 content layouts with and without images

• Test against the card component to validate whether the block overall follows the card guidelines https://material.io/develop/web/components/cards/

• Ensure that the 3 styles appear as expected

• Ensure that columns work as expected

• Ensure that the width options in the block toolbar function correctly

• Ensure that each of the post meta settings appear as expected

• Test the post orders, may require adding comments to a few posts, and verifying the post publish dates

• Test whether the block changes when the font, radius, colors, and icon type are changed in the Customizer

Demo

• Hand-picked Posts Block Video Demo

Changelog entry

[jwold]

@davidlonjon do you have availability to pick this up for Sprint 2? If so, can you write the implementation brief and move it to Review?

[davidlonjon]

@ravichdev,

I have added the implementation brief for it. I ran out of time a little bit today so did not go into details. I am not sure if sufficient.

cc @jwold

[davidlonjon]

@jwold , I don't think we will be able to achieve the requirement: "Hovering over a Post title in the edit window will display a tooltip for the Post ID" for MVP as the posts list in the edit mode is provided by an external component from WooCommerce which we cannot modify without embedding into our repo but this will take a long time. I don't think this is a critical feature, so I'll rather have it out for MVP. Is it ok? cc @ravichdev

[jwold]

@davidlonjon I agree this doesn't need to be MVP. Thank you! :)

[jwold]

@davidlonjon we discussed the benefit of having hand-picked pages or custom post types. Is this something that would need to be a new issue? It feels like that, but wanted to get your feedback first.

[davidlonjon]

Hi @jwold, It should be a new issue. Also, we might want to consider to make them different blocks (one for pages and one for CPT) too (?) as it would make the blocks simpler as well as clearer from the user's perspective. cc @ravichdev

[jwold]

Found an issue with QA on staging:

1. New posts appear to not show up: https://v.usetapes.com/hGbVaSukZU

cc @davidlonjon

[davidlonjon]

@jwold ,

Today I did some investigation and I think what you've reported with "New posts appear to not show up", is due to the following issue #128 which is quite a big one. I have submitted a PR for it #129 which should hopefully fix this.

cc @ravichdev

[davidlonjon]

@jwold: This issue "New posts appear to not show up:" should now been fixed as it was due to the bug that I mentioned above and the fix has now been merged

[jwold]

Awesome. Thanks so much!

[jwold]

@csossi this issue is ready for QA as well. Thanks!

A few quick notes:

• There is a visual issue where spacing is off in the default edit window as well as when you search.
• This visual padding issue is also affecting the block settings sidebar post settings.
• For visual inspiration on how this should look try out the hand-picked reviews block from WooCommerce
• The tooltip for post ID appears to not be working at the moment

[davidlonjon]

Hi @jwold, @csossi ,

I think our Material theme might impact the look of the edit mode of the block as on my local it looks like

but on the test environment it looks like

I think there is an alignment issue.

Also here is a video showing how the our material theme is affecting the alignment control (though I cannot replicate what we are seeing on the test environment as shown on the screenshot above):

https://cloudup.com/cnBu4jtRiIJ

Maybe it would be worth trying to switch the theme to Tweenty Tweenty on the test environment to check if the issue still remains as it could be something with the plugin too.

cc @emeaguiar , @ravichdev

Finally, Joshua the tooltip for post ID will not work for MVP as this block is making use (as a module dependency) of a component from WooCommerce which we cannot change. We would have to embed the specific import completely inside our repo and then we could modify for our purpose, but it will be a lot of work because of the way they build the styles with Sass. I am not sure it would be worth the effort for showing the Post ID tooltlip. In any case this cannot be done for MVP.

[jwold]

Thanks for the update David!

I am not sure it would be worth the effort for showing the Post ID tooltlip. In any case this cannot be done for MVP.

Agreed. Let's pass on this.

[emeaguiar]

@davidlonjon I'll take a look to see what's happening

[emeaguiar]

@davidlonjon ~is that alignment button not available in develop yet? It's not appearing in my local install, do I need to activate an option?~ Realized that is the issue.

Also, I've confirmed that the test site alignment of the edit screen looks the same even with the Material Theme deactivated, so something else is going on in there:

https://share.getcloudapp.com/p9u7g6ld

[emeaguiar]

After some research it seems the theme needs to enable support for these widths. So this is not exactly a bug. I'll work on adding support.

[emeaguiar]

I have a PR in the repo to add alignment support: xwp/material-theme-wp#41 it'll be visible in the testing site once it's merged.

[csossi]

@jwold

When I use the Search tool to search for posts, there's some cutoff along the bottom edge of design panel - unable to scroll (was using Win10/Chrome):

[csossi]

@jwold

When I use the "clear all" under Posts in the design panel, the posts clear, but hangs on the "loading"/"working" animation:

[jwold]

When I use the Search tool to search for posts, there's some cutoff along the bottom edge of design panel - unable to scroll (was using Win10/Chrome):

It appears that two-line post titles are being cutoff: https://d.pr/i/6oaS2x. Can we increase line height of the item, or something like that?

When I use the "clear all" under Posts in the design panel, the posts clear, but hangs on the "loading"/"working" animation:

I wonder if we should set the hand-picked posts back to the edit mode, so that users can then pick again?

cc @emeaguiar

[jwold]

Going to move this to complete. We can always open a new ticket if that QA issue appears.