#Collections

Under the hood, Collections are called Datastores and Entries are called DataItems. "Datastore" and "DataItem" will be used in this documentation when talking about API access while "Collection" and "Entry" will be used when talking about user interface.

#Datastore Schema

The schema for a Datastore is shown below. We will go into what each property does here.

{

  // uneditable properties
  _id: '639cf545ea990f22e697185e',
  parentVersionId: '639cf555ea990f22e6971860',
  managedByAddonId: '639b8f837f5fb8a39404280a',
  createdAt: 1671250792833,
  updatedAt: 1671250878818,

  // basic properties
  name: 'Vehicle',
  description: 'Vehicles for sale',
  icon: 'directions_car',

  // general properties
  isEnabled: true,
  isGlobal: false,
  isGlobalSelectable: false,
  isInNav: false,
  isAddonDataItemCreateEnabled: false,
  isAddonDataItemDeleteEnabled: false,

  // fields
  fields: [],

  // form layout
  tabs: [],
  sections: [],

  // display fields
  displayField: 'displayTitle',
  displayFieldSecondary: '',
  displayFieldExtra: '',
  displayFieldContent: 'description',
  displayFieldImage: 'images',

  // sorting fields
  sortBy: 'listedAt',
  sortOrder: 'desc',

  // archive fields
  archiveField: 'listedAt',
  archiveAfterDays: 90,

  // build-time properties
  functions: [],
  buildScript: '',

}

#Uneditable Properties

#Basic Properties

#General Properties

#Fields

An array of Fields. Fields have common properties and properties unique to that type. Each type is explained below. All properties other than name and type have a default value and can be omitted when creating a Field or Datastore. See Collection Fields for more information.

#Common Field Properties

These properties are available on most Field types.

#String (Text)

Strings have the following special properties they can optionally specify.

Formats have the following properties. Note that only type is required for all but the "replace" format type.

#Number

Numbers have the following special properties they can optionally specify.

#Date

Dates have the following special properties they can optionally specify.

You must provide date values for this Field in the format you specify with dateType. For example:

'2023-02-03'  // dateType: ''
'23:49'       // dateType: 'time' (always 24-hour format)
1678003648592 // dateType: 'datetime' (JavaScript Date)

#Rich Text

Rich Text Fields have the following special properties they can optionally specify.

#Media

Media Fields have the following special properties they can optionally specify.

#Asset

Asset Fields have the following special properties they can optionally specify.

#Enum (Enumerable)

Enum Fields have the following special properties they can optionally specify.

You can also specify isEnumValueCreateDisabled on the Field to prevent the user from creating their own enumValues.

#Reference (Relation)

Reference Fields have the following special properties. referenceTo is required.

#Array

Array Fields must specify the field property.

For example, an array of images might look like this:

{
  name: 'Images',
  type: 'array',
  minLength: 1,
  maxLength: 20,
  field: {
    type: 'media',
    mediaType: 'image',
    uploadPath: 'Blog Post Images',
  },
}

#Object

Object Fields can optionally specify many of the same properties the Datastore can. Specifically tabs, sections, fields, displayField, displayFieldSecondary, displayFieldExtra, displayFieldContent, and displayFieldImage.

#Form Layout

Datastores and Object Fields can define a tabs and sections array. Tabs are currently under development, and thus, do nothing.

The form is described by a list of sections. These sections are shown vertically in the order they're defined in the array. Any Fields not specified in the form's sections are hidden. Here's an example:

sections: [
  {
    rows: [1, 1, 1],
    items: [
      {type: 'field', field: 'title'},
      {type: 'field', field: 'excerpt'},
      {type: 'field', field: 'body'},
    ]
  },
  {
    rows: [1, 1],
    items: [
      {type: 'field', field: 'metaTitle'},
      {type: 'field', field: 'metaDescription'},
    ]
  },
  {
    location: 'sidebar',
    rows: [2, 1, 1, 1, 1, 1],
    items: [
      {type: 'field', field: 'isFeatured'}, // first row
      {type: 'field', field: 'isHidden'},
      {type: 'field', field: 'slug'}, // second row
      {type: 'field', field: 'featuredImage'}, // third row
      {type: 'field', field: 'publishedAt'}, // fourth row
      {type: 'field', field: 'category'}, // fifth row
      {type: 'field', field: 'author'}, // sixth row
    ]
  },
]

Each section has a location which is either "main" or "sidebar" and defaults to "main". It then has an array called rows which defines how many items go into each row. You can see in the sidebar in this example that the isFeatured and isHidden Fields will be beside each other. It is recommended you do no more than 4 columns in the main sections and 2 columns in the sidebar.

