automattic/newspack-listings

Reusable lists using the block editor.

newspack-listings

Create reusable content as listings and add them to lists wherever core blocks can be used. Create static, curated lists or dynamic, auto-updating lists with optional "load more" functionality. Edit display options to control how the list looks and behaves for readers. Compatible with AMP.

Usage

1. Activate this plugin.
2. In the WP admin dashboard, look for Listings.
3. Create and publish listings of any type. Listings can contain any core blocks as content.
4. Optionally tag or categorize your listings to keep them organized, even across different listing types.
5. Once at least one listing is published, add a Curated List block to any post or page.
6. Choose Specific Listings mode to create a static list, or Query mode to create a dynamic list which will automatically update itself when new listings matching the query options are published.
7. Edit list options to control the list's display and behavior.

For more detailed instructions, refer to the public documentation for Newspack Listings.

Development

Run composer update && npm install.

Run npm run build.

Each listing type is a separate custom post type. Configuration is in includes/newspack-listings-core.php.

Metadata for listing CPTs is synced from certain blocks in the post content. See configuration in includes/newspack-listings-core.php for details.

newspack-listings's Issues

Lists: Add Columns Option

The Curated List block in Query mode adds all listings that meet the criteria set in the Listings settings and displays those in one list. For long lists in particular, it would be helpful to include a column view and have the lists dynamically distribute across columns, similar to what we do for the Homepage Posts block.

Option to hide publish date from single listing template

A new option per-post, and maybe a new global setting too.

Update Categories and Tags labels with "Listings" prefix

To distinguish these from regular post categories and tags everywhere they appear in the UI.

Add offset option and/or deduplication

Curated List blocks in query mode currently don't have any offset option nor any awareness of other listings that might be on the page. We should implement the following:

1. Offset option: under "Advanded filters" in query options. This will let editors skip n number of listings that match the query terms.
2. (Optionally) Deduplication of listings like in Homepage Posts and Post Carousel. This would mean that if multiple Curated List blocks appear in the same post, each listing will only appear once across all block instances, even if a listing meets query options for multiple lists.

use componentized Autocomplete Tokenfield from `newspack-components`

Now that this component has been incorporated into newspack-components, once the NPM package is updated, we should update any instances of this component to use the NPM version and remove the duplicate code from this repo.

See here for details: Automattic/newspack-plugin#674

Listings documentation

We need basic developer + public-facing documentation before this plugin can be considered ready to launch.

URL slug settings and redirect rules not working properly

Somehow, the listings prefix in settings is getting dropped when the settings are set to default. The individual listing permalinks still seem to work when the settings are default, but if you change any post type slug, the permalinks drop the prefix but the rewrite rules still expect it, so the permalinks 404.

Listing Patterns for non-business listings

We have a nice set of business patterns for Places, but how about some patterns for other use cases? Definitely open to ideas here.

Marketplace Listings

• Classified ad
• Obituary
• Real estate listing
• Job listing

Events

• Generic event
• Specific types of events, e.g. concerts?

Generic Listings

Not sure we need any patterns for this. Open to suggestions.

bug: individual listings in specific listings mode don't inherit parent Curated List attributes in editor

Something must have changed to break this functionality for the inner blocks. Investigate whether it affects the front-end, too. Either way, consider using CSS to show/hide elements in the editor instead of relying on parent block attributes.

Enable linking between Events and Places

It would be useful to be able to link Event listings with Place listings that can serve as venues.

• If a Place is added to an Event as a venue, when viewing the Event's single page, you should see some info on the venue appear automatically below the content.
• If that Event is added to a list with map functionality enabled, its venue's location data should be added to the map (as well as any map data existing in the Event post content itself).
• If viewing a Place that is attached to one or more Events, you should be able to see a list of the Events below the content.

[design] Add icon + title to new listing blocks

Can we have an icon and a title for the "placeholder" listing? Just like the curated list placeholder. So that the user know exactly which type of listing he's adding.

Also at this stage, we don't need the list numbers even if it's turned on. List numbers should only be displayed when the user selects a listing.

