Event dates block and sort UI

[dkoo]

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:

Implements two major features:

• An Event Dates block which can be used only in Newspack Listings Event posts. This lets editors add one or more event dates and optional times (and optionally, end dates/times to create ranges) to event listings as blocks, and these blocks are synced to post metadata so the first date found can be used to sort event listings by date.
• A front-end sort UI which can be turned on for Curated Lists. This UI shows different sort options depending on the list's attributes, e.g. it will show an option to sort by Event Date if the list is set to show only events, it will show an option to sort by author if the list is set to show listing authors, etc.

Also includes a minor design improvement that closes #10.

Also includes a partial solution that might close #8—now, instead of only showing map locations for the first paginated set of results, the map will show locations for all listings that match the query options, up to an absolute maximum of 100 (this can be changed in code, but possibly moved to an admin option to give editors control over this maximum). The absolute max of 100 items only applies to the map locations and editor queries; when viewed on the front-end, a list can still show an infinite number of paginated results, but only the first 100 items will be shown on the list's map.

Not included in this PR is any front-end filtering UI. I think filtering will take a non-trivial amount of additional effort, and this PR has already gotten big enough that we should push that development to another PR.

How to test the changes in this Pull Request:

Event Dates block

This new block allows editors to add one or more sets of dates/times to Event listings. The date data from the first block that appears in the content is synced to post meta so it can be used for WP_Query sorting and search purposes.

1. Create a new Event listing. Observe that the empty event starts with an Event Dates block by default. (This will be added to Event listing patterns in the future).

2. Add some content to the listing post, but keep the Event Dates block empty without selecting a date or time. Publish and view the listing front-end and observe that no markup is rendered for an empty Event Dates block.

3. Add a date to the Event Dates block by clicking a date on the calendar. Observe that the selected date is highlighted on click and that a "Reset" button appears when a date is selected. Test that clicking "Reset" clears the selected date.

4. Ensure that a date is selected. Save and view the post and observe that the date is shown in human-readable form on the front-end. Note: Currently, event dates are always shown in F j, Y date format, regardless of the date format option selected in WP settings. This is to simplify the algorithm I wrote to render date/time ranges. Times are shown in the format selected in WP settings, however.

5. In the editor with the Event Dates block selected, observe an Event Dates Settings panel in the sidebar with two options: Show Times and Show End Date:

6. Enable "Show Times" and observe that the Event Dates block's UI changes to include a time picker UI. (Also observe that certain block settings labels change to say "Time" instead of "Date".) Set a time in the block and save the post.

7. Observe that the human-readable date on the front-end now includes the selected time.

8. Back in the editor, enable the "Show End Time" option. Observe that the block now includes a second calendar to choose an End Time:

9. Try to set an End Time before the selected Start Time (either on the same day but an earlier time, or any day before the Start Time day). Observe that warning appears, preventing you from setting an End Time before the Start Time. Test that this happens whether you click a day on the calendar or try to set a day/time using the input fields:

10. Set an End Time that occurs on a different day after the selected Start Time. Update the post and view on the front-end. Observe that the selected times are rendered as a human-readable time range:

11. Update the End Time so that it occurs on the same day as Start Time, but at a later time. Update the post and observe that the human-readable time range is now condensed:

12. Back in the editor, disable the "Show Times" option. Observe that the time picker UI disappears, and that the calendars for both Start Date and End Date now have the same day selected. Update the post and view on the front-end. Observe that only one date is shown (because the start and end dates are the same):

13. Change the End Date to another day but in the same calendar month as Start Date. Update and view the post on the front-end, and observe that the dates are shown as a range:

14. Change the Start Date so that it occurs in a different month but in the same calendar year as End Date. Update, view post, observe that the range shows both months:

15. Now change the Start Date or End Date so that they occur in different years. Update, view post, observe that the range now shows the full dates for both start and end:

16. Add the Event to a Curated List in another post or page. Confirm that when the event appears in the list editor, its excerpt is pre-pended with the Event Dates and that the Event Dates are always rendered exactly as they appear on the Event's front-end (test with various ranges and Event Dates block options):

17. Also view the Curated List on the front-end and confirm that the Event Dates are still rendered there the same way (test with various ranges and Event Dates block options).

18. Confirm that if an event has multiple Event Dates blocks with valid dates/times/ranges, they will all be pre-pended to the excerpt when added to a Curated List, in the order they appear in the event listing's post content:

Sort UI

Editors can now optionally add a sort UI to any Curated List block. The sort-by options are dynamic based on the block's attributes.

1. Ensure that you have a number of listing posts of various types. Specifically, make sure you have different listings set to at least a few different authors, and at least a few Event listings containing Event Dates blocks with various combinations of dates, times, and ranges as described in the Event Dates testing instructions above.

2. Create a new Curated List in any post or page.

3. Select Query for the first test. Set any query options that will allow at least several listing items to render in the list. Under Query Settings, enable the Show load more button option and set the Max number of items to something that will cause the list items to paginate. Note that the default sort options for queried listings is by Publish Date in descending order (most recent first).

4. Under the List Settings sidebar panel, observe a new option for Show sort UI:

