@volvo-cars/content-management-client NPM

@volvo-cars/content-management-client

Attention!

This package is a wrapper around some of the content management APIs, it's intended to help you integrate dictionaries, contentTypes, editorialComponents and pageTypes in your projects as easily as possible. This package is designed for server-side Node.js applications. Attempting to use it client-side, in either the browser or any other environment will not work.

Installation

yarn add @volvo-cars/content-management-client

npm install @volvo-cars/content-management-client

This adds @volvo-cars/content-management-client to your projects dependencies in your package.json:

"dependencies": {
    "@volvo-cars/content-management-client": "*"
}

CLI

Config

A configuration is required to use the CLI, create a file with the following configuration and export it:

// ./src/content-management/config.js
module.exports = {
  path: './src/content-management', // required
  contentManagementApiKey: process.env.CONTENT_MANAGEMENT_API_KEY, // required
  applicationId: 'sampleApplication', // required
  defaultDataSource: 'dotcom-sitecore-test', // optional
};

path:string a path where dictionaries/contentTypes and other necessary files can be written relative to your project root.
applicationId:string Id of your application in the CMS.
contentManagementApiKey:string The API key for your product.
defaultDataSource?:string: Default dataSource to be used when not explicitly set in the CLI.

Dictionaries

`cmc dictionary:create`

Create a dictionary

USAGE
  $ cmc dictionary:create

OPTIONS
  -N, --namespace=namespace      (required) Namespace in which this dictionary will belong to
  -c, --config=config            Location of your config file relative the current working directory
  -d, --dataSources=dataSources  Data sources to push  dictionaries to
  -h, --help                     show CLI help
  -n, --name=name                (required) Name of the dictionary to create
  --skipPush                     Create dictionary locally without pushing to CMS

EXAMPLES
  $ yarn cmc dictionary:create
       --name "dictionaryName" --namespace DictionaryNamespace --config src/content-management/config.js
  $ yarn cmc dictionary:create
       -n "carBadges" --namespace CarBadges --config src/content-management/config.js

`cmc dictionary:publish`

Publish one or more dictionaries

USAGE
  $ cmc dictionary:publish

OPTIONS
  -c, --config=config                    Location of your config file relative the current working directory
  -d, --dataSource=dataSource            Data sources to publish dictionaries in
  -h, --help                             show CLI help

  --dictionariesPaths=dictionariesPaths  Which dictionaries to publish. Should be in the format namespace.name. If this
                                         option is not specified, all dictionaries will be updated in that dataSource

EXAMPLES
  $ yarn cmc dictionary:publish --config src/content-management/config.js --dataSource dotcom-sitecore-test --publish
  $ yarn cmc dictionary:publish --dictionariesPaths=mynamespace.mydictionary --config src/content-management/config.js

`cmc dictionary:update`

Update/push one or more dictionaries

USAGE
  $ cmc dictionary:update

OPTIONS
  -P, --publish                          Publish dictionaries after updating. Will not publish dictionaries unless this
                                         is specified

  -c, --config=config                    Location of your config file relative the current working directory

  -d, --dataSource=dataSource            Data sources to push dictionaries to

  -h, --help                             show CLI help

  --skipTypeEmit                       Skip creating or updating `DictionaryItemTypes` file

  --dictionariesPaths=dictionariesPaths  Which dictionaries to update. Should be in the format namespace.name. If this
                                         option is not specified, all dictionaries will be updated in that dataSource

EXAMPLES
  $ yarn cmc dictionary:update --config src/content-management/config.js --dataSource dotcom-sitecore-test
  $ yarn cmc dictionary:update --dictionariesPaths=mynamespace.mydictionary --config src/content-management/config.js

`cmc dictionary:push`

An alias for cmc dictionary:update

`cmc dictionary:types`

Generate item types for all dictionaries in your project

USAGE
  $ cmc dictionary:types ACTION

