Extension

View as Markdown

Extension

An extension adds a custom field, widget, dashboard widget, JSON Rich Text Editor (JSON RTE) plugin or asset sidebar to the Contentstack interface. The Extension class manages the extensions of a stack through the Content Management API (CMA). Use this class to

  • create an extension from a source URL or from source code
  • upload an extension from an HTML file
  • list the extensions of a stack, or read one by its UID
  • change or delete an extension

Call the extension method of the Stack class to get an object.

Note The API reference describes extensions as the legacy approach and recommends the UI locations of the Contentstack App Framework for new work.

Instance State

  • Call stack.extension() without a UID to work with the extensions of the stack, for example create and query.
  • Call stack.extension('<EXTENSION_UID>') to work with one extension, for example fetch and delete.
  • Each form has only its own methods. A method of the other form is undefined, and calling it throws TypeError.
  • The objects that create, upload, fetch, update and query().find() return are the single-extension form.

The Method Index below lists the full set for each form.

Warning stack.extension('') returns the collection form, because the SDK treats an empty string as no UID. Check the UID before you build the object.

Class-Level Notes

Extension types.

  • One set of requests covers every kind of extension. The type key of the extension sets the kind, for example field, widget, dashboard, rte_plugin or asset_sidebar_widget.

Branch scoping.

  • When you create the stack with branch_uid, every request from this class sends the branch header, and the API works with the extensions of that branch.

Headers.

  • Every request sends the headers of this object. The object shares the header map of the stack until you change its headers with addHeader, addHeaderDict or removeHeader. The first change gives the object its own copy.

Rate limiting and retry.

  • This SDK automatically retries on 429 with configurable delay and attempt limits.

Additional Resource For more information on the retry options and their defaults, refer to the Contentstack documentation.

Capability Matrix

CapabilitySupportedNotes / Alternative
Set the widget scope with uploadNoUpload without scope, then set scope on the result and call update
Upload from a browserNoupload reads a file path with Node.js fs. Use create with srcdoc instead
Update fields without fetching firstNoupdate sends the properties of the object. Call fetch, change the result, then call update

Method Index

Work with the extensions of a stack. Available on stack.extension().

Method NameReturnsDescription
createThe new extension.Creates an extension from a URL or source code.
uploadThe uploaded extension.Uploads an extension from an HTML file.
queryA query for extensions, sent when you call find(), findOne() or count().Lists the extensions of the stack.

Work with one extension. Available on stack.extension('<EXTENSION_UID>').

Method NameReturnsDescription
fetchThe requested extension.Reads one extension.
updateThe updated extension.Saves changes to the extension.
deleteThe API response with a notice.Deletes the extension.

Set request headers. Available on both forms.

Method NameReturnsDescription
addHeaderThe same extension object, for chaining.Adds one request header.
addHeaderDictThe same extension object, for chaining.Adds several request headers.
removeHeaderThe same extension object, for chaining.Removes one request header.

Class-Level Snippet

The snippet below creates a custom field from a source URL, then lists every custom field of the stack.

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  const extension = await stack.extension().create({
    extension: {
      title: 'docs-test-color-picker',
      type: 'field',
      data_type: 'text',
      src: 'https://example.com/color-picker.html'
    }
  })
  console.log(extension.uid)

  const fields = await stack.extension().query({ query: { type: 'field' } }).find()
  fields.items.forEach((field) => console.log(field.uid, field.title))
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

Methods

Each method of the Extension class has its own section below, with its parameters, validation rules, behavior, and examples.

addHeader

addHeader adds one header to every request that this extension object sends.

NameTypeDescription
key (required)string

Header name, for example x-request-id.

Default: Not applicable
value (required)string

Header value to send.

Default: Not applicable

Returns: Extension. The same extension object, for chaining.

Validation

  • There is no client-side validation. A null or undefined key leaves the headers unchanged, and addHeader returns the same object.
  • An invalid value surfaces as a rejected promise from the request method you call next.

Behavior

  • Client-side only. addHeader sends no request.
  • Until its first header change, this object shares the header map of the stack. The first change copies that map, so the header applies to this object only, not to the stack or to other objects of the same stack.
  • Every request method of this object sends its headers. A key that the object already holds gets the new value.
  • query copies the headers of this object when you call it. Add the header first, then call query.

Example

Basic usage: tag the requests of one extension object

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

const extension = stack.extension('<EXTENSION_UID>').addHeader('x-request-id', 'docs-123')
// Every request this object sends from now on carries the header
console.log(extension.stackHeaders['x-request-id'])

addHeaderDict

addHeaderDict adds several headers to every request that this extension object sends.

NameTypeDescription
headerDict (required)object

Header names and values to add.

Default: Not applicable

Returns: Extension. The same extension object, for chaining.

