Newspack Listings is a tool to help publishers create reusable lists using the Gutenberg block editor. It can be used to generate curated lists of specific items, or lists that are populated by queries. Lists can be embedded in post or page content, or anywhere core Gutenberg blocks can be used. Listing items exist as discrete, reusable pieces of content with their own standalone pages, useful for SEO purposes.
Newspack Listings is designed to be used for a wide variety of use cases, whether you want to build a directory of local businesses, a list of upcoming events, a site section for obituaries or classified ads, a series of listicles, or basically any type of content that is best displayed in list form—especially if you intend to reuse the list or items in it in various places. Edit a listing item in one place, and it will update everywhere it appears. Save curated lists as reusable blocks and drop them into various posts, pages, or widgets.
To contribute to the plugin’s development, report bugs, or make feature requests, please visit the GitHub repository.
Newspack Listings is a standalone plugin which you’ll need to install and activate in order to use:
- Navigate to Dashboard > Plugins.
- Find Newspack Listings listed in the plugins to install under Newspack.
- Click Install, then Activate.
If you’re not using Newspack, you’ll need to download the Newspack Listings plugin, upload it to your WordPress site, then activate it.
After installing and activating the plugin, you’ll see a Listings menu item in your WP Admin sidebar. Hover over the menu item to see the available content types, taxonomies, and plugin settings:
First, click on Settings (the last link in the menu). There is currently one plugin-wide setting, which lets you choose the prefix that appears in every individual listing’s public URL. This is
listings by default, so that an individual listing’s URL will look something like this:
https://[SITE DOMAIN]/listings/[LISTING TYPE]/[LISTING SLUG]
If you change this option, please make sure to flush permalinks in order for the new URLs to take effect. To flush permalinks, visit Settings > Permalinks in the WP admin dashboard, then click Save Changes without changing any of the options on that page.
If you use AMP on your site, you should enable AMP for all listings content types. To do this:
- Go to AMP > Settings in admin dashboard.
- Under Advanced Settings, expand the Supported Templates panel.
- Under Content Types, make sure the boxes are checked for all listing types (Events, Generic Listings, Marketplace, and Places):
- Click Save Settings at the bottom of the settings page to apply the change.
Note that there’s currently a known bug when viewing a listing page with AMP disabled. If the Newspack Campaigns plugin is active and campaigns are enabled for a post, the Campaigns plugin may conflict with certain Jetpack features, including the Jetpack Map block. If you notice a map not rendering in a listing’s content, either a.) make sure AMP is enabled for the listing type, as described above, or b.) disable campaigns on the individual listing by toggling on the “Disable Campaigns on this post or page” option.
Before you can create and populate lists, you need to publish some listing content first. Think of lists as being containers that hold individual listings—all content exists in the individual listings, not the list. This lets you reuse listings across multiple lists while only needing to edit listing content in one place.
The following listing types are available to author content. These listing types are intended to provide a flexible way to organize different types of list content. Each listing type has a range of intended uses:
- Events: These listings are tied to specific dates or times. If creating a queried list with only Event listings, the list can be optionally sorted by event date. Examples of events: upcoming board meetings, concerts in town, local elections
- Generic Listings: These listings can be any kind of editorial content best displayed in list form. Use generic listings when you’re building a list with content that doesn’t fit into any of the other listing types. Examples of generic listings: top 10 albums of the year, holiday gift ideas, best new comedies to stream, Buzzfeed-style listicles
- Marketplace Listings: These listings are intended to represent third-party content for monetization purposes. Currently, there are no self-service features for letting third parties purchase and/or maintain their own content, but any self-service features that are developed in the future will apply to marketplace listings only. The types of content that can be considered marketplace listings can and will overlap with other listing types, but the primary distinction is that marketplace listings are intended to be non-editorial content that exists for generating direct sales revenue. Examples of marketplace listings: classified ads, local obituaries, sponsored local business profiles, sponsored product pages
- Places: These listings are tied to specific locations. These could be businesses or just anyplace that can be pinpointed on a map. Examples of place listings: best take-out restaurants, public parks in the area, local polling stations, COVID-19 testing sites
To create new listings, click on the listing type in the menu. This will bring you to the familiar posts-like interface, where you can add new listings or edit existing ones:
Listings must have a Published status in order to appear in lists. If a published listing is trashed or reverted to draft status, it will no longer appear in any lists it was previously added to.
Listing Content and Layouts
Listing content is built using Gutenberg blocks, just like any WordPress post or page. You can author and arrange content however you like in each individual listing. However, adding certain blocks will unlock some functionality that applies to listings only.
To help keep listing content and data consistent, Newspack Listings provides several block patterns that can be used only with the appropriate listing types. These block patterns provide prefabricated content layouts with placeholder content and empty fields to suggest the types of data that can be added to a listing. Once a pattern is added to the listing content, the blocks in the pattern can be moved around or deleted as needed.
For example, if editing a Place or Marketplace listing, you may choose to use one of several Business Listing block patterns, which provide placeholder content and data fields that could be relevant for business profiles. These include a business description, map and contact info, and business hours in a column layout:
To use these patterns, while editing a listing, click on the Block Inserter button in the upper-left corner of the editor to expand the block menu. Click the Patterns tab, then select Newspack Listings from the dropdown to view the block patterns available for the current listing type. Note that not all listing types support all block patterns; for example, the Business Listing patterns are only available for Places and Marketplace listings, while Event patterns are available only for Event listings, and so on.
Note that to get the most out of these block patterns, your site needs to have Jetpack installed and connected. Without Jetpack, you will still be able to add the patterns, but some of the premium blocks in the patterns will be unusable.
Other Listing Options
Before exiting the block editor, you may want to look at a few settings that are important for listings.
First, in the sidebar for your listing type, expand the [LISTING TYPE] Settings panel. Here there’s an option (OFF by default) to hide the author for this listing. If you’re using a Newspack theme, enabling this option will ensure that the author byline will be hidden wherever this listing is shown, whether it’s in a list (even if the list has enabled author display) or in the listing’s own page.
Next, under the same sidebar, expand the Categories and Tags panels. These category and tag taxonomies work similarly to Categories and Tags for regular posts, except these Categories and Tags are associated only with listings. All listing types share the same categories and tags, so there’s no need to create a “Restaurant” category for both Places and Marketplace listings, for example. Organizing listings with relevant categories and tags can help you build dynamic lists using queries (more on this later). You can manage existing listing taxonomies by visiting Listings > Categories and Listings > Tags from the main WP admin dashboard.
Lastly, under the same sidebar, expand the Excerpt panel. If you enter an excerpt here, it will be displayed whenever the listing is displayed in a list that is set to display excerpts. If this excerpt field is left blank, an excerpt will be automatically generated from the first bit of content in the listing. If the auto-generated excerpt doesn’t look good in your list, try adding your own excerpt using this option.
Once you have at least one published listing of any type, you can create a list. Lists are blocks that can be added to any post or page content. To start creating a list:
- Edit the post or page where you’d like the list to live.
- In the content editor, insert a new block (either via the quick inserter or the regular block inserter). Look for the Curated List block under the Newspack block category.
- Select Curated List to add the list block to your post or page content.
- When creating a list for the first time, you’ll need to decide whether the list should show a query, or specific listings.
- Specific listings mode lets you choose the exact listings to be displayed, in the order you specify. Once published, the items shown by the list will never change (unless items in the list get changed to a non-published status—these listings will no longer be shown, in that case).
- Query mode is a more advanced mode to dynamically display listings that match the query options you set in the block. This is useful if you want the list to automatically update itself when new listings are published, or if you want the list to display many listings with “load more” functionality.
- Once you select the list mode, you can’t change it. You’ll have to create a new Curated List block if you change your mind. This is by design, to prevent accidental loss of data.
Tip: If you’re happy with a Curated List’s content and like how it looks, you can save the list as a reusable block that can be used elsewhere.
Populating Lists in Specific Listings Mode
We’ll go through creating lists in specific listings mode first, because it’s simpler.
- When prompted, select Specific Listings. You’ll see an empty list like so:
- Click the [+] inserter button to add a listing. You’ll be prompted to choose the listing type first. After choosing the listing type, you’ll see a UI to either search for a listing by title, or to select from a list of the ten most recently published listings of that type.
- You can mix and match different listing types within the same list.
- Listings will only be shown here if it has a “published” status and hasn’t already been added to this particular list.
- Individual listings in specific listings mode are edited as Gutenberg blocks. Once you’ve added more than one listing, you can change the order of the listings by dragging and dropping them in place, or by clicking on the listing and using the sort buttons in the block toolbar (highlighted here in red):
- To remove a listing item after it’s been added, click on the listing and select the three vertical dots button in the toolbar, then click Remove block. This won’t affect the listing item itself—it will just remove it from the list you’re currently editing.
- Once you’re happy with the items in your list and the order they’re appearing, publish or update your post or page to make the list publicly viewable.
Populating Lists in Query Mode
If you’ve selected Query mode after adding a Curated List to your post or page, you might see some listings appear automatically. Notice that you can’t click on individual listing items to move or remove them. This is because query mode populates the list by query settings you define in the Curated List block’s sidebar. The listing items shown in the editor (and on the front-end) will automatically update as you change the query settings. It’s important to note again that query mode lists will load listings dynamically, so if new listings are published that match a list’s query settings, the list will show those new listings even if it was already published before.
The available query settings are:
- Listing Type: Lets you restrict the list to a specific listing type. Default: “Any,” meaning the list can show all types of listings.
- Authors: If you enter one or more author names here, only listings with one of the specified authors will be shown. Default: none.
- Categories/Tags: If you enter one or more categories or tags in these fields, only listings with at least one of the specified categories or tags will be shown. Default: none.
- Max number of items: Sets the maximum number of listings to load at a time. If your query settings match a lot of listings, only up to this number of results will be shown. This also defines the number of additional listings loaded when the “Load More” button is enabled. Default: 10.
- Show “load more” button: When enabled, if more listings match the query settings than the “Max number of items” option allows for, the list will show a “Load More” button until all matching listings have been loaded. Default: disabled
- If enabled, you can also define the button label with the Load More Button Text setting. Default: “Load more listings”
- Click Show Advanced Filters to view some more advanced query settings:
- Sort By: Lets you choose by what criteria the listing items are sorted. Note that the available options here depend on other list settings. For example, if you set the Listing Type setting above to Event, you will see an option to sort by Event Date. Likewise, if you set the list to display authors as described below, you’ll see an option to sort by Author. If you don’t see an option here that you want, make sure the list is configured to show the data you want to sort by. Default: publish date.
- Sort Order: Used in tandem with Sort By, lets you select whether the items should be sorted in ascending or descending order. Default: Descending, so that the default query shows listings from newest to oldest.
- Excluded Categories/Tags: If you enter one or more categories or tags in these fields, any listings that have those categories or tags will never be shown in the list. These settings will override the Categories/Tags settings above.
Whether you’re using query mode or specific listings mode, there are a number of options available to change how the list is displayed. You can find these in the block sidebar when selecting a Curated List in the editor. All options affect every item in the list.
Here are the options and some quick notes on what they do:
- Show list item numbers: If ON, displays listings as numbered items. If OFF, no numbers will be displayed. Default: ON
- Show map: If ON, a map will be automatically created inside your list with all locations of the listing items in that list. This map will update itself automatically as you add or remove listing items. Default: OFF
- To use this feature, your site must be connected to Jetpack and you must provide Jetpack with a Mapbox API token. For more details, see Jetpack’s instructions on how to get a token and configure the Jetpack map block.
- A listing item is considered to have location data if it contains at least one Jetpack Map block with at least one location pin.
- Note that for performance reasons, only up to 100 listings will be represented on the map. If your list contains more than 100 items, only the first 100 will appear on the map.
- Show sort UI: If ON, the list will be displayed with sort by and sort order controls that let the reader sort the list. Default: OFF
- A “Default” sort option that resets the list to the initial state is only available for lists in specific listings mode. Query mode lists will default to the sort order specified in the editor under Query Settings.
- If the reader sorts a list after clicking the “load more” button, the list will reset to the first set of “max number of items” results.
- Note that the sort options available in the UI depend on other list attributes. For example, the “Default” option won’t appear for query mode lists, and the “Event Date” option will only appear for query mode lists that are restricted to the Event listing type.
Featured Image Settings
- These settings control whether and how to show a featured image thumbnail and its caption with each listing. The featured images themselves are set within each individual listing. Default setting is to show a thumbnail but no caption.
Post Control Settings
- Show Excerpt: If ON, displays a short excerpt for each listing. This is either the excerpt set manually for that listing, or an auto-generated excerpt from the listing’s content. Default: ON
- Type Scale: Allows you to control the size of the text in the list. Default is the base font size of your theme.
- Text Color: Lets you define the color of the text in the list. Default is the base font color of your theme.
- Background Color: Lets you define the background color of the list. Default is transparent. If changing this setting, make sure the Text Color option is something that provides enough contrast to maintain legibility.
- Show Author: If ON, shows a byline for each listing. This can be overridden on a per-listing basis by enabling the Hide author setting when editing the listing itself. Default: OFF
- Show Category: If ON, shows categories assigned to the listing. Default: OFF
- Show Tags: If ON, shows tags assigned to the listing. Default: OFF