Each item in the items array has a type. The only type available now is "field" which requires that you specify a field property which is the name of the field to show. This can be a Field from the Datastore or one of its Shared Fields. You can also have null as an item instead of an object for an empty space for that column.

In the future, additional item types will be added.

#Display Fields

#Sorting Fields

#Archive Fields

#Build-time Properties

An example function is below. For more information, see Collection Functions

{
  type: 'instance',
  script: 'function doStuff(arg1, arg2) {\n  //do stuff\n}',
}

To make a function available on each DataItem (blogPost.getRelated()), use type: 'instance'. To make the function available on the Datastore (blogPostList.getRecentPosts()), use type: 'static'.

#User Modification

Collections created by your Addon behave slightly differently than Collections created by the user. The following rules apply:

• Any Datastores your Addon creates will be automatically deleted when the Addon is uninstalled. This includes all of its DataItems including those created by the user.
• The user cannot create or delete DataItems in any Datastore you create. You can specify isAddonDataItemCreateEnabled: true in the Datastore to allow the user to create and delete their own DataItems, but still not delete any created by your Addon. Specify isAddonDataItemDeleteEnabled: true in the Datastore to allow the user to delete DataItems created by your Addon.
• The user cannot change the name of the Datastore or whether it is global, but can change whether it shows in the Sidebar, its Sorting Fields, Archive behavior, and its Display Fields.
• The user can rearrange Fields, hide Fields from the form, and add their own, but not delete Fields you have created.
• The user can add their own enumValues to enum Fields but not remove enumValues your Addon has created. To prevent the user from creating their own enumValues, set isEnumValueCreateDisabled: true on the field.
• The user can modify the assetUploadPath and mediaUploadPath on Asset, Media, and Rich Text Fields.
• The user can create their own Collection Functions but not remove ones you have created.

You must write your Addon in a way that allows for the user to extend your Addon's Datastore. They are expected to add their own fields as needed and it is part of MercuryCMS' design to allow the user to combine multiple Addons' data in their own Collections and Components. Do not write code that routinely destroys and recreates Datastore field schema or destroys all current schema when updating.

#Getting Datastores

You can get a list of all of your Datastores by calling cms.getDatastores(). This will return a full list of the Datastores your Addon has created and does not include any created by the user or other Addons.

// use static-cms-addon
import cms from 'static-cms-addon'

let datastores = await cms.getDatastores()
console.log(datastores.map(datastore => datastore.name)) // ['Blog Post', 'Category', 'Author']

// use axios
let response = await axios.get(`http://localhost:${cmsPort}/api/addon/${addonId}/datastore`)
console.log(response.data.datastores.map(datastore => datastore.name)) // ['Blog Post', 'Category', 'Author']

#Creating Datastores

You can create Datastores by using cms.upsertDatastore(). This function will look to see if a specific Datastore exists and update it, or create it if it doesn't exist. This will return the created Datastore including its assigned _id. You can then use that _id when creating Reference Fields.

You typically want to create Datastores right when your Addon starts. Updating Datastores will this function will not overwrite user-managed settings like any functions they have created, custom fields they've added, etc.

let datastores = await cms.getDatastores()
let blogCategoryDatastore = datastores.find(datastore => datastore.name == 'Blog Category')
let blogAuthorDatastore = datastores.find(datastore => datastore.name == 'Blog Author')

let blogPostDatastoreDef = {
  name: 'Blog Post',
  description: 'Blog Posts imported from WordPress',
  icon: 'edit',
  displayField: 'title',
  displayFieldSecondary: '',
  displayFieldContent: 'body',
  displayFieldImage: 'featuredImage',
  sortBy: 'publishedAt',
  sortOrder: 'desc',
  fields: [
    {name: 'Title'},
    {name: 'Excerpt'},
    {name: 'Body', type: 'richText'},
    {name: 'Meta Title'},
    {name: 'Meta Description'},
    {name: 'Is Featured', type: 'boolean'},
    {name: 'Is Hidden', type: 'boolean'},
    {name: 'Slug', computedValue: '{{ this.title }}', format: [{type: 'kebabcase'}]},
    {name: 'Featured Image', type: 'media', mediaType: 'image'},
    {name: 'PublishedAt', type: 'date', dateType: 'datetime'},
    {name: 'Category', type: 'reference', referenceTo: blogCategoryDatastore._id},
    {name: 'Author', type: 'reference', referenceTo: blogAuthorDatastore._id}
  ],
  sections: [
    {
      rows: [1, 1, 1, 1, 1],
      items: [
        {type: 'field', field: 'title'},
        {type: 'field', field: 'excerpt'},
        {type: 'field', field: 'body'},
      ]
    },
    {
      rows: [1, 1],
      items: [
        {type: 'field', field: 'metaTitle'},
        {type: 'field', field: 'metaDescription'},
      ]
    },
    {
      location: 'sidebar',
      rows: [2, 1, 1, 1, 1, 1],
      items: [
        {type: 'field', field: 'isFeatured'},
        {type: 'field', field: 'isHidden'},
        {type: 'field', field: 'slug'},
        {type: 'field', field: 'featuredImage'},
        {type: 'field', field: 'publishedAt'},
        {type: 'field', field: 'category'},
        {type: 'field', field: 'author'},
      ]
    },
  ]
}