5. Enable the option. Note that a non-interactive dummy representation of the sort UI appears in the block:

6. Save the post and view the front-end. Observe that a sort UI is rendered at the top of the list:

7. For Curated List blocks with default attributes, only Publish Date, Title, and Listing Type options are available in the Sort by dropdown. For Curated List blocks in query mode, confirm that Publish Date and Descending options should be selected by default, matching the default query. Click the "Load more" button to load all listings and note the order of all items.

8. Try selecting the "Ascending" option. Note that the list enters a loading state and after a few seconds, the listing items should re-render to sort by Publish Date in ascending order (oldest items first, reverse of the default). Confirm that the items are paginated again, but that the results are not constrained to the first set of default results. In other words, the first item should be the last item in the list after you had clicked "Load more" enough times to load all items in the previous step. Click "Load more" again until all items are loaded and ensure that all items are in the expected sort order by ascending publish date.

9. Select the "Title" sort-by option, and repeat the above two tests. Title+Ascending should render listing items in alphabetical order by title, Title+Descending should be in reverse-alphabetical order.

10. Select the "Listing Type" sort-by option and repeat the tests. This option groups the items in the list by type so that Events will appear first, then Generic listings, then Marketplace listings, then Place listings (when Ascending is also selected). This option is only available when the listing type is set to "Any" under Query Settings for the list.

11. Edit the post again. Under Query Settings, set Listing Type to a single listing type. Try Marketplace, for example. Under Meta Settings, enable the Show Author option. Save the post and view the front-end.

12. When the list loads again, it should still be set to Publish Date and Descending by default. This time, open the "Sort by" dropdown and observe that there's no longer a Listing Type option (because we set the list query to show only a single type) and there's now a new option to sort by Author.

13. Select the Author option and test that the listings render in the expected order, grouping posts by author.

14. Edit the post again. Under Query Settings, click the Show advanced filters button. Change the Sort By and Sort Order options to something other than the default. (Also confirm that the options change depending on the other block attributes—e.g. if you change Query Settings > Listing Type or toggle on/off the Show Author options).

15. View the front-end and observe that not only do the listing items render at page load in the order you specified, but that the same Sort by and Sort order options you selected in the editor are selected on the front-end by default.

16. Edit the post again. Under Query Settings, set Listing Type to Event so that only event listings are rendered. Ensure that at least some of the events have Event Dates blocks with valid dates/times/ranges.

17. Under Query Settings, click the Show advanced filters button. Expand the Sort By dropdown and observe that there's a new option for "Event Date". Select that option and observe that the listing items re-render in order of the first start date in each listing. Test the ascending/descending options and confirm that the list re-renders in the expected order.

18. View the front-end. Observe that the "Event Date" option is selected by default, and that the listings are rendered in the same order as in the editor, by the first state date of each listing. Test the ascending/descending options and confirm that the list re-renders in the expected order.

19. Create a new Curated List in the same post or another post. This time, choose Specific Listings instead of query mode.

20. Manually add several listings of various types to the list and enable the "Show sort UI" option.

21. View the list on the front-end. This time, observe that the "Sort by" dropdown has a new option called "Default" which is selected on page load. Also observe that "Sort order" radio buttons are disabled to start (this is because there is no ascending/descending order when the listing items are added manually). Lastly, observe that the "Listing type" option is always available for curated lists in Specific Listings mode—this is because it's hard to guess whether or not a manually curated list contains more than one listing type, without a query.

22. Change the "Sort by" dropdown to a different option. Observe that the "Sort order" radio buttons become interactive when any option other than Default is selected. Confirm that the the listing items render in the expected order with each "Sort by" and "Sort order" option selected.

23. Select "Default" again. Observe that the items return the order to the original, manually curated order and the "Sort order" radio buttons become non-interactive again.

24. Test the sort UI with AMP both enabled and disabled—sort UI behavior should be the same.

Testing the map locations fix

Maps associated with Curated Lists in query mode with more than one page of results will now show locations for up to 100 listing items, regardless of the number of listing items shown per page.

1. Create a new Curated List post in Query mode and ensure that the query settings show enough listings to paginate the results when the Show "load more" button option is enabled. Ensure that at least some of the listings that render on pages after the first page of results have Jetpack Map blocks with locations set.

2. Toggle the Show map option ON. Confirm that the map is created with locations for all of the listing items that match the query, not just the ones shown in the first page of results (up to a max of 100).

3. Save and view the front-end. Confirm that the map shows all locations here, too.

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?

[jeffersonrabb]

I saw only one tiny thing which shouldn't block landing this.

For Curated List blocks with default attributes, only Publish Date, Title, and Listing Type options are available in the Sort by dropdown. For Curated List blocks in query mode, confirm that Publish Date and Descending options should be selected by default, matching the default query. Click the "Load more" button to load all listings and note the order of all items.

Listing Type will not be included in the Sort by select unless the Query Settings Listing Type has been interacted with (changed from Any to something else and back again). If it's left untouched in Any state, the Sort by select won't include it.

[matticbot]

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

The release is available on GitHub release

Your semantic-release bot 📦🚀

[matticbot]

🎉 This PR is included in version 1.0.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