feat(collections): add Collections block

[rbcorrales]

All Submissions:

• Have you followed the Newspack Contributing guideline?
• Does your code follow the WordPress' coding standards and VIP Go coding standards?
• Have you checked to ensure there aren't other open Pull Requests for the same update/change?

Changes proposed in this Pull Request:

This PR adds a new block for displaying Collections with customizable layout and filtering options.

Query options:

• Recent collections with category filtering and offset
• Specific collections with manual selection via autocomplete

Layout and display options:

• Grid layout (responsive 2-6 columns)
• List layout with configurable image alignment (top/left/right)
• Image sizing for list layout: small, medium, large
• Toggleable display of all fields, like featured image, title, categories, excerpt, volume/number/period metadata
• Configurable CTAs with subscription/order toggles and specific CTA filtering
• Editable "See All" button linking to collections archive

Technical details:

• Hybrid block with React editor components and PHP server-side rendering
• Integrates with the existing REST API for the live editor and extends the CTA fields in the JSON response
• Modular component architecture
• Integration with existing Query_Helper and Template_Helper classes

ToDo:

• Currently, the block can also be used in the Collections archive template, as the design should visually match 1:1 (with the appropriate settings), but it will be missing pagination. This would be nice to have to be able to use this block to render the same Collection components everywhere.
• Unit testing
• Add the ability to render iframes with the digital editions

Closes NPPD-797.

How to test the changes in this Pull Request:

1. Ensure the Collections module is active. The block only registers when Collections::is_module_active() returns true.
2. Create or edit a post/page. Go to the editor and add a new Collections block in the block inserter.
3. Test default configuration. Verify the block displays 4 collections in a 4-column grid layout with no excerpts, all metadata enabled (volume/number/period), and 1 CTA per collection.
4. Test Query Settings panel. Switch between "Recent Collections" and "Specific Collections" query types, set the number of collections, adjust the offset for recent collections.
5. Test category filtering for recent collections. Use the "Include Categories" and "Exclude Categories" autocomplete fields to filter collections by category.
6. Test specific collections selection - When the query type is "Specific Collections", use the autocomplete field to search and select individual collections by name.
7. Test Layout Settings panel. Switch between Grid and List layouts, adjust columns for grid (1-6), test image alignment for list (Top/Left/Right).
8. Test image sizing for list layout. When the layout is List, verify the Image Size control appears with Small/Medium/Large options and affects image dimensions accordingly.
9. Test Display Settings panel. Toggle each display option: Featured Image, Title, Category, Excerpt, Period, Volume, Number, CTAs and "See All" Link.
10. Test CTA controls - Adjust "Number of CTAs", toggle "Show Subscription URL" and "Show Order URL", test "Specific CTAs" field with comma-separated CTA labels.
11. Test the section header. Click the placeholder text at the top of the block to add an editable section header.
12. Test "See All" button customization - When "Show See All Link" is enabled, edit the button text via the "See All Link Text" field.
13. Test frontend rendering. Verify the block displays correctly on the frontend with consistent styling and functionality matching the editor preview.
14. Test responsive behavior. Check that the grid layout responds properly: 2 columns on mobile, 3 on tablet, and respects column setting on desktop (960px+).
15. Test category links. On the frontend, click category tags to verify they link to collections archive with category filtering (/collections/?category=slug).
16. Test block example preview. Insert the block and verify it shows the example configuration with "Featured Collections" header and 4 collections in grid layout.

Other information:

• Have you added an explanation of what your changes do and why you'd like us to include them?
• Have you written new tests for your changes, as applicable?
• Have you successfully ran tests with your changes locally?

[thomasguillot]

@rbcorrales I pushed a bunch of changes to the block. I have one question... why do we need a sectionHeader? Surely it can be a standalone heading block, or am I missing something?

[rbcorrales]

@rbcorrales I pushed a bunch of changes to the block. I have one question... why do we need a sectionHeader? Surely it can be a standalone heading block, or am I missing something?

Hey @thomasguillot indeed, this could be achieved using a separate block. I just followed the pattern of the Content Loop block for consistency, which also allows you to include a header in the block itself. Do you think it's better to remove it?

[thomasguillot]

@rbcorrales The Content Loop block uses it as a quick way to add section headers so you can stack different sections on a page (that said, I’m not really a fan of having the header baked into this block either).

Anyway... for Collections, I think the use case is a bit different (it's unlikely we're going to stack multiple Collections blocks together) and it probably doesn’t need one.

[rbcorrales]

@thomasguillot done. Header removed with 816599f.

[thomasguillot]

@rbcorrales thank you!

[dkoo]

@rbcorrales This is some great and comprehensive work so far! The major functionality is mostly looking good to me. I ran into a handful of minor issues, many of them visual. I'll list in order of descending importance:

1. The category links aren't working for me. Clicking on a category flag sends me to a URL that looks like this: https://siteurl/collections/?category=collection-category. On my site, which had Jetpack Search enabled, it led to a page that looks like this:

After this I disabled Jetpack Search and refreshed permalinks, but then the links only led me to the main Collections archive page showing all collections, without filtering by category.

2. The front-end styles for the "See all" buttons don't look right to me. On my site, I have these colors set in Newspack > Settings > Theme and Brand:

In the editor, the button correctly shows with the #3c434a background color and a white text color:

But on the front-end, it renders the text as the same color as the background, making it invisible until I hover:

I think it has to do with the anchor tag not inheriting some theme styles for buttons. Some custom CSS may be required to make this more closely match the button.wp-block-button__link styles.

3. If showing CTA(s) while not showing excerpts, there could be a little bit of whitespace above the first CTA. (This next one is probably an edge case, but if you only show Category + CTAs, the first CTA button ends up overlapping the category flag). Also, if the block is set to display columns, I'd consider making the CTA buttons the full width of the column, what do you think? (cc @thomasguillot)