Originally posted by @thomasguillot in #6 (comment)

Add option to remove Jetpack Related Posts

Both Local Profile and Gay Desert Guide have asked us to remove Jetpack's related posts from their listings. In light of the fact that listings are often in competition with each other, it would make sense for us to include a means to easily toggle those off.

For now, we've added some CSS to accommodate:

/* Hide Jetpack Related Posts from Listings CPTs */

.newspack_lst_generic-template .newspack_lst_place-template .newspack_lst_mktplce-template .jp-relatedposts, [class^="jp-relatedposts"] {
	display: none !important;
}

Create block patterns for listings

Currently, we have one block pattern: the "Business Listing" pattern, available in Marketplace and Place listings. This is modeled loosely on the listing templates from D Magazine.

I'd like to establish several block patterns that can be used as starter content for each listing type. Since these are just collections of existing blocks, we can always change these around or add additional patterns over time, but at launch I'd like to have at least a few for each listing type, to help editors get started.

Paging @joeboydston, @thomasguillot and @laurelfulford for your help in establishing what types of content we should design first. Here's a brief list of ideas to get us started:

• Business (Marketplace, Place): Description content with a sidebar containing map, social media links, contact info and business hours. Intended for location-based listings. This is the one I've already included to get us started.
• Restaurant (Marketplace, Place): We could potentially get more granular with different business types, like D Magazine does. A Restaurant listing might include much of the same content as a Business, but with additional blocks for menu links, cuisine, pricing, reservation info, etc. We could also create additional patterns based on other types of businesses or locations, if we go this route.
• Event (Event): Used to describe something that happens during a particular time or time range. Could include a description, date/time info, map of location, a link to buy tickets if applicable, etc.
• Obituary (Marketplace): Let's look to Legacy.com for inspiration.
• Classified Ad (Marketplace): Something like craigslist.org for Newspack sites.
• Listicle Item (Generic): Content that could be used to represent a single item in a listicle. Listicles can be any type of editorial content that isn't tied to a particular date or location.

Front-end sort UI

From the roadmap:

Front-end sorting and filtering UI for Curated List block