// use static-cms-addon
import cms from 'static-cms-addon'

let blogPostDatastore = await cms.upsertDatastore({name: 'Blog Post'}, blogPostDatastoreDef, 'Added Meta Title and Meta Description.')
console.log(blogPostDatastore._id) // "639e58c84b851d93f27dc830"

// use axios
let response = await axios.post(`http://localhost:${cmsPort}/api/addon/${addonId}/datastore`, blogPostDatastoreDef)
console.log(response.data.datastore._id) // "639e58c84b851d93f27dc830"

The first argument to upsertDatastore() is the fields to match against. This should typically just be name. The second argument is the Datastore definition, and the third argument is an optional Publish Comment. You can use this to provide information about what changed in the Datastore. This will not be used if the Datastore is new, and will only be shown if the Datastore you are upserting has actually changed.

When specifying reference fields, instead of using the reference Datastore's _id, you can instead use their camelCase name. For example, to reference a Datastore named "Blog Author", you could use {name: 'Author', type: 'reference', referenceTo: 'blogAuthor'}. The reference Datastore will still need to first exist before you can reference to it.

You can also load the Datastore from a zip or folder using cms.loadDatastorePackage().

let componentDef = cms.loadDatastorePackage('components/myComponent.datastore.zip').datastore
let component = await cms.upsertDatastore(componentDef)

#Deleting Datastores

You can use cms.deleteDatastores() to delete Datastores your Addon has created. This will also delete all of its DataItems.

// use static-cms-addon
import cms from 'static-cms-addon'

let datastores = await cms.getDatastores()
let datastore = datastores.find(datastore => datastore.name == 'My Datastore')
await cms.deleteDatastores([datastore._id])

// use axios
let response = await axios.get(`http://localhost:${cmsPort}/api/addon/${addonId}/datastore`)
let datastore = response.data.datastores.find(datastore => datastore.name == 'My Datastore')
await axios.post(`http://localhost:${cmsPort}/api/addon/${addonId}/datastore/delete`, {datastoreIds: [datastore._id]})

#DataItems

DataItem schema is shown below:

{

  // uneditable properties
  _id: '639e8eb64b851d93f27dc843',
  parentVersionId: '639e8ef54b851d93f27dc845',
  managedByAddonId: '639b8f837f5fb8a39404280a',
  createdAt: 1671335606730,
  updatedAt: 1671335669405,

  // datastore that determines dataitem fields
  datastoreId: '639e8eb64b851d93f27dc843',

  // general properties
  isEnabled: true,

  // field metadata
  overriddenFields: [],

  // field values
  fields: {},

}

#Uneditable DataItem Properties

#General Properties

#Field Metadata

These properties are automatically managed by the interface. For example, when the user clicks the "Override" switch and enters their own value in place of a Computed Value, MercuryCMS adds the name of the Field to overriddenFields.

#DataItem Fields

The fields object contains the values of the Fields. For example:

fields: {
  title: 'My Blog Post',
  excerpt: 'My post\'s excerpt',
  body: '# Some Heading\n\nSome text',
  metaTitle: 'My Blog Post',
  metaDescription: 'A post I made',
  isFeatured: true,
  isHidden: false,
  slug: 'my-blog-post',
  featuredImage: '639e92b24b851d93f27dc847',
  keywords: ['post', 'blog', 'my', 'demo'],
  publishedAt: 1671336660864,
  category: '639e92f14b851d93f27dc848',
  author: '639e92f84b851d93f27dc84a',
  review: {
    overriddenFields: [],
    fields: {
      title: 'My Review',
      stars: 4,
      body: 'This blog post is pretty good.',
      reviewer: {
        overriddenFields: [],
        fields: {
          name: 'John Doe',
          email: 'johndoe@example.com',
        }
      }
    }
  }
}