4. (non-blocking) I'm not so sure about the "Specific CTAs" UI being a text input field. Aside from being a little strange conceptually, I notice it's very strict in terms of matching the exact label string, such that if I enter "subscribe" it matches/shows a "Subscribe" CTA but not a "Subscribe now" CTA. @thomasguillot do you have any ideas for improving this UI?

5. (non-blocking) Do we need a text size attribute like we have for Content Loop?

[thomasguillot]

I'd consider making the CTA buttons the full width of the column, what do you think?

Yes, I agree

[thomasguillot]

(non-blocking) I'm not so sure about the "Specific CTAs" UI being a text input field. Aside from being a little strange conceptually, I notice it's very strict in terms of matching the exact label string, such that if I enter "subscribe" it matches/shows a "Subscribe" CTA but not a "Subscribe now" CTA. @thomasguillot do you have any ideas for improving this UI?

I wonder if we could use an Autocomplete Input that allows multiple selection?

[thomasguillot]

(non-blocking) Do we need a text size attribute like we have for Content Loop?

@rbcorrales would it be easy to copy this from the Content Loop? (including the CSS for the text sizes)

[rbcorrales]

Thanks for your review @dkoo!
Some comments:

The category links aren't working for me. Clicking on a category flag sends me to a URL that looks like this: https://siteurl/collections/?category=collection-category. On my site, which had Jetpack Search enabled, it led to a page that looks like this:

This was due to a change in the query string structure from a hotfix precisely for Jetpack Search. In the subsequent PRs, I brought that change in, so it should be working fine.

If showing CTA(s) while not showing excerpts, there could be a little bit of whitespace above the first CTA.

I rewrote a bunch of the styling in the subsequent PRs too 😅
Let me know if this is still an issue.

Also, if the block is set to display columns, I'd consider making the CTA buttons the full width of the column, what do you think?

I agree, if @thomasguillot agrees, but the thing is that I'm also using this block to render the grid on the archive template now (in the other PRs), so that would also affect the rendering of the grid in those other places, and I'm not sure of how it could affect existing customers already using the functionality.

I'm not so sure about the "Specific CTAs" UI being a text input field. Aside from being a little strange conceptually, I notice it's very strict in terms of matching the exact label string, such that if I enter "subscribe" it matches/shows a "Subscribe" CTA but not a "Subscribe now" CTA

It could be, but it would require some extra logic on a custom component, because it's trying to match that against a custom meta that was precisely set loosely with a link and a label, to accommodate all the possible migration scenarios for different customers.

[rbcorrales]

I agree, if @thomasguillot agrees, but the thing is that I'm also using this block to render the grid on the archive template now (in the other PRs), so that would also affect the rendering of the grid in those other places, and I'm not sure of how it could affect existing customers already using the functionality.

Disregard this. I realized it was working like that before and at some point, I probably broke it. I'll make it fill the whole width.

[rbcorrales]

@dkoo the CTA width was fixed on 6d2ef90, part of #4179. Let me know if it works as expected now.

[rbcorrales]

About the "See all" button color, it's rendering correctly in the editor because it's a richtext, instead of a button (I made it editable at some point, but ran into issues when rendering, so it's a leftover).

But what I noticed on the page is that it's only setting the white color when the link is visited:

So if you haven't visited it, it will render the text with var(--newspack-theme-color-secondary-against-white) color by default, and it doesn't look like I'm adding custom styles for this button. Is this maybe a theme color issue? cc: @thomasguillot

[thomasguillot]

I’m wondering if the “See all” button really makes sense as part of this block. Right now it’s pretty basic and doesn’t offer much customization. An alternative could be to turn it into its own block (something like a “Collections Archive Button”), with customization options similar to the Button block—style, colors, padding, width, radius, etc.

This would give publishers more flexibility: they could build more complex layouts (for example, a row with a heading + this new button, followed by the Collections block), or even place a “See all issues →” button anywhere on a page.

[rbcorrales]

@thomasguillot I agree, similar to the previous heading field, it probably doesn't make sense to keep the "See all" button bundled into the block. Conceptually, it's more of a call-to-action than part of the content itself, but creating a dedicated "Collections Archive Button" block feels like it might be over-engineering, since the core functionality that would make it different is just a link to the archive. From a pattern perspective, we should usually try to avoid introducing narrowly scoped one-off blocks when the same result can be achieved with an existing, more general component (like the standard button block).

I vote for removing the button altogether. Yay or nay?

[dkoo]

creating a dedicated "Collections Archive Button" block feels like it might be over-engineering, since the core functionality that would make it different is just a link to the archive.

I agree with this—it seems to me like this should just be a standard Button block pointing to the Collections archive URL, no?

[rbcorrales]

I agree with this—it seems to me like this should just be a standard Button block pointing to the Collections archive URL, no?
Yes, and it could be even achieved with block composition via patterns in the editor if needed.

I also removed the "See all" link in this commit, on a separate feedback branch that I will use to create a PR soon to address multiple items without further blocking these PRs.

[dkoo]

Approving since the feedback is being addressed in the feat/collections-block-feedback branch!

[github-actions]

Hey @rbcorrales, good job getting this PR merged! 🎉

Now, the needs-changelog label has been added to it.

Please check if this PR needs to be included in the "Upcoming Changes" and "Release Notes" doc. If it doesn't, simply remove the label.

If it does, please add an entry to our shared document, with screenshots and testing instructions if applicable, then remove the label.

Thank you! ❤️

[matticbot]

🎉 This PR is included in version 6.20.0-alpha.1 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

[matticbot]

🎉 This PR is included in version 6.20.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