• Editors should be able to turn on sorting and filtering UIs for specific Curated List block instances.
• This would allow front-end users to sort and filter items within the single Curated List instance.
• Sort by: listing title (alphabetical), date (if date data exists)
• Filter by: categories, tags (will push this to a future enhancement #16)
• Must take into account multi-page lists, if the list is in query mode and has “load more” functionality enabled.
• Must be AMP-compatible

Use post categories and tags instead of custom taxonomies

Consider deprecating the custom taxonomies and allowing listings to use regular post categories and tags.

This would create another relationship between regular posts and listings and make it easier to do things like place certain ad units with specific categories and have them show up with both articles and listings.

Integration with Newspack Sponsors

Ability to apply sponsors to:

• Individual listings
• Whole curated lists

Potential bug: pages with query-mode Curated Lists don't update automatically unless manually updated

Expected behavior: If you add a Curated List block in query mode to a page, and then add more listings that match the block's query params, the page should update itself automatically to show the latest posts.

Actual behavior: Perhaps due to edge caching in a production environment, the page will not update itself until the cache is busted.

Switching month on event editor crashes block

I am unable to change the month of an event. The block crashes with the following error:

TypeError: t.onMonthPreviewed is not a function

Update block patterns with placeholder images

Instead of including empty Image and Gallery blocks in our patterns, we should populate them with Newspack-branded placeholder assets. This will make it easier at a glance to see what the pattern is supposed to look like with live content.

"Listing Type" is not an available Sort By option at editor page load

As described in #12 (review), the Listing Type sort option should be available by default, but currently you must interact with the "Listing Type" option first before it appears in the dropdown.

When inserting block patterns, don't create maps with default markers

Creating maps with a default marker adds an extra step for each listing, so it would be smoother for most editors if the map came in completely empty.

User-generated content/self-serve listings

• Publishers should be able to provide login credentials for third parties to allow those third parties to create and edit their own listings.
• These third-party users can only see and edit listings and sponsor CPTs, and can only see and edit their own posts.
• Listings created by third-party users must enter a “review” status so editorial staff can review before publishing.
• Since this is the same functionality as is planned for the Newspack Sponsors plugin, we may be able to create this functionality in one plugin and use it for both Sponsors and Listings.

New option to set default template for listings

Currently, all listing CPTs inherit the default template set for posts in the Customizer. Ideally, we should add options to set the default template for each listing CPT separately from posts. This could potentially live in Newspack Listings plugin settings instead of the customizer.

Front-end filter UI

We have a sort UI now, but it would be nice to add filtering capabilities. This would let readers filter the list by category, tag, search term, or perhaps other arbitrary metadata.

Settings: Listings permalink prefix for Events, Generic Listings, Marketplace Items, Places

Today, I can edit /listings in settings, but items, marketplace and places are fixed:

• /listings/items/
• /listings/marketplace/
• /listings/places/

For an even more generic use (our case: product/service listings, people directory), I'd like to be able to modify permalink prefixes for each listing type:

• /directory/people/ (generic)
• /directory/products/ (marketplace)
• /directory/bikeshops/ (places)

Front-end styles for featured listings

#124 adds two class names to featured listing article elements when shown in Homepage Posts, Post Carousel, or Curated List blocks; archive pages; search results; or to the body on singular listings.

• featured-listing - Added if the listing is currently featured, regardless of priority level
• featured-listing-priority-# - The # is an integer from 1–9 indicating the feature priority level.

As mentioned in that PR, we need to come up with a universalish way to style these featured items so they're visually distinct from non-featured/regular items. GDG uses what we call "pseudo-labels" which are shown alongside the post's category labels, but this isn't universal enough because many sites choose not to show categories in their blocks. A CSS-only treatment would be cleaner and more customizable, if possible.

Map only shows first page of queried results

When creating a query-based list with the "show map" and "load more" options enabled, the map will only ever show locations for the first set of listing posts.

Curated List: Add option to block settings to define the default sort order

The default sort order appears to be published date. Since we allow the reader to change that via the UI option, it would be handy to allow those who are creating the page to change the default as well.

Particularly for places, sorting by title as a default generally is more intuitive than sorting by publish date.

By request from SacObserver.

Phase 2 beta test

This is a single issue where we can track all problems or requests related to the transition from v1.X.X to v2.X.X.

Design: front-end display of parent and child listings

@thomasguillot now that #58 is well underway to let editors create connections between listings of different types as well as posts/pages, we should think about how we want these to appear to readers. We've talked about using a custom block that will let editors both choose if/where the listings get rendered in content, and choose some style options to control how they look. I'm on board with this idea and would suggest we start with a relatively small number of styling options to keep this as more of an MVP, as we can always add more options in the future based on publisher feedback. Here's what I think we need:

1. Two custom blocks: one for parent listings, and another for child listings. These wouldn't let you select/manage parent or child listings directly, but perhaps we could move the button to open the modal UI to do so from the post sidebar to the block sidebar instead. These blocks would only be available on posts that can display parent or child listings.
2. Front-end display: I'll need some mockups of how you'd like the parent/child listings to be displayed to readers, with the variations that can be chosen in the blocks. For reference, here's an example of how this is done in Village Media:

• Business listing (equivalent to our Place): The "Careers" and "Listings" below the main content are both different types of child listings.
• Property listing (equivalent to our Marketplace) which is owned by the above business: The "Contact Williams and McDaniel Property Management" is the parent listing which links back to the business's profile page.

I also understand that the display of parent listings may be different on posts and pages, compared to other listings. For posts and pages, we're calling parent listings "related listings" and they're intended to be seen more as related content than "owning" the post or page. For convenience they do use the same back-end data relationship as a parent listing.

Featured Image options for individual listings

On regular articles (posts), the Newspack themes provide several Featured Image Position options for displaying the featured image:

These options should be present on individual listings as well.

Add a test suite

As the plugin grows in complexity (especially with the Phase 2 features), it's getting more difficult to track the logic of which post types can relate to others, and how certain custom UI elements should behave. We should implement at the very least some Jest tests to cover the more complex UI elements. It might also be useful to build some PHPunit tests for covering the display of curated lists and related listings. Ideas:

JS

• Test the display of the custom autocomplete UI for selecting parent and child listings (from #43): Certain post types should only allow assignment of specific other post types for parent and child relationships
• Test the display of Curated List block previews in the editor given different block attributes

PHP

• Test the front-end display of curated list blocks and the listing excerpts shown within, given different attributes
• Test the front-end display of child/related listings on a post with assigned parent listings

Hide shadow taxonomies from Quick Edit UI

Related listings are applied using shadow taxonomies, which are supposed to be invisible to the admin user. However, these taxonomies are shown in the Quick Edit UI for posts, which means it's possible to accidentally disassociate a listing from its shadow taxonomy (which would break some related listing functionality).

Easiest solution would be to prevent shadow taxonomies from appearing in this Quick Edit UI, so that they can only be applied as intended using the Related Content modal UI.

Bug: Invalid meta value error

(More detailed replication steps TK)

1. Create a listing and add a Jetpack Contact Info block.
2. Remove some sub-fields from the Jetpack Contact Info block, such as phone number and email address.
3. Fill out the remaining fields and publish/save the listing.
4. You should see an error about "invalid metadata" that seemingly prevents the post from being saved.

Permalinks lead to 404

#1 (comment)

Difficult to replicate. May have something to do with a Yoast conflict.

[design] Focused vs. unfocused styles

When the Curated List block is unfocused, we shouldn't see the borders, paddings, [+], etc...

Originally posted by @thomasguillot in #6 (comment)

Fatal error when products are enabled but WC Subscriptions isn't active

When the NEWSPACK_LISTINGS_SELF_SERVE_ENABLED environment constant is set to true, Newspack Listings self-serve products are available. However, the products class assumes both WooCommerce and the WooCommerce Subscriptions extension are active; it's possible for the base WC plugin to be active but the Subscriptions extension to not be. In the latter case, Newspack Listings will throw an unhandled fatal error, taking down the whole site.

Categories archive for listings only

#120 introduced options to enable/disable archives for listings. The shared taxonomy with posts makes it reasonable to not enable category archives for listings and have them mixed with the other articles archives.

The logical, but undesirable result is that it also disables navigation through categories that contain only listings, showing "no results".

I still don't know what the best solution could be here. The best I could think of is to restore the listing custom taxonomy and have them both available. The custom taxonomy could then have its own archive options

Price: Add styling options to the block

At the moment, the block is pretty basic and it feels like there's a lack of customisation.

Maybe in the sidebar we could add a few controls:

• Typography
  • Font-size (default to Large)
  • Text alignment (default to Left)
• Colour settings
  • Text colour
  • Background colour

Direct associations with Posts and Pages

Create a way to build relationships between all the different listing types and posts/pages. One way to do this would be to create a metadata field in the sidebar for posts and pages that lets editors search for listings to associate with that content. This could be very similar to the UI we show for searching for listings in a Specific Posts curated list block, but for all listing types, not just one at a time:

After one or more listings is associated with a post or page, we would have the ability to e.g. show them on the front-end in a custom related content module.

Add social media links to business block patterns

Publishers always want social media links for business listings—we should add the social links block to our business patterns to accommodate that common use case.

JS errors on Widget screen in WP 5.8

When the Newspack Listings plugin is activated (v 2.0.1) on a site running the WordPress 5.8 RC, you get this error on the Appearance > Widgets screen:

TypeError: _dispatch is null

Two files seem to be throwing this error in this plugin:

/src/editor/shadow-taxonomies/child-listings.js?:337
/src/editor/shadow-taxonomies/parent-listings.js?:402

This is similar to what happened to the Newspack theme, which threw the same error. Everything enqueued with enqueue_block_editor_assets is now being loaded on the Widgets screen; this plugin might need a check to avoid loading all these files on the widget screen.

Automatically populate address when adding a map location?

Suggested by @jeffersonrabb: when creating a listing using the business patterns provided, those patterns include both a map and a contact info block. The expectation should be that if you add a location to the map, it should fill out the contact info with the location's address, if possible.

Questions:

• What if there's more than one location added to the map?
• What if the editor adds more contact info blocks? Which one do we update?
• If the contact info block has an address in it already, should we overwrite it?
• Is the contact address always the same as the location? I can see use cases where they shouldn't match—e.g. the location is a park, but the contact info is for the local parks office that manages all parks.

Add a class name for each category to the single post body

Similar to Automattic/newspack-theme#1291, we should add a class name for each category term on the single listing post body element. This would let publishers apply custom CSS based on categories, such as a "Best Of" flag.

Curated Block: Increase Minimum from 20 to 35

Local Profile has mentioned that 20 feels too few. They've requested 35. Would that be too much to load all at once? What's the best way for us to determine the optimal threshold for that setting?

Data import feature

Ability to import content from a CSV file to generate Place listing posts representing businesses.

We should start with supporting a single standardized format for the CSV import file. Should support data like business names, addresses, and contact info.

Convert Marketplace listings to Place listings (and vice versa)

With the coming Phase 2 requirement that businesses should be created as Place listings, there could be potential confusion about the use of Marketplace vs. Place listings since Phase 1 versions allow Marketplace listings to be used as business profiles. For this reason, we should create a feature in the editor that lets admins convert Marketplace listings into Place listings, and vice versa.

Since both post types share the same meta fields, it should be fairly clean to just swap the post_type property to do the conversion. One caveat is that Curated List blocks that contained the posts pre-conversion would no longer be able to find the posts by their original post type, so we'll need a strategy to handle that scenario.

cc @joeboydston

Migration script to handle existing custom taxonomies

#39 deprecates the custom category and tag taxonomies for listings only, in favor of post categories and tags. This PR will be a breaking change, so we should consider creating a migration script to help sites who may be using those taxonomies. This script should get all listing posts that have terms from the deprecated taxonomies and then:

1. Check for a corresponding post category or tag term with the same name, and if it exists, assign that
2. If a corresponding post category or tag term doesn't exist with the same name, create and assign it
3. (optionally) remove the term assignments for the deprecated taxonomies from any posts that have them

Tagged as on hold so we can confirm whether this is needed first.

Harden post type usage

We built Newspack Listings to be flexible in the usage of the various listing types, but in order to more easily cross-reference listings with each other and other content types, we should more clearly define the use cases for Places and Marketplace listings: businesses should always be represented as places, and Marketplace listings as one-off pieces of content. This would make it easier for us to create a parent-child relationship between businesses as Places and the Marketplace listings they own.

If we did this, Places would become the de facto content type that publishers sell to third parties to represent their business, and Marketplace listings would be the content that those third parties could create and edit on their own. Marketplace listings could also serve as classified ads and obituaries, and we would offer block pattern layouts for all of these use cases, while removing the Business patterns from the Marketplace post type.

We could also create a similar parent-child relationship between Places and Events, so that (for example) a concert venue could be created as a Place, and Event listings that take place at the venue could be associated with it. Porting ideas from #22 here (not vetted, just ideas):

• If a Place is added to an Event as a venue, when viewing the Event's single page, you should see some info on the venue appear automatically below the content.
• If that Event is added to a list with map functionality enabled, its venue's location data should be added to the map (as well as any map data existing in the Event post content itself).
• If viewing a Place that is attached to one or more Events, you should be able to see a list of the Events below the content.

Terminology: "Related Content"

What we call parent and child listings internally is labeled as "Related Content" in admin-facing UI. This somewhat generic term is a potential source of confusion—for example, Jetpack's Related Content module has nothing to do with this, but the use of the same term might lead one to think they're related.

Let's brainstorm alternatives to "Related Content" that define this feature more clearly as part of Newspack Listings only. Ideas:

• Newspack Listings: Related Content
• Related Listings (this is closer to what we called it originally, but decided to change it as posts and pages can also be designated as children of listings).
• Your ideas here?