ARGUMENTS
  ACTION  (generate) [default: generate] Generate types

OPTIONS
  -c, --config=config  Location of your config file relative the current working directory
  -h, --help           show CLI help

EXAMPLE
  $ yarn cmc dictionary:types generate

`cmc dictionary help`

display help for cmc dictionary

Manage everything related to dictionaries

USAGE
  $ cmc dictionary:COMMAND

COMMANDS
  dictionary:create   Create a dictionary
  dictionary:publish  Publish one or more dictionaries
  dictionary:update   Update one or more dictionaries

ContentTypes

`cmc content:create TYPE`

Create a content type, an editorial component or a page type

USAGE
  $ cmc content:create TYPE

ARGUMENTS
  TYPE  (content-type|editorial-component|page-type) Which type to scaffold

OPTIONS
  -N, --namespace=namespace  (required) Namespace in which this content type will belong to
  -c, --config=config        Location of your config file relative the current working directory
  -h, --help                 show CLI help
  -i, --id=id                (required) camelCase id of your content type
  -n, --name=name            (required) Name of the content type to create

EXAMPLES
  $ yarn cmc content:create content-type
       -n "My ContentType" --id camelCaseId --namespace myNameSpace --config src/content-management/config.js
  $ yarn cmc content:create editorial-component
       -n "My EditorialComponent" --id camelCaseId --namespace myNameSpace --config src/content-management/config.js
  $ yarn cmc content:create page-type
       -n "My PageType" -i camelCaseId -N myNameSpace -c src/content-management/config.js

`cmc content:list TYPE`

List all content types, editorial components and page types in your project

USAGE
  $ cmc content:list TYPE

ARGUMENTS
  TYPE  (content-type|editorial-component|page-type) Which type to list

OPTIONS
  -c, --config=config     Location of your config file relative the current working directory
  -x, --extended          show extra columns
  --columns=columns       only show provided columns (comma-separated)
  --csv                   output is csv format [alias: --output=csv]
  --filter=filter         filter property by partial string matching, ex: name=foo
  --no-header             hide table header from output
  --no-truncate           do not truncate output to fit screen
  --output=csv|json|yaml  output in a more machine friendly format
  --sort=sort             property to sort by (prepend '-' for descending)

EXAMPLE
  $ yarn cmc content:list content-type --config src/content-management/config.js

`cmc content:props ACTION`

Generate props for all content types, editorial components and page types in your project

USAGE
  $ cmc content:props ACTION

ARGUMENTS
  ACTION  (generate) [default: generate] Generate props

OPTIONS
  -h, --help   show CLI help
  -w, --watch  Watch for content type changes

EXAMPLE
  $ yarn cmc content:props generate

`cmc content:push TYPE`

Push all content types, editorial components or page types

USAGE
  $ cmc content:push TYPE

ARGUMENTS
  TYPE  (content-type|editorial-component|page-type|all) Which type to push to the CMS

OPTIONS
  -c, --config=config            [default: src/content-management/config.js] Location of your config file
                                 relative the current working directory

  -d, --dataSources=dataSources  Data sources to push content types to

  -h, --help                     show CLI help

  -l, --legacy-push              Use legacy push which creates and publishes content types separately


  -r, --retries=retries          [default: 10] Number of retries before giving up on pushing content types,
                                 awaits 10 seconds in between each retry


  --changedSince=[branch/commit] Pushes content types related to the changes since the provided branch or commit
                                 hash. If the current branch has diverged from the given branch, then only changed content types locally will be pushed

EXAMPLES
  $ yarn cmc content:push content-type
       -d dotcom-sitecore-qa -c src/content-management/config.js
  $ yarn cmc content:push editorial-component
       --dataSources dotcom-sitecore-qa --config src/content-management/config.js
  $ yarn cmc content:push page-type
       -d dotcom-sitecore-qa -c src/content-management/config.js

`cmc content help`

Manage everything related to content types

