@apostrophecms/import-a2-tags
v1.0.1
Published
Import tags from A2 to tag piece types corresponding to various piece and page types in your project
Downloads
6
Keywords
Readme
@apostrophecms/import-a2-tags
Purpose
While Apostrophe 2 documents have a tags
array field, this field doesn't exist in
Apostrophe 3. Instead, tags are represented as relationships to a "tag piece type" if
and when this is desired in a particular project.
This module provides a simple way to migrate A2-style, array-based tags
properties to
A3-style relationships to a "tag piece type" corresponding to a particular piece type, or
to pages.
This module is most often used after a successful run of @apostrophecms/content-upgrader
,
which copies the tags
array property of each document over to A3 without modification.
Installation
npm install @apostrophecms/import-a2-tags
Configuration
Note that in this example we are configuring tags for all page types, but you can also import tags for any piece type or individual page type in the same way.
You can also add tags to all piece types by configuring them for @apostrophecms/piece-type
,
but usually this is a mistake because you will want to curate the tags for each piece type
separately.
// in app.js
modules: {
// Create a "tag piece type" to hold the tags in A3, since
// A3 does not use arrays for tags.
//
// For images and files you can skip this
'page-tag': {},
// Activate the import-a2-tags module
'@apostrophecms/import-a2-tags': {}
}
// in modules/page-tag/index.js (for images and files you can skip this)
module.exports = {
extend: '@apostrophecms/piece-type'
},
// in modules/@apostrophecms/page-type/index.js (for images and files you can skip this)
module.exports = {
fields: {
add: {
_tags: {
type: 'relationship',
withType: 'page-tag',
label: 'Tags',
help: 'Tags for this page'
}
}
}
};
Usage
# Import tags on images to the built-in image-tag piece type and create relationships
node app @apostrophecms/import-a2-tags:import --types=@apostrophecms/image:@apostrophecms/image-tag
# Requires additional configuration, see above
node app @apostrophecms/import-a2-tags:import --types=@apostrophecms/page-type:page-tag
Specifying the piece type or page type to import tags from
The type before the :
is the page or piece type that has data in an existing tags
array
property in MongoDB (usually due to an import from A2).
Specifying the "tag piece type" to represent the tags
Since A3 does not have array-based tags, you'll need to add a piece type to your project to represent the tags. This change was made in A3 because it yields a better curation experience.
The type after the :
is a piece type that you have added to your A3 project to serve as a
"tag type." You must also add a _tags
relationship pointing at this type, as shown above.
Note that images already have a tag piece type, @apostrophecms/image-tag
, and
files do too, @apostrophecms/file-tag
. You don't have to create a new module in order
to import these.
Importing multiple types at once
If you wish, you can specify multiple comma-separated pairs of types:
node app @apostrophecms/import-a2-tags:import --types=type1:type1-tag,type2:type2-tag
Again, the tag piece types must exist in your project, except for
@apostrophecms/image-tag
and @apostrophecms/file-tag
which exist by default.