Validation

  • There is no client-side validation. A null value, or a value that is not an object, leaves the headers unchanged, and addHeaderDict returns the same object.
  • An invalid value surfaces as a rejected promise from the request method you call next.

Behavior

  • Client-side only. addHeaderDict sends no request.
  • Copies every key of headerDict into the headers of this object. A key that the object already holds gets the new value.
  • The first header change on this object copies the header map that it shares with the stack. The change then applies to this object only.

Example

Basic usage: send two extra headers from one extension object

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

const extension = stack.extension('<EXTENSION_UID>').addHeaderDict({ 'x-request-id': 'docs-123', 'x-trace-id': 'docs-456' })
// fetch, update and delete on this object send both headers
console.log(extension.stackHeaders)

create

create creates an extension in the stack from a source URL or from source code.

NameTypeDescription
data (required)object

Request body with the extension under extension.

Default: Not applicable
data.extension.title (required)string

Title of the extension.

Default: Not applicable
data.extension.type (required)string

Kind of extension, for example field or widget.

Default: Not applicable
data.extension.srcstring

URL of an externally hosted extension.

Default: API default
data.extension.srcdocstring

Source code that Contentstack hosts.

Default: API default
data.extension.data_typestring

Data type of a custom field, for example text.

Default: API default
data.extension.tagsstring[]

Tags for the extension.

Default: API default
data.extension.multipleboolean

Lets a custom field hold several values.

Default: API default
data.extension.configstring

Configuration that the extension reads.

Default: API default
data.extension.scopeExtensionScope

Content types where a widget appears.

Default: API default
data.extension.enableboolean

Turns a dashboard widget on.

Default: API default
data.extension.default_widthstring

Width of a dashboard widget, full or half.

Default: API default
paramobject

Query parameters, sent as given.

Default: undefined (sends no query parameters)
param.include_branchboolean

Adds the _branch key to the response.

Default: API default

Returns: Promise<Extension>. The new extension.

Validation

  • There is no client-side validation. create sends data as the JSON body as it is.
  • create exists only on stack.extension(). On stack.extension('<EXTENSION_UID>') it is undefined, and calling it throws TypeError.
  • The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends POST /v3/extensions with data as the body and every key of param as a query parameter.
  • Pass src for an externally hosted extension, as Create a custom field with source URL describes. Pass srcdoc for source code that Contentstack hosts, as Create a custom field with source code describes.
  • A widget takes scope, for example { content_types: ['$all'] }, as Create widget with source URL describes.
  • Resolves to a new Extension object that holds the created extension, with fetch, update and delete. When the API answers with an empty body, it resolves to { status, statusText } instead.
  • To create an extension from an HTML file, use the upload method.

Example

Basic usage: create a custom field from a source URL

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  const extension = await stack.extension().create({
    extension: {
      title: 'docs-test-color-picker',
      type: 'field',
      data_type: 'text',
      src: 'https://example.com/color-picker.html'
    }
  })
  console.log(extension.uid)
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

All parameters: create a custom field from source code on a branch

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>', branch_uid: '<BRANCH>' })

try {
  const extension = await stack.extension().create({
    extension: {
      title: 'docs-test-rating',
      type: 'field',
      data_type: 'number',
      srcdoc: '<html><body>Rating field</body></html>',
      tags: ['rating', 'docs'],
      multiple: false,
      config: '{"max": 5}'
    }
  }, { include_branch: true })
  console.log(extension.uid, extension._branch)
} catch (error) {
  console.error(error.errorMessage)
}

Create a widget for every content type

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  const widget = await stack.extension().create({
    extension: {
      title: 'docs-test-seo-widget',
      type: 'widget',
      src: 'https://example.com/seo-widget.html',
      scope: { content_types: ['$all'] }
    }
  })
  console.log(widget.uid)
} catch (error) {
  console.error(error.errorMessage)
}

Create a dashboard widget at half width

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  const dashboard = await stack.extension().create({
    extension: {
      title: 'docs-test-dashboard',
      type: 'dashboard',
      src: 'https://example.com/dashboard.html',
      enable: true,
      default_width: 'half'
    }
  })
  console.log(dashboard.uid)
} catch (error) {
  console.error(error.errorMessage)
}

delete

delete removes the extension whose UID you passed to stack.extension('<EXTENSION_UID>') from the stack.

NameTypeDescription
paramobject

Query parameters, sent as given.

Default: {}

Returns: Promise<Response>. The API response with a notice.

Warning A successful delete removes the extension permanently, and you cannot undo it.

Validation

  • There is no client-side validation.
  • delete exists only on stack.extension('<EXTENSION_UID>') and on the Extension objects that requests return. On stack.extension() it is undefined, and calling it throws TypeError.
  • The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends DELETE /v3/extensions/{extension_uid} with every key of param as a query parameter, as Delete custom field describes. The API reference lists no query parameters for this request.
  • Resolves to the response body, which carries notice. When the API answers with an empty body, it resolves to { status, statusText } instead.

