# Inherits from: apostrophe-custom-pages
apostrophe-pieces-pages implements "index pages" that display pieces of a
particular type in a paginated, filterable way. It's great for implementing
blogs, event listings, project listings, staff directories... almost any
extend this module in new modules corresponding to your modules
To learn more and see complete examples, see:
If present, this is an array of objects with
name properties. The named cursor filters are
safeFor: "public" if they exist, and an array of choices for each is populated
req.data.piecesFilters.tags (if the field in question is
tags), etc. The choices in the
array are objects with
If a filter configuration has a
counts property set to
true, then the array provided for
that filter will also have a
count property for each value. This has a performance
Extend this method for your piece type to call additional
chainable filters by default. You should not add entirely new
filters here. For that, define the appropriate subclass of
apostrophe-pieces-cursor in your subclass of
# indexPage(req, callback)
At the URL of the page, display an index view (list view) of the pieces, with support for pagination.
# beforeIndex(req, callback)
indexPage. By default, does nothing.
A convenient way to extend the functionality.
# filterByIndexPageTags(cursor, page)
Invokes filters on the given cursor to ensure it only fetches results with the tags this page has been locked down to via page settings. If it has not been locked down, no filtering occurs. Override to change the behavior.
# showPage(req, callback)
Invoked to display a piece by itself, a "show page." Renders
show.html template after setting
If the pieces module is set
contextual: true, the context menu
(the gear at lower left) is updated appropriately if the user has
# beforeShow(req, callback)
Invoked just before the piece is displayed on its "show page." By default, does nothing. A useful override point.
Set the dispatch routes. By default, the bare URL of the page displays
the index view via
indexPage; if the URL has an additional component,
/blog/good-article, it is assumed to be the slug of the
showPage is invoked. You can override this method,
for instance to also accept
/:year/:month/:day/:slug as a way of
self.showPage. See apostrophe-custom-pages
for more about what you can do with dispatch routes.
# chooseParentPage(pages, piece)
Given an array containing all of the index pages of this type that exist on the site and an individual piece, return the index page that is the best fit for use in the URL of the piece. The algorithm is based on shared tags, with an emphasis on matching tags, and also favors an index page with no preferred tags over bad matches. Override to replace the algorithm.
This method is called for you. In the presence of index pages, the cursors for the corresponding pieces are automatically enhanced to invoke it when building URLs.
# buildUrl(page, piece)
Given an index page and a piece, build a complete URL to
the piece. If you override
dispatch to change how
"show page" URLs are matched, you will also want to override
this method to build them differently.
Make the browser-side
apos object aware of the current
in-context piece, as
apos.contextPiece. Just enough to
help the contextual editing tools in various modules
pushContextPiece to make
in the browser
# addUrlsToPieces(req, results, callback)
._url property to all of the provided pieces,
which are assumed to be of the appropriate type for this module.
Aliased as the
addUrls method of apostrophe-pieces, which
is invoked by the
addUrls filter of apostrophe-cursor.
Returns a cursor suitable for finding pieces-pages for the purposes of assigning URLs to pieces based on the best match.
Should be as fast as possible while still returning enough
information to do that. For instance, tags are essential for the standard
chooseParentPage algorithm, but joins and areas are not.
The default implementation returns a cursor with areas and joins shut off.
addUrlsToPieces method as the
of the related pieces module.
# populatePiecesFilters(cursor, callback)
req.data.piecesFilters with arrays of choice objects,
with label and value properties, for each filter configured in the
piecesFilters array option. Each filter in that array must have a
name property. Distinct values are fetched for the corresponding
cursor filter (note that most schema fields automatically get a
corresponding cursor filter method). Each filter's choices are
reduced by the other filters; for instance, "tags" might only reveal
choices not ruled out by the current "topic" filter setting.
If a filter in the array has its
counts property set to true,
Apostrophe will supply a
count property for each distinct value,
whenever possible. This has a performance impact.