USAGE
  $ cmc content:COMMAND

COMMANDS
  content:create  Create a content type, an editorial component or a page type
  content:list    List all content types, editorial components and page types in your project
  content:props   Generate props for all content types, editorial components and page types in your project
  content:push    Push all content types, editorial components or page types

Node

Dictionaries Node

Create a dictionary

import { createDictionary } from '@volvo-cars/content-management-client/management';
// check api docs
const baseConfig = {
  path: './src/content-management',
  contentManagementApiKey: process.env.CONTENT_MANAGEMENT_API_KEY,
  applicationId: process.env.CONTENT_SERVICES_APPLICATION_ID,
};
(async () => {
  try {
    // check api docs
    await createDictionary(baseConfig, {
      name: 'mydictionary',
      namespace: 'mynamespace',
      dataSources: ['dotcom-sitecore-test'],
    });
  } catch (error) {
    //handle your error
  }
})();

This will create a dictionary in the dataSource dotcom-sitecore-test and write a master file to ./src/content-management/dictionaries/mynamespace/mydictionary.json in the following format:

{
  "id": {
    "dotcom-sitecore-test": "some id"
  },
  "items": {},
  "name": "mydictionary",
  "namespace": "mynamespace"
}

Creating the same dictionary in another dataSource will add that dataSource id to the json file.

The idea is that this json file is the master file and is the source of truth not the CMS.

Update a dictionary

Now that you created the dictionary, you can go ahead and add items to the items property in the json file:

"items":{
    "item1": "I am item 1 {parameter1} {parameter2}",
    "item2": "I am item 2"
}

And then update the dictionary:

import { updateDictionaries } from '@volvo-cars/content-management-client/management';
...
(async () => {
    try {
      // check api docs
      await updateDictionaries(baseConfig,{
        dataSource: 'dotcom-sitecore-test',
        dictionariesPaths: ['mynamespace.mydictionaryname']
      });
    } catch (error) {
      //handle your error
    }
})();

Publish a dictionary

import { publishDictionaries } from '@volvo-cars/content-management-client/management';
...
(async () => {
    try {
      //check api docs
      await publishDictionaries(baseConfig,{
        dataSource: 'dotcom-sitecore-test',
        dictionariesPaths: ['mynamespace.mydictionaryname']
      });
    } catch (error) {
      //handle your error
    }
})();

You can also update and pusblish at once:

import { updateAndPublishDictionaries } from '@volvo-cars/content-management-client/management';
...
(async () => {
  try{
    await updateAndPublishDictionaries(baseConfig,{
      dataSource: 'dotcom-sitecore-test',
      dictionariesPaths: ['mynamespace.mydictionaryname']
  });
  }catch(error){
    //handle error
  }

})();

Node API

baseConfig

baseConfig
- path:string a path where dictionaries and other nececcary files can be written relative to your project root.
- applicationId:string Id of your application
- contentManagementApiKey?:string The API key for your product.
- asyncWait?:number a number in milliseconds indicating how long you are willing to wait for the api to finish updating/publishing before rejecting. Defaults to 60000.
- VCCEnv?: qa | prod Which VCC consumer api to use. Can be qa(https://gw.qa.consumer.api.volvocars.com) or prod(https://gw.consumer.api.volvocars.com)

createDictionary(baseConfig, options)

options
- name:string Name of your dictionary.
- namespace:string Namespace where the dictionary will belong
- dataSources:string[] DataSources in which this dictionary will be created
returns:Promise<void>

updateDictionary(baseConfig, options)

options
- dataSource:string DataSource to update the dictionary in.
- dictionariesPaths?:string(namespace.name)[] Which dictionaries to update. Should be in the format namespace.name. If this option is not specified, all dictionaries will be updated in that dataSource.
- languageVersion:string Which languageVersion to update. You usually want to always manage the same languageVersion locally, usually en. Will use the languageVersion specified in createClient config as default.
returns:Promise<void>