Example

Basic usage: delete an extension

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  const response = await stack.extension('<EXTENSION_UID>').delete()
  console.log(response.notice)
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

All parameters: pass query parameters

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  // delete sends every key of the object as a query parameter. The API lists none for this request.
  const response = await stack.extension('<EXTENSION_UID>').delete({})
  console.log(response.notice)
} catch (error) {
  console.error(error.errorMessage)
}

fetch

fetch retrieves the extension whose UID you passed to stack.extension('<EXTENSION_UID>').

NameTypeDescription
paramobject

Query parameters, sent as given.

Default: {}
param.include_branchboolean

Adds the _branch key to the response.

Default: API default

Returns: Promise<Extension>. The requested extension.

Validation

  • There is no client-side validation.
  • fetch exists only on stack.extension('<EXTENSION_UID>') and on the Extension objects that requests return. On stack.extension() it is undefined, and calling it throws TypeError.
  • The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends GET /v3/extensions/{extension_uid} with every key of param as a query parameter, as Get a single custom field describes. The same request reads widgets, dashboard widgets, JSON RTE plugins and asset sidebar extensions.
  • Resolves to a new Extension object that the SDK builds from the extension key of the response, with fetch, update and delete.

Example

Basic usage: read one extension

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  const extension = await stack.extension('<EXTENSION_UID>').fetch()
  console.log(extension.title, extension.type)
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

All parameters: read an extension of a branch with its branch UID

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>', branch_uid: '<BRANCH>' })

try {
  const extension = await stack.extension('<EXTENSION_UID>').fetch({ include_branch: true })
  console.log(extension.title, extension._branch)
} catch (error) {
  console.error(error.errorMessage)
}

query

query builds a request that lists the extensions of the stack. It sends nothing until you call find(), findOne() or count() on the result.

NameTypeDescription
paramsobject

Query parameters for the list request.

Default: {}
params.queryobject

Filter condition, sent as JSON, for example by type.

Default: API default
params.scopestring

Content type UID whose widgets to list.

Default: API default
params.include_branchboolean

Adds the _branch key to each item.

Default: API default

Returns: Query. A query for extensions, sent when you call find(), findOne() or count().

Validation

  • There is no client-side validation.
  • query exists only on stack.extension(). On stack.extension('<EXTENSION_UID>') it is undefined, and calling it throws TypeError.
  • An invalid value surfaces as a rejected promise from the request method you call next.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • query sends no request. find(), findOne() and count() on the returned object each send GET /v3/extensions, as Get all custom fields describes.
  • The SDK sends params.query as a JSON string in the query parameter, and every other key of params as its own query parameter.
  • Filter by kind with query: { type: 'field' }, 'widget', 'dashboard', 'rte_plugin' or 'asset_sidebar_widget'. List the widgets of one content type with scope, as Get widgets of a content type describes.
  • The returned object copies the headers of this extension object when you call query. A header that you add to the extension object later does not reach it.
  • find() resolves to a collection whose items are Extension objects, each with fetch, update and delete. See the find method of the Query class for the collection.

Example

Basic usage: list the custom fields of a stack

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  const result = await stack.extension().query({ query: { type: 'field' } }).find()
  result.items.forEach((extension) => console.log(extension.uid, extension.title))
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

All parameters: list the widgets of one content type on a branch

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>', branch_uid: '<BRANCH>' })

try {
  const result = await stack.extension()
    .query({ query: { type: 'widget' }, scope: '<CONTENT_TYPE_UID>', include_branch: true })
    .find()
  result.items.forEach((widget) => console.log(widget.uid, widget._branch))
} catch (error) {
  console.error(error.errorMessage)
}

removeHeader

removeHeader removes one header from the requests that this extension object sends.

NameTypeDescription
key (required)string

Name of the header to remove.

Default: Not applicable

Returns: Extension. The same extension object, for chaining.

Validation

  • There is no client-side validation. A null or undefined key, or a key that the object does not hold, leaves the headers unchanged.
  • An invalid value surfaces as a rejected promise from the request method you call next.

Behavior

  • Client-side only. removeHeader sends no request.
  • Removing a header that the object shares with the stack first copies the shared map, so the stack and other objects keep the header.
  • The SDK adds some headers at request time, for example the authorization header of the client. removeHeader cannot remove those.

Example

Basic usage: send requests from one extension object without the branch header

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>', branch_uid: '<BRANCH>' })

const extension = stack.extension('<EXTENSION_UID>').removeHeader('branch')
// This object now works with the default branch
console.log(extension.stackHeaders.branch)

update

update saves your changes to the properties of this extension object, such as its title, source or scope.

NameTypeDescription
paramobject

Query parameters, sent as given.