As you can see, all values are stored in their native type (string Fields are strings, number Fields are numbers, array Fields are arrays, etc. The only special Field type is object, which has its own fields property and Field metadata (overriddenFields etc.) When you retrieve a DataItem from the API, you will need to account for this format.

#Getting DataItems

You can get DataItems by using cms.getDataItem() and cms.getDataItems(). You can optionally provide a match key to getDataItems(). This is a Mongo-compatible query which supports all directives like $in and $ne. datastoreId is automatically added to your match query based on the path parameters in the request. You can also specify an array of dataItemIds rather than having to use a cumbersome combination of $in and $oid.

// use static-cms-addon
import cms from 'static-cms-addon'

let authorDataItem = await cms.getDataItem({datastoreId: authorDatastore._id, dataItemId: '639ea4aa4b851d93f27dc84f'})
let allBlogPostDataItems = await cms.getDataItems({datastoreId: blogPostDatastore._id})
let authorBlogPostDataItems = await cms.getDataItems({datastoreId: blogPostDatastore._id, match: {'fields.author': authorDataItem._id}})
let categoryDataItems = await cms.getDataItems({datastoreId: categoryDatastore._id, dataItemIds: ['639ea62e4b851d93f27dc851', '639ea6394b851d93f27dc857']})

// use axios
let response = await axios.get(`http://localhost:${cmsPort}/api/addon/${addonId}/dataitem/${authorDatastore._id}/639ea4aa4b851d93f27dc84f`)
let authorDataItem = response.data.dataItem

response = await axios.post(`http://localhost:${cmsPort}/api/addon/${addonId}/dataitem/${blogPostDatastore._id}/list`)
let allBlogPostDataItems = response.data.dataItems

response = await axios.post(`http://localhost:${cmsPort}/api/addon/${addonId}/dataitem/${blogPostDatastore._id}/list`, {match: 'fields.author': authorDataItem._id})
let authorBlogPostDataItems = response.data.dataItems

response = await axios.post(`http://localhost:${cmsPort}/api/addon/${addonId}/dataitem/${categoryDatastore._id}/list`, {dataItemIds: ['639ea62e4b851d93f27dc851', '639ea6394b851d93f27dc857']})
let categoryDataItems = response.data.dataItems

#Creating DataItems

You can create DataItems by calling cms.upsertDataItems(). You can either pass a DataItem that already contains fields, or you can pass raw: true to the request and pass in DataItems in the same format you would see them when Templating. This is very useful when pulling the data from an external API so you don't have to parse the raw objects yourself.

Note: You never need to set datastoreId on a DataItem. This is always done automatically by MercuryCMS.

let rawBlogPosts = [
  {
    title: 'My Blog Post',
    excerpt: 'My post\'s excerpt',
    body: '# Some Heading\n\nSome text',
    metaTitle: 'My Blog Post',
    metaDescription: 'A post I made',
    isFeatured: true,
    isHidden: false,
    slug: 'my-blog-post',
    featuredImage: '639e92b24b851d93f27dc847',
    keywords: ['post', 'blog', 'my', 'demo'],
    publishedAt: 1671336660864,
    category: '639e92f14b851d93f27dc848',
    author: '639e92f84b851d93f27dc84a',
    review: {
      title: 'My Review',
      stars: 4,
      body: 'This blog post is pretty good.',
      reviewer: {
        name: 'John Doe',
        email: 'johndoe@example.com',
      }
    }
  }
]

// use static-cms-addon
import cms from 'static-cms-addon'

let blogPostDataItems = await cms.upsertDataItems({
  datastoreId: blogPostDatastore._id,
  match: ['fields.slug'],
  dataItems: rawBlogPosts,
  publishComment: 'Import from my website',
  raw: true,
})
console.log(blogPostDataItems[0].fields.review.fields.title) // "My Review"

// use axios
let response = await axios.post(`http://localhost:${cmsPort}/api/addon/${addonId}/dataitem/${blogPostDatastore._id}`, {match: ['fields.slug'], dataItems: rawBlogPosts, publishComment: 'Import from my website', raw: true})
console.log(response.data.dataItems[0].fields.review.fields.title) // "My Review"

The match option allows you to provide an array of values that will be checked on each DataItem. In the above example, each Blog Post being passed in will be matched against an existing Blog Post based on its slug. You can provide multiple values to match against.

The Publish Comment is optional. You can use this to provide information about what changed in the DataItem. This will not be used if the DataItem is new, and will only be shown if the DataItem you are upserting has actually changed.

You can also create individual DataItems using cms.upsertDataItem(). In the following example, an object is used for match, but this call also supports simply passing ['fields.slug'] as well.

let blogPostDataItem = await cms.upsertDataItem({
  datastoreId: blogPostDatastore._id,
  match: {'fields.slug': blogPostDataItem.slug},
  dataItems: rawBlogPost,
  publishComment: 'Import from my website',
  raw: true,
})
console.log(blogPostDataItem.fields.review.fields.title) // "My Review"

// use axios
let response = await axios.post(`http://localhost:${cmsPort}/api/addon/${addonId}/dataitem/${blogPostDatastore._id}`, {match: {'fields.slug': rawBlogPost.slug}, dataItems: [rawBlogPost], publishComment: 'Import from my website', raw: true})
console.log(response.data.dataItems[0].fields.review.fields.title) // "My Review"

#Deleting DataItems

You can delete DataItems by using cms.deleteDataItems(). You must provide a match key. This is a Mongo-compatible query which supports all directives like $in and $ne. datastoreId is automatically added to your match query based on the path parameters in the request. You can also specify an array of dataItemIds rather than having to use a cumbersome combination of $in and $oid, or an array of notDataItemIds rather than $nin and $oid.

// use static-cms-addon
import cms from 'static-cms-addon'

let authorDataItems = await cms.getDataItems({datastoreId: authorDatastore._id, match: {'fields.name': 'John Doe'}})
let authorDataItem = authorDataItems[0]
await cms.deleteDataItems({datastoreId: blogPostDatastore._id, match: {'fields.author': authorDataItem._id}})

// use axios
await axios.post(`http://localhost:${cmsPort}/api/addon/${addonId}/dataitem/${blogPostDatastore._id}/delete`, {match: {'fields.author', authorDataItem._id}})

#Enabling and Disabling Data Items

You can enable and disable DataItems using cms.enableDataItems() and cms.disableDataItems().

// use static-cms-addon
import cms from 'static-cms-addon'

await cms.enableDataItems({datastoreId: storeItemDatastore._id, match: {'fields.onSale': true}, publishComment: 'Listing sale items.'})
await cms.disableDataItems({datastoreId: storeItemDatastore._id, match: {'fields.sourceId': 863}, publishComment: 'Disabling discount supplier.'})

// use axios
await axios.post(`http://localhost:${cmsPort}/api/addon/${addonId}/dataitem/${storeItemDatastore._id}/enable`, {match: {'fields.onSale': true}, publishComment: 'Listing sale items.'})
await axios.post(`http://localhost:${cmsPort}/api/addon/${addonId}/dataitem/${storeItemDatastore._id}/disable`, {match: {'fields.sourceId': 863}, publishComment: 'Disabling discount supplier.'})

You can also specify dataItemIds or notDataItemIds. This is useful when importing from an external source and disabling all DataItems except the ones you just imported. Do this rather than deleting all of the DataItems not found, so the user can manually enable them if they wish, and their overrides won't be destroyed.

#Importing From External APIs

One of the most common use-cases for Addons is to pull data from an external source and make them available in MercuryCMS for Templating. Because of this, there are a number of built-in features that allow you to make this as simple as possible. Let's do a simple example first, then build on it.

import cms from 'static-cms-addon'

let storeItemDatastore = await cms.upsertDatastore({name: 'Store Item'}, {
  name: 'Store Item',
  description: 'Your Store Items from your Example.com Store',
  icon: 'shopping_bag',
  fields: [
    {name: 'ID', type: 'number', isReadonly: true, isManagedByAddon: true},
    {name: 'Price', type: 'number', isReadonly: true, isManagedByAddon: true},
    {name: 'Name', isReadonly: true, isManagedByAddon: true},
  ],
  sections: [
    {
      rows: [1],
      items: [
        {type: 'field', field: 'name'},
      ]
    },
    {
      location: 'sidebar',
      rows: [1, 1],
      {type: 'field', field: 'id'},
      {type: 'field', field: 'price'},
    }
  ]
})

let response = await axios.get('https://example.com/api/items')
let storeItems = response.data.storeItems
console.log(storeItems)
// [
//   {id: 736273, price: 999, name: 'Coffee Mug'},
//   {id: 137823, price: 1299, name: 'Hat'},
//   {id: 321232, price: 2499, name: 'T-Shirt'},
// ]

let dataItems = await cms.upsertDataItems({
  datastoreId: storeItemDatastore._id,
  match: ['id'],
  dataItems: storeItems,
  raw: true
})
await cms.disableDataItems({datastoreId: storeItemDatastore._id, notDataItemIds: dataItems.map(dataItem => dataItem._id)})

In this example, you can see how easy it is for us to update the Store Item Collection and disable unused items. The user can use this data via storeItemList when Templating and we can provide some Components for the user to quickly get started.