Extension
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
| Capability | Supported | Notes / Alternative |
|---|---|---|
| Set the widget scope with upload | No | Upload without scope, then set scope on the result and call update |
| Upload from a browser | No | upload reads a file path with Node.js fs. Use create with srcdoc instead |
| Update fields without fetching first | No | update 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 Name | Returns | Description |
|---|---|---|
| create | The new extension. | Creates an extension from a URL or source code. |
| upload | The uploaded extension. | Uploads an extension from an HTML file. |
| query | A 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 Name | Returns | Description |
|---|---|---|
| fetch | The requested extension. | Reads one extension. |
| update | The updated extension. | Saves changes to the extension. |
| delete | The API response with a notice. | Deletes the extension. |
Set request headers. Available on both forms.
| Method Name | Returns | Description |
|---|---|---|
| addHeader | The same extension object, for chaining. | Adds one request header. |
| addHeaderDict | The same extension object, for chaining. | Adds several request headers. |
| removeHeader | The 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.
| Name | Type | Description |
|---|---|---|
| key (required) | string | Header name, for example x-request-id. |
| value (required) | string | Header value to send. |
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.
| Name | Type | Description |
|---|---|---|
| headerDict (required) | object | Header names and values to add. |
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.
| Name | Type | Description |
|---|---|---|
| data (required) | object | Request body with the extension under extension. |
| data.extension.title (required) | string | Title of the extension. |
| data.extension.type (required) | string | Kind of extension, for example field or widget. |
| data.extension.src | string | URL of an externally hosted extension. |
| data.extension.srcdoc | string | Source code that Contentstack hosts. |
| data.extension.data_type | string | Data type of a custom field, for example text. |
| data.extension.tags | string[] | Tags for the extension. |
| data.extension.multiple | boolean | Lets a custom field hold several values. |
| data.extension.config | string | Configuration that the extension reads. |
| data.extension.scope | ExtensionScope | Content types where a widget appears. |
| data.extension.enable | boolean | Turns a dashboard widget on. |
| data.extension.default_width | string | Width of a dashboard widget, full or half. |
| param | object | Query parameters, sent as given. |
| param.include_branch | boolean | Adds the _branch key to the response. |
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.
| Name | Type | Description |
|---|---|---|
| param | object | Query parameters, sent as given. |
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>').
| Name | Type | Description |
|---|---|---|
| param | object | Query parameters, sent as given. |
| param.include_branch | boolean | Adds the _branch key to the response. |
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.
| Name | Type | Description |
|---|---|---|
| params | object | Query parameters for the list request. |
| params.query | object | Filter condition, sent as JSON, for example by type. |
| params.scope | string | Content type UID whose widgets to list. |
| params.include_branch | boolean | Adds the _branch key to each item. |
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.
| Name | Type | Description |
|---|---|---|
| key (required) | string | Name of the header to remove. |
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.
| Name | Type | Description |
|---|---|---|
| param | object | Query parameters, sent as given. |
| param.include_branch | boolean | Adds the _branch key to the response. |
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.
| Name | Type | Description |
|---|---|---|
| data (required) | UploadExtensionData | Extension details and the file path. |
| data.upload (required) | string | Path of the HTML file to upload. |
| data.title (required) | string | Title of the extension. |
| data.type (required) | string | Kind of extension, for example field or widget. |
| data.data_type | string | Data type of a custom field, for example text. |
| data.tags | string[] | string | Tags, as an array or a comma-separated string. |
| data.multiple | boolean | Lets a custom field hold several values. |
| data.enable | boolean | Turns a dashboard widget on. |
| params | object | Query parameters, sent as given. |
| params.include_branch | boolean | Adds the _branch key to the response. |
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)
}