Inherits from: apostrophe-doc-type-manager
apostrophe-pieces provides a "base class" you can extend to create new content
types for your project. Just use the addFields option to create a schema and
you'll get a user interface for managing your content for free. Add in the
apostrophe-pieces-pages module to display an index page and permalink pages
for your pieces, and use apostrophe-pieces-widgets to allow them to be sprinkled
into pages all over the site. To learn more, see:
If set this string, which typically should end with -, will be prepended
to the slugs of all pieces of this type in order to prevent needless
conflicts with the slugs of other piece types.
See reusable content with pieces for many additional options.
Returns a cursor that finds docs the current user can edit. Unlike find(), this cursor defaults to including unpublished docs. Subclasses of apostrophe-pieces often extend this to remove more default filters
middleware for JSON API routes that expect the ID of an existing piece at req.body._id, with editing privileges
middleware for JSON API routes that expect the ID of an existing piece this user is allowed to edit at req.body._id
User must have some editing privileges for this type
options.filters can contain cursor filters. options.chooser, options.format and
options.manageView are also implemented. For bc, if options.filters does not exist,
all properties of options are treated as cursor filters.
Insert a piece. Also invokes the beforeInsert, beforeSave, afterInsert and
afterSave methods of this module.
You may omit the options argument completely.
If options.permissions is explicitly set to false, permissions are
not checked. Otherwise the user must have the appropriate permissions to
insert the piece.
For convenience, the piece is passed to the callback as the second argument. It's the same piece object, with some new properties.
If no callback is passed, returns a promise.
Update a piece. Also invokes the beforeUpdate, beforeSave, afterUpdate and
afterSave methods of this module.
You may omit the options argument completely.
If options.permissions is explicitly set to false, permissions are
not checked. Otherwise the user must have the appropriate permissions to
insert the piece.
For convenience, the piece is passed to the callback as the second argument.
It's the same piece object you passed, likely with modifications such as
the updatedAt property.
Move a piece to the trash by id. If callback is omitted,
a promise is returned.
Rescue a piece from the trash by id. If callback is omitted,
a promise is returned.
Convert the data supplied in req.body via the schema and
update the piece object accordingly.
Invoked after apos.schemas.convert by the insert and
update routes
Invoked by self.insert. Does nothing by default; convenient extension point
Invoked by self.insert and self.update. Does nothing by default; convenient extension point
Invoked by self.insert. Does nothing by default; convenient extension point
Invoked by self.insert and self.update. Does nothing by default; convenient extension point
Invoked by self.update. Does nothing by default; convenient extension point
Invoked by self.update. Does nothing by default; convenient extension point
Invoked by self.trash. Does nothing by default; convenient extension point
Invoked by self.trash. Does nothing by default; convenient extension point
For legacy reasons, pieces have their own apiResponse method which is just a wrapper for the newer apiResponder.
Enable inclusion of this type in sitewide search results
Add ._url properties to the given pieces, if possible.
The default implementation does nothing, however
apostrophe-pieces-pages will
call setAddUrls to point to its own addUrlsToPieces method.
Called by apostrophe-pieces-pages to
replace the default addUrls method with one that assigns ._url
properties to pieces based on the most suitable pages of that type.
See the addUrlsToPieces method of apostrophe-pieces-pages.
Implements a simple batch operation like publish or unpublish.
Pass req, the name of a configured batch operation, and
and a function that accepts (req, piece, data, callback),
performs the modification on that one piece (including calling
update if appropriate), and invokes its callback.
data is an object containing any schema fields specified
for the batch operation. If there is no schema it will be
an empty object.
If req.body.job is truthy, replies immediately to the request with
{ status: 'ok', jobId: 'cxxxx' }. The jobId can then
be passed to apos.modules['apostrophe-jobs'].start() on the rowser side to
monitor progress.
Otherwise, replies to the request with { status: 'ok', data: piece }
on success. If ids rather than _id were specified,
data is an empty object.
To avoid RAM issues with very large selections and ensure that lifecycle callbacks like beforeUpdate, etc. are invoked, the current implementation processes the pieces in series.
Accept a piece found at req.body, via
schema-based convert mechanisms, then
invoke responder with req, res, err, piece.
Implements self.routes.insert. Also used
by the optional apostrophe-pieces-rest-api module.
If req.piece has a _copyingId property, fetch that
piece and, if we have permission to edit, copy its
non-schema-based top level areas into the new piece.
This accounts for content editor-modal.js doesn't know about.
Update the piece object at req.piece
(usually populated via the requirePiece middleware
or by the insert route) based on req.body, fetch the updated piece
and invoke responder with req, res, err, piece.
Implements the back end of the update route, also used
by the optional apostrophe-pieces-rest-api module.
Copy top-level areas present in copyFrom to piece,
leaving any that are already present in piece alone.
The copy mechanism in the piece editor modal only
knows about noncontextual schema fields, this method is called on the
server side to copy contextual and undeclared areas too
An empty stub you may override to copy extra properties not visible to the schema when the user carries out a "copy piece" operation. At this point schema fields and top level extra areas have already been copied
Generate a sample piece of this type. The i counter
is used to distinguish it from other samples. Useful
for things like testing pagination, see the
your-piece-type:generate task.