Default: {}
param.include_branchboolean

Adds the _branch key to the response.

Default: API default

Returns: Promise<Extension>. The updated extension.

Validation

  • There is no client-side validation.
  • update exists only on stack.extension('<EXTENSION_UID>') and on the Extension objects that requests return. On stack.extension() it is undefined, and calling it throws TypeError.
  • The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends PUT /v3/extensions/{extension_uid} with every key of param as a query parameter, as Update a custom field describes.
  • The body is { extension: { ... } }, built from the properties of this object. The SDK leaves out uid, created_at, created_by, updated_at, updated_by, deleted_at, org_uid, api_key and its own internal properties.
  • Call fetch first and change the result. An object from stack.extension('<EXTENSION_UID>') holds only the UID, so update on it sends an empty extension object.
  • Resolves to a new Extension object that the SDK builds from the extension key of the response.

Example

Basic usage: rename an extension

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  const extension = await stack.extension('<EXTENSION_UID>').fetch()
  extension.title = 'docs-test-color-picker-v2'
  const updated = await extension.update()
  console.log(updated.title)
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

All parameters: limit a widget to one content type on a branch

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>', branch_uid: '<BRANCH>' })

try {
  const widget = await stack.extension('<EXTENSION_UID>').fetch()
  widget.scope = { content_types: ['<CONTENT_TYPE_UID>'] }
  const updated = await widget.update({ include_branch: true })
  console.log(updated.scope, updated._branch)
} catch (error) {
  console.error(error.errorMessage)
}

upload

upload creates an extension in the stack from an HTML file on disk.

NameTypeDescription
data (required)UploadExtensionData

Extension details and the file path.

Default: Not applicable
data.upload (required)string

Path of the HTML file to upload.

Default: Not applicable
data.title (required)string

Title of the extension.

Default: Not applicable
data.type (required)string

Kind of extension, for example field or widget.

Default: Not applicable
data.data_typestring

Data type of a custom field, for example text.

Default: undefined (not sent)
data.tagsstring[] | string

Tags, as an array or a comma-separated string.

Default: undefined (not sent)
data.multipleboolean

Lets a custom field hold several values.

Default: undefined (not sent)
data.enableboolean

Turns a dashboard widget on.

Default: undefined (not sent)
paramsobject

Query parameters, sent as given.

Default: undefined (sends no query parameters)
params.include_branchboolean

Adds the _branch key to the response.

Default: API default

Returns: Promise<Extension>. The uploaded extension.

Known issue: upload sends a scope object as the text [object Object] and skips a scope string, so it cannot set the content types of a widget. Upload without scope, then set scope on the returned extension and call update.

Validation

  • There is no client-side validation of the values.
  • upload exists only on stack.extension(). On stack.extension('<EXTENSION_UID>') it is undefined, and calling it throws TypeError.
  • The returned promise rejects with an Error whose code is ERR_INVALID_ARG_TYPE when data.upload is missing or is not a string. The SDK opens the file first, so it sends no request in this case.
  • The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends POST /v3/extensions as multipart/form-data, as Upload a custom field and Upload a widget describe. Every key of params goes in the query string.
  • The form holds extension[title], extension[data_type], extension[type], extension[tags], extension[multiple], extension[enable] and the file as extension[upload]. The SDK adds each value only when it has the type in the table above. It joins a tags array with commas and sends booleans as the text true or false.
  • upload does not send src, srcdoc, config or default_width. Set them with update after the upload, or use the create method instead.
  • upload reads the file with the Node.js fs module, so it works in Node.js only.
  • Resolves to a new Extension object that holds the uploaded extension, with fetch, update and delete.

Example

Basic usage: upload a custom field

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  const extension = await stack.extension().upload({
    upload: '<FILE_PATH>',
    title: 'docs-test-color-picker',
    type: 'field',
    data_type: 'text'
  })
  console.log(extension.uid)
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

All parameters: upload a dashboard widget on a branch

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>', branch_uid: '<BRANCH>' })

try {
  const extension = await stack.extension().upload({
    upload: '<FILE_PATH>',
    title: 'docs-test-dashboard',
    type: 'dashboard',
    data_type: 'text',
    tags: ['dashboard', 'docs'],
    multiple: false,
    enable: true
  }, { include_branch: true })
  console.log(extension.uid, extension._branch)
} catch (error) {
  console.error(error.errorMessage)
}

Edge case: upload a widget, then set its scope

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  // upload cannot send scope, so set it with update after the upload
  const widget = await stack.extension().upload({
    upload: '<FILE_PATH>',
    title: 'docs-test-seo-widget',
    type: 'widget'
  })
  widget.scope = { content_types: ['<CONTENT_TYPE_UID>'] }
  const updated = await widget.update()
  console.log(updated.scope)
} catch (error) {
  console.error(error.errorMessage)
}