In this document, we will discuss the API requests that a custom location can use to communicate with Contentstack.

To include the app-sdk library in your React app or project, you need to open command prompt and run the following command:

npm install @contentstack/app-sdk

Alternatively, you can add it inside script tag:

<scriptsrc="https://unpkg.com/@contentstack/app-sdk/dist/index.js" integrity="sha512-mcJn/xSGuDGTvKiBvPfjLxbLfRpByRNzdbyldfpNie10BdFHgy7hRxACw3mQ3xbx752N85eqgMPIm8lb4Aq8pw==" crossorigin="anonymous"></script>

The above command will install the app-sdk library in your project which contains the necessary toolkit you need to manage installed apps on specific locations.

Below we have listed some of the top-level objects used in the App SDK.

• Location: It's an object that represents all locations from the Contentstack UI.
• Store: It refers to a class that is used by a location to store your data in the local storage.
• Stack: It's a class representing the current stack in the Contentstack UI.
• Window Frame: It refers to a class that represents an iframe window from the Contentstack UI.

  Note: This class is not available for Custom Widgets.

• Entry: It's a class that represents an entry from the Contentstack UI.

  Note: It's not available for the Dashboard Widget extension.

• Modal: It's a class that represents a modal dialog opened from the app within the Contentstack UI.

The App SDK provides several top-level methods that retrieve app-related information.

• getConfig: Retrieves the configuration set for the app. This method allows easy access to the app's configuration data set on the app configuration page.
• getCurrentLocation: Returns the current UI location type of the app.
• getCurrentRegion: : Retrieves the Contentstack Region on which the app is running.
• getAppVersion: Returns the version of the app currently installed.

  Note: The getAppVersion method is not available for JSON RTE Plugins.

Example

// javascriptContentstackAppSDK.init().then(asyncfunction(appSdk){// Retrieve the app configurationconstappConfig=awaitappSdk.getConfig();// Get the current UI location of the appconstcurrentLocation=appSdk.getCurrentLocation();// Get the Contentstack Region of the appconstcurrentRegion=appSdk.getCurrentRegion();// Get the version of the appconstappVersion=awaitappSdk.getAppVersion();});

Locations refers to the position or the placement of the app (sidebar widget, custom field, etc). As of now, the following locations are supported:

• CustomField: It's an object representing the current Custom field reference in the Contentstack UI.
• DashboardWidget: It's an object representing the Dashboard widget reference in the Contentstack UI.
• SidebarWidget: It's an object representing the current Sidebar widget reference in the Contentstack UI.
• AppConfigWidget: It's an object representing the current App configuration for the current App in the Contentstack UI.
• FieldModifierLocation: It's an object representing the Field Modifier reference over the field in the Contentstack UI.
• ContentTypeSidebarWidget: It's an object representing the Content Type Sidebar Widget in the Contentstack UI.

• Promise: The Promise object represents the eventual completion (or failure) of an asynchronous operation and its resulting value.
• localStorage: The read-only localStorage property allows you to access a Storage object for the Document's origin; the stored data is saved across browser sessions.

Kind: global class

ContentstackAppSDK

• .SDK_VERSION : string
• .init() ⇒ Promise

The above defines the version of the Contentstack UI App SDK.

Kind: static property of ContentstackAppSDK

To start using the APP SDK, you first need to include the Contentstack UI App SDK and Contentstack Venus UI Stylesheet in your HTML file and then call ContentstackAppSDK.init on component mount.

Kind: The static method of ContentstackAppSDK

Returns: Promise - A promise object which will be resolved with an instance of the Location class which is instantiated using the data received from the Contentstack UI.

Example(App Config Widget)

// javascriptContentstackAppSDK.init().then(function(appSdk){// Get AppConfigWidget object// this is only initialized on the App configuration page.// on other locations this will return undefined.varappConfigWidget=awaitappSdk.location.AppConfigWidget;// fetch all Installation configuration related to// 1. App Configuration// 2. Server Configuration// 3. Webhooks channels// 4. UI Locations configured in the appvarinstallationData=awaitappConfigWidget.getInstallationData();// Update all Installation configuration related to// 1. App Configuration// 2. Server Configuration// 3. Webhooks channels// 4. UI Locations configured in the appvargetInstallationData=awaitappConfigWidget.setInstallationData(installationData);});

Example(Custom Field)

// javascriptContentstackAppSDK.init().then(function(appSdk){// Get CustomField object// this is only initialized on the Entry create/edit page.// on other locations this will return undefined.varcustomField=awaitappSdk.location.CustomField;// fetch app configurationvarappConfig=awaitappSdk.getConfig();// fetch entry informationvarfieldData=awaitcustomField.entry.getData();});

Example(Sidebar Widget)

// javascriptContentstackAppSDK.init().then(function(location){// Get SidebarWidget object// this is only initialized on the Entry edit page.// on other locations this will return undefined.varsidebarWidget=awaitappSdk.location.SidebarWidget;// fetch app configurationvarappConfig=awaitappSdk.getConfig();// fetch entry informationvarfieldData=awaitsidebarWidget.entry.getData();});

Example(Dashboard Widget)

// javascriptContentstackAppSDK.init().then(function(location){// Get SidebarWidget object// this is only initialized on the Entry edit page.// on other locations this will return undefined.vardashboardWidget=awaitappSdk.location.DashboardWidget;// fetch app configurationvarappConfig=awaitappSdk.getConfig();// fetch stack informationvarstackData=awaitappSdk.stack.getData();});

Example(Field Modifier location)

// javascriptContentstackAppSDK.init().then(function(appSdk){// Get FieldModifierLocation object// this is only initialized on the Entry create/edit page.// on other locations this will return undefined.varfieldModifierLocation=awaitappSdk.location.FieldModifierLocation;// fetch app configurationvarappConfig=awaitappSdk.getConfig();// fetch entry informationvarfieldData=awaitfieldModifierLocation.entry.getData();});

It is an object representing the current Custom field reference in the Contentstack UI.

Kind: The instance property of AppConfigWidget

CustomField

• .fieldConfig : Object
• .field : Field
• .entry : Entry
• .frame : Frame
• .stack : Stack

The above method gives you the instance configuration parameters set from the content type builder page in the field settings. This is only available for the Custom Field location.

Kind: instance property of CustomField

This method gives you the custom field object which allows you to interact with the field. Please note that it is available only for the Custom Field location.

Kind: instance property of CustomField

This method gives you the entry object which allows you to interact with the current entry. Please note that it is not available for the Dashboard Widget location.

Kind: instance property of CustomField

The frame object provides users with methods that allow them to adjust the size of the iframe containing the location. Note that it is not available for the custom widgets location.

Kind: instance property of CustomField

This method returns the stack object which allows users to read and manipulate a range of objects in a stack.

Kind: instance property of CustomField

DashboardWidget

Kind: instance property of DashboardWidget

DashboardWidget

• .frame : Frame
• .stack : Stack

This frame object provides users with methods that allow them to adjust the size of the iframe that contains the extension. Not available in case of custom widgets.

Kind: instance property of Location

This method returns the stack object which allows users to read and manipulate a range of objects in a stack.

Kind: instance property of Location

It is an object representing the current Sidebar widget reference in the Contentstack UI.

Kind: instance property of SidebarWidget

SidebarWidget

• .entry : Entry
• .stack : Stack

This gives you the entry object to interact with the current entry. Please note that it is not available for the Dashboard Widget extension.

Kind: instance property of Extension

This method returns the stack object to read and manipulate a range of objects in a stack.

Kind: instance property of Extension

It is an object representing the current Asset Sidebar Widget reference in the Contentstack UI.

• getData()
• setData(asset: Partial)
• syncAsset()
• updateWidth(width: number)
• replaceAsset(file: File)
• onSave(callback: anyFunction)
• onChange(callback: anyFunction)
• onPublish(callback: anyFunction)
• onUnPublish(callback: anyFunction)
• AssetData

This method returns the object representing the current asset.

This method modifies the properties of the current asset.

If your asset has been modified externally, you can use this method to load the new asset and sync its settings with the current asset.

This method is used to modify the width of the asset sidebar panel. Using this method, you can resize the panel depending on the resolution of your content.

This method is used to replace the current asset with a new file. Unlike setData(), where you can only modify the properties, you can use this method to replace the actual file.

This is a callback function that runs after you save the asset settings.

This is a callback function that runs every time the user modifies the asset data.

This is a callback function that is executed after a user publishes an asset.

This is a callback function that is executed after you unpublish an asset.

It is the property that you can modify using the setData() method.

It's an object representing the current App configuration for the current App in the Contentstack UI.

Kind: instance property of AppConfigWidget

AppConfigWidget

• .getInstallationData : InstallationData
• .setInstallationData : InstallationData
• .setValidity(isValid: boolean, options: { message: string }) : void

This method gives you the complete installation data.

Kind: instance property of AppConfigWidget

This method updates installation data for the app.

Kind: instance property of AppConfigWidget

The appconfig.setValidity method is used to set the validation state of the app in the Contentstack App Config location. By invoking this method with the isValid parameter as false, the user will be prevented from saving the configuration. Additionally, an optional message parameter can be provided to display a custom error message.

• isValid (boolean): Specifies whether the app configuration is considered valid (true) or invalid (false).
• options (object): An optional object containing the following property:
  • message (string): A custom error message to be displayed when the configuration is invalid.

Kind: instance property of AppConfigWidget

// JavaScript// Initialize ContentstackAppSDKContentstackAppSDK.init().then(asyncfunction(appSdk){// Get the AppConfigWidget objectconstappConfigWidget=awaitappSdk.location.AppConfigWidget;// Set validity to false, notifying the user that incorrect inputs have been entered.appConfigWidget.installation.setValidity(false,{message: 'Please enter valid inputs'});});

It is an object representing the field modifier UI location in the Contentstack UI.

Kind: The instance property of FieldModifierLocation

FieldModifierLocation

• .field : Field
• .entry : Entry
• .frame : Frame
• .stack : Stack

This method gives you the current field object which allows you to interact with the field.

Kind: instance property of FieldModifierLocation

• Field
  • .uid : string
  • .data_type : string
  • .schema : Object
  • .setData(data) ⇒ Promise
  • .getData(options) ⇒ Object | string | number

The UID of the current field is defined in the content type of the entry.

Kind: instance property of Field

The data type of the current field is set using this method.

Kind: instance property of Field

The schema of the current field (schema of fields such as ‘Single Line Textbox’, ‘Number’, and so on) is set using this method.

Kind: instance property of Field

Sets the data for the current field.

Kind: instance method of FieldReturns: Promise - A promise object which is resolved when data is set for a field. Note: The data set by this function will only be saved when the user saves the entry.

Gets the data of the current field.

Kind: instance method of FieldReturns: Object | string | number - Returns the field data.

The field.onChange() function is called when another extension programmatically changes the data of the current extension field using the field.setData() function. This function is only available for extension fields that support the following data types: text, number, boolean, or date.

Kind: instance method of Field

This method gives you the entry, object which allows you to interact with the current entry.

Kind: instance property of FieldModifierLocation

• Entry
  • .content_type : Object
  • .locale : string
  • .getData() ⇒ Object
  • .getField(uid, options?) ⇒ Object
  • .onSave(callback)
  • .onChange(callback)
  • .onPublish(callback)
  • .onUnPublish(callback)
  • .getTags()
  • .setTags(tags)

Gets the content type of the current entry.

Kind: instance property of Entry

Gets the locale of the current entry.

Kind: instance property of Entry

Gets data of the current entry.

Kind: instance method of EntryReturns: Object - Returns entry data.

It gets the field object, allowing you to interact with it. This object will support all the methods and properties that work with the extension.field. Note: For fields initialized using the getFields function, the setData() function currently works only for the following fields: single_line, multi_line, RTE, markdown, select, number, boolean, date, link, and extension of data type text, number, boolean, and date.

Kind: instance method of EntryReturns: Object - Field object

Example

varfield=entry.getField("field_uid");varfieldSchema=field.schema;varfieldUid=field.uid;varfieldData=field.getData();

This onSave() function executes the callback function every time an entry is saved.

Kind: instance method of Entry

The onChange() function executes the callback function every time an entry has been updated.

Kind: instance method of Entry

The onPublish() function executes the callback function every time an entry has been published with the respective payload.

Kind: instance method of Entry

The onPublish() function executes the callback function every time an entry has been unpublished with the respective payload.

Kind: instance method of Entry

Gets the tags of the current entry. By default, this method gets the saved tags, but you can get the draft tags by setting the options.useUnsavedSchema parameter.

Kind: instance method of EntryReturns: Array - List of tags

Sets the tags in the entry.

Kind: instance method of EntryReturns: Array - List of tags

This method returns the stack object which allows users to read and manipulate a range of objects in a stack.

Kind: instance property of FieldModifierLocation

The frame object provides users with methods that allow them to adjust the size of the iframe containing the UI location.

Kind: instance property of FieldModifierLocation

• .updateDimension({height?, width?}) ⇒ Promise
• .enableAutoResizing() ⇒ frame
• .disableAutoResizing() ⇒ frame
• .preventFrameClose(state: boolean) ⇒ void

This method updates the extension dimensions on the Contentstack UI. If the dimensions are not provided, it will update the dimensions of the extension to the dimensions of the content.

Kind: instance method of frame

Returns: Promise - A promise object which will be resolved when Contentstack UI sends an acknowledgement stating that the height has been updated.

This method enables the auto resizing of the extension height.

Kind: instance method of frame

Returns: frame

This method disables the auto resizing of the extension height.

Kind: instance method of frame

Returns: frame.

The frame.preventFrameClose method allows you to manage the default closing behavior of the app when the user clicks outside its frame. By default, the app is closed in such scenarios. This method enables you to control and customize the closing behavior based on your requirements.

Kind: instance method of frame

// JavaScriptContentstackAppSDK.init().then(asyncfunction(appSdk){// Get the FieldModifierLocation objectconstfieldModifierLocation=awaitappSdk.location.FieldModifierLocation;// To disable the automatic closure of the app frame when the user clicks outsidefieldModifierLocation.frame.preventFrameClose(true);});

It is an object representing the Content Type Sidebar Widget in the Contentstack UI.

Kind: The instance property of ContentTypeSidebarWidget

This method retrieves the current content type data of the sidebar widget.

Kind: instance method of ContentTypeSidebarWidget

Returns: ContentType - The current content type data.

Executes the specified callback function each time the content type is saved. The callback function receives the updated content type data as an argument.

Kind: instance method of ContentTypeSidebarWidget

Throws: Will throw an error if the provided callback is not a function.

Example

constsidebarWidget=newContentTypeSidebarWidget(initData,connection,emitter);// Register onSave callback to execute on each save event.sidebarWidget.onSave((updatedContentType)=>{console.log("Content type saved:",updatedContentType);});

It is a class representing an iframe window from the Contentstack UI. Please note that it is not available for Custom Widgets.

Kind: global class

frame

• .enableResizing() ⇒ Promise
• .onDashboardResize(callback) ⇒ boolean
• .updateHeight(height) ⇒ Promise
• .enableAutoResizing() ⇒ frame
• .disableAutoResizing() ⇒ frame

This method activates the resize button that gives you the provision to resize your Dashboard Widget.

Kind: instance method of frame

Returns: Promise - A promise object which will resolve when a resize button is visible on the Dashboard Widget.

This function executes the callback function whenever a Dashboard Widget extension is maximized or minimized. Please note that it is only applicable for Dashboard Widget extensions.

Kind: instance method of frame

Returns: boolean - Will return true

This method updates the extension height on the Contentstack UI. If the ‘height’ argument is not passed, it will calculate the scroll height and set the height of the location window accordingly.

Kind: instance method of frame

Returns: Promise - A promise object which will be resolved when Contentstack UI sends an acknowledgement stating that the height has been updated.

This method enables the auto resizing of the extension height.

Kind: instance method of frame

Returns: frame

This method disables the auto resizing of the extension height.

Kind: instance method of frame

Returns: frame.

It is a class representing the current stack in Contentstack UI.

Kind: global class

Stack

• .ContentType
  • new this.ContentType(uid)
  • .Entry
    • new Entry()
    • instance
      • .only([key], values) ⇒ Entry
      • .except([key], values) ⇒ Entry
      • .addParam(key, value) ⇒ Entry
      • .getReferences() ⇒ Promise
      • .delete() ⇒ Promise
      • .fetch() ⇒ Promise
      • .includeReference() ⇒ Entry
      • .language(languageCode) ⇒ Entry
      • .environment(environment_uid) ⇒ Entry
      • .addQuery(key, value) ⇒ Entry
      • .includeSchema() ⇒ Entry
      • .includeContentType() ⇒ Entry
      • .includeOwner() ⇒ Entry
      • .getLanguages() ⇒ Promise
      • .unlocalize(locale) ⇒ Promise
      • .publish(payload, api_version="") ⇒ Promise
      • .unpublish(payload) ⇒ Promise
      • .setWorkflowStage(payload) ⇒ Promise
      • .update(payload, [locale]) ⇒ Promise
    • static
      • .Query() ⇒ Query
      • .create(payload) ⇒ Promise
• .Asset
  • new this.Asset(uid)
  • instance
    • .only([key], values) ⇒ Asset
    • .except([key], values) ⇒ Asset
    • .environment(environment_uid) ⇒ Asset
    • .addParam(key, value) ⇒ Asset
    • .addQuery(key, value) ⇒ Asset
    • .getReferences() ⇒ Promise
    • .delete() ⇒ Promise
    • .publish(payload, api_version="") ⇒ Promise
    • .unpublish(payload) ⇒ Promise
  • static
    • .Query() ⇒ Query
    • .getRteAssets() ⇒ Promise
    • .getAssetsOfSpecificTypes(assetType) ⇒ Promise
• .getData() ⇒ Object
• .getContentType(uid, params) ⇒ Object
• .getContentTypes(query, params) ⇒ Object
• .getEnvironment(name, params) ⇒ Object
• .getEnvironments(query, params) ⇒ Object
• .getLocale(code, params) ⇒ Object
• .getLocales(query, params) ⇒ Object
• .getReleases(query, params) ⇒ Object
• .getPublishes(query, params) ⇒ Object
• .search(queries, apiKey) => Promise
• .getAllStacks(options): Promise
• .getCurrentBranch() ⇒ Object | null
• .getAllBranch() ⇒ Object[]
• .getGlobalField(uid, params) ⇒ Object
• .getGlobalFields(query, params) ⇒ Object
• .getVariantById(variant_uid) ⇒ Object

Kind: instance class of Stack

See: ContentType

.ContentType

• new this.ContentType(uid)
• .Entry
  • new Entry()
  • instance
    • .only([key], values) ⇒ Entry
    • .except([key], values) ⇒ Entry
    • .addParam(key, value) ⇒ Entry
    • .getReferences() ⇒ Promise
    • .delete() ⇒ Promise
    • .fetch() ⇒ Promise
    • .includeReference() ⇒ Entry
    • .language(languageCode) ⇒ Entry
    • .environment(environment_uid) ⇒ Entry
    • .addQuery(key, value) ⇒ Entry
    • .includeSchema() ⇒ Entry
    • .includeContentType() ⇒ Entry
    • .includeOwner() ⇒ Entry
    • .getLanguages() ⇒ Promise
    • .unlocalize(locale) ⇒ Promise
    • .publish(payload, api_version="") ⇒ Promise
    • .unpublish(payload) ⇒ Promise
    • .setWorkflowStage(payload) ⇒ Promise
    • .update(payload, [locale]) ⇒ Promise
  • static
    • .Query() ⇒ Query
    • .create(payload) ⇒ Promise

A content type defines the structure or the schema of a page or a section of your web or mobile property.

Example

extension.stack.ContentType('content_type_uid')

Kind: instance class of ContentType

See: Entries

• .Entry
  • new Entry()
  • instance
    • .only([key], values) ⇒ Entry
    • .except([key], values) ⇒ Entry
    • .addParam(key, value) ⇒ Entry
    • .getReferences() ⇒ Promise
    • .delete() ⇒ Promise
    • .fetch() ⇒ Promise
    • .includeReference() ⇒ Entry
    • .language(languageCode) ⇒ Entry
    • .environment(environment_uid) ⇒ Entry
    • .addQuery(key, value) ⇒ Entry
    • .includeSchema() ⇒ Entry
    • .includeContentType() ⇒ Entry
    • .includeOwner() ⇒ Entry
    • .getLanguages() ⇒ Promise
    • .unlocalize(locale) ⇒ Promise
    • .publish(payload, api_version="") ⇒ Promise
    • .unpublish(payload) ⇒ Promise
    • .setWorkflowStage(payload) ⇒ Promise
    • .update(payload, [locale]) ⇒ Promise
  • static
    • .Query() ⇒ Query
    • .create(payload) ⇒ Promise

An entry is the actual piece of content created using one of the defined content types.

This method is used to show the selected fields of an entry in the result set.

Kind: instance method of Entry

Example( Only with field UID )

extension.stack.ContentType("content_type_uid").Entry("bltsomething123").only("title").fetch();

Example( Only with field UID )

extension.stack.ContentType("content_type_uid").Entry("bltsomething123").only("BASE","title").fetch();

Example( Only with field UIDs(array) )

extension.stack.ContentType("content_type_uid").Entry("bltsomething123").only(["title","description"]).fetch();

This method is used to hide the selected fields of an entry in the result set.

Kind: instance method of Entry

Example( Except with field uid )

extension.stack.ContentType("content_type_uid").Entry("bltsomething123").except("title").fetch();

Example( Except with field uid )

extension.stack.ContentType("content_type_uid").Entry("bltsomething123").except("BASE","title").fetch();

Example( Except with field uids(array) )

extension.stack.ContentType("content_type_uid").Entry("bltsomething123").except(["title","description"]).fetch();

This method includes a query parameter in a query.

Kind: instance method of Entry

Returns: Entry - Returns

Example

extension.stack.ContentType("content_type_uid").Entry("uid").addParam("include_count","true").fetch().then().catch();

This method fetches all the entries in which the current entry is referenced.

Kind: instance method of Entry

Returns: Promise - Required data if resolved successfully

Additional Resource:Learn more about Entry references

Example

extension.stack.ContentType("content_type_uid").Entry("uid").getReferences().then().catch();

This method deletes an existing entry.

Kind: instance method of Entry

Returns: Promise - Required data if resolved successfully

Additional Resource: Learn more about [Deleting an Entry](https://www.contentstack.com/docs/apis/content-management-api/#delete-an-entry| Delete Entry).

Example

extension.stack.ContentType("content_type_uid").Entry("uid").delete().then().catch();

This method fetches information of a specific entry.

Kind: instance method of Entry

Returns: Promise - Required data if resolved successfully.

Additional Resource: Learn more about Fetching a Single Entry.

Example

extension.stack.ContentType("content_type_uid").Entry("uid").fetch().then().catch();

This method is used to include referenced entries from other content types.

Kind: instance method of Entry

Example( .includeReference with reference_field_uids as array )

stack.ContentType("contenttype_uid").Entry("bltsomething123").includeReference(["category","author"]).fetch();

Example( .includeReference with reference_field_uids )

stack.ContentType("contenttype_uid").Entry("bltsomething123").includeReference("category","author").fetch();

This method is used to set the language code of which you want to retrieve the data.

Kind: instance method of Entry

Example

extension.stack.ContentType("contenttype_uid").Entry("bltsomething123").language("en-us").fetch();

This method is used to set the environment name of which you want to retrieve the data.

Kind: instance method of Entry

Example

extension.stack.ContentType("contenttype_uid").Entry("bltsomething123").environment("development").fetch();

This method is used to add a query to an entry object.

Kind: instance method of Entry

Example

extension.stack.ContentType("contenttype_uid").Entry("bltsomething123").addQuery("include_schema",true).fetch();

This method is used to include the schema of the current content type in the result set along with the entry/entries.

Kind: instance method of Entry

Example

extension.stack.ContentType("contenttype_uid").Entry("bltsomething123").includeSchema().fetch();

This method is used to include the current content type in the result set along with the entry(ies).

Kind: instance method of Entry

Example

extension.stack.ContentType("contenttype_uid").Entry("bltsomething123").includeContentType().fetch();

This method is used to include the owner of the entry(ies) in the result set.

Kind: instance method of Entry

Example

extension.stack.ContentType("contenttype_uid").Entry("bltsomething123").includeOwner().fetch();

This method returns the details of all languages in which the entry is localized.

Kind: instance method of Entry

Example

extension.stack.ContentType("contenttype_uid").Entry("bltsomething123").getLanguages();

This method is used to unlocalize an entry.

Kind: instance method of Entry

Example

extension.stack.ContentType('contenttype_uid').Entry('bltsomething123').unlocalize('fr-fr').then(...).catch(...);

This method lets you publish an entry either immediately or schedule it to be published automatically at a later date/time.

Kind: instance method of Entry

Example

extension.stack.ContentType('contenttype_uid').Entry('bltsomething123').publish({"entry": {"environments": ["development"],"locales": ["en-us"]},"locale": "en-us","version": 1,"scheduled_at": "2019-02-14T18:30:00.000Z"}).then(...).catch(...);

This method lets you unpublish an entry either immediately or schedule it to be unpublished automatically at a later date/time.

Kind: instance method of Entry

Example

extension.stack.ContentType('contenttype_uid').Entry('bltsomething123').unpublish({"entry": {"environments": ["development"],"locales": ["en-us"]},"locale": "en-us","version": 1,"scheduled_at": "2019-02-14T18:30:00.000Z"}).then(...).catch(...);

This method allows you to either set a particular workflow stage or update the workflow stage details of an entry.

Kind: instance method of Entry

Example

extension.stack.ContentType('contenttype_uid').Entry('bltsomething123').setWorkflowStage({"workflow": {"workflow_stage": {"comment": "Test Comment","due_date": "Thu Dec 01 2018","notify": false,"uid": "blt9f52a2cd5e0014fb","assigned_to": [{"uid": "blt296a22e28cc0c63c","name": "John Doe","email": "john.doe@contentstack.com"}],"assigned_by_roles": [{"uid": "blt5b74c24c7ae25d94","name": "Content Manager"}]}}}).then(...).catch(...);

This call allows you to update the entry content.

Kind: instance method of Entry

See: Update Entry

Example

extension.stack.ContentType('contenttype_uid').Entry('bltsomething123').update({"entry": {"title": "example","url": "/example"}}).then(...).catch(...);

This static method instantiates the query module for entries. To see the list of methods that can be used for querying entries, refer to the Query module.

Kind: static method of Entry

Example

letentryQuery=extension.stack.ContentType('content_type_uid').Entry.Query();entryQuery.where("field_uid": "10").limit(10).skip(10).find().then(...).catch(...);

This method creates a new entry.

Kind: static method of Entry

Returns: Promise - Required data if resolved successfully

Additional Resource: Learn more about [Creating an Entry](https://www.contentstack.com/docs/apis/content-management-api/#create-a-an-entry| Create Entry).

Example

extension.stack.ContentType('content_type_uid').Entry.create({"entry": {"title": "example","url": "/example"}}).then(...).catch(...);

Kind: instance class of Stack

See: Asset

.Asset

• new this.Asset(uid)
• instance
  • .only([key], values) ⇒ Asset
  • .except([key], values) ⇒ Asset
  • .environment(environment_uid) ⇒ Asset
  • .addParam(key, value) ⇒ Asset
  • .addQuery(key, value) ⇒ Asset
  • .getReferences() ⇒ Promise
  • .delete() ⇒ Promise
  • .publish(payload, api_version="") ⇒ Promise
  • .unpublish(payload) ⇒ Promise
• static
  • .Query() ⇒ Query
  • .getRteAssets() ⇒ Promise
  • .getAssetsOfSpecificTypes(assetType) ⇒ Promise

An initializer is responsible for creating an Asset object.

Example

extension.stack.Asset("asset_uid");

This method is used to show the selected fields of the assets in the result set.

Kind: instance method of Asset

Example( Only with the field UID )

extension.stack.Asset("bltsomething123").only("title").fetch();

Example( Only with the field UID )

extension.stack.Asset("bltsomething123").only("BASE","title").fetch();

Example( Only with the field UIDs(array) )

extension.stack.Asset("bltsomething123").only(["title","description"]).fetch();

This method is used to hide the selected fields of the assets in the result set.

Kind: instance method of Asset

Example( .Except with the field UID )

extension.stack.Asset("bltsomething123").except("title").fetch();

Example( .Except with the field UID )

extension.stack.Asset("bltsomething123").except("BASE","title").fetch();

Example( .Except with the field UIDs(array) )

extension.stack.Asset("bltsomething123").except(["title","description"]).fetch();

This method is used to set the environment name of which you want to retrieve the data.

Kind: instance method of Asset

Example

extension.stack.Asset("bltsomething123").environment("development").fetch();

This method includes a query parameter in your query.

Kind: instance method of Asset

Example

extension.stack.Asset("bltsomething123").environment("development").fetch();

This method includes a query parameter in your query.

Kind: instance method of Asset

Example

extension.stack.Asset("uid").addQuery("key","value").fetch().then().catch();

This method fetches the details of entries and the assets in which the specified asset is referenced.

Kind: instance method of Asset

Additional Resource: Learn more about [Asset References](https://www.contentstack.com/docs/apis/content-management-api/#get-all-references-of-asset| Asset References).

Example

extension.stack.Asset("uid").getReferences().then().catch();

This method deletes an existing asset.

Kind: instance method of Asset

Additional Resource: Learn more about [Deleting an Asset](https://www.contentstack.com/docs/apis/content-management-api/#delete-an-asset| Delete Asset).

Example

extension.stack.Asset("uid").delete().then().catch();

This method allows you to publish the asset either immediately or schedule the publish for a later date/time.

Kind: instance method of Asset

Example

extension.stack.Asset("bltsomething123").publish({asset: {locales: ["en-us"],environments: ["development"],},version: 1,scheduled_at: "2019-02-08T18:30:00.000Z",});

This method instantly unpublishes the asset and also gives you the provision to automatically unpublish the asset at a later date/time.

Kind: instance method of Asset

Example

extension.stack.Asset("bltsomething123").unpublish({asset: {locales: ["en-us"],environments: ["development"],},version: 1,scheduled_at: "2019-02-08T18:30:00.000Z",});

This static method instantiates the query module for assets. To see the list of methods that can be used for querying assets, refer to the Query module.

Kind: static method of Asset

Example

letassetQuery=extension.stack.Asset.Query();assetQuery.where("title": "main.js").limit(10).skip(10).find().then(...).catch(...);

This static method retrieves comprehensive information on all assets uploaded through the Rich Text Editor field.

Kind: static method of Asset

This static method retrieves assets that are either image or video files, based on the request query.

Kind: static method of Asset

This method returns the data of the current stack.

Kind: instance method of Stack

Returns: Object - Returns stack data.

This API allows you to retrieve data of a content type of a stack using the Content Type API requests. This method returns a Promise object.

Kind: instance method of Stack

Returns: Object - A promise object which will be resolved with content type details.

This API allows you to retrieve data of a content type of a stack using the Content Types API requests. This method returns a Promise object.

Kind: instance method of Stack

Returns: Object - A promise object which will be resolved with details of the content type.

This API allows you to retrieve environment details of a stack using the Environment API requests. This method returns a Promise object.

Kind: instance method of Stack

Returns: Object - A promise object which will be resolved with environment details.

This API allows you to retrieve details of environments of a stack using the Environments API requests. This method returns a Promise object.

Kind: instance method of Stack

Returns: Object - A Promise object which will be resolved with details of the environments.

This API allows you to retrieve a locale of a stack using the Language API requests. Method returns a Promise object.

Kind: instance method of Stack

Returns: Object - A promise object which will be resolved with locale details.

This API allows you to retrieve the locales of a stack using the Languages API requests. Method returns a Promise object.

Kind: instance method of Stack

Returns: Object - A Promise object which will be resolved with details of the locales.

This API allows you to retrieve details of releases of a stack using the Releases API requests. Method returns a Promise object.

Kind: instance method of Stack

Returns: Object - A Promise object which will be resolved with details of the releases.

This API allows you to retrieve details of publish queue of a stack using the Publish Queue API requests. Method returns a Promise object.

Kind: instance method of Stack

Returns: Object - A Promise object which will be resolved with details of the publish queue.

This API allows you to search for content in a stack. It uses the API used by the Contentstack Search Bar. By default, the current stack is searched. Method returns a Promise object.

Kind: instance method of Stack

Returns: Object - A Promise object which will be resolved with details of the stacks in the organization.

This is the type of the queries parameter of the search method.

StackSearchQuery{ type: "entries"|"assets"; skip?: number; limit?: number; include_publish_details?: boolean; include_unpublished?: boolean; include_workflow?: boolean; include_fields?: boolean; include_rules?: boolean; include_title_field_uid?: boolean; query?: AnyObject; search?: string; save_recent_search?: boolean; desc?: string;}

This API allows you to retrieve details of all the stacks of an organization using the Get all Stacks API requests. Method returns a Promise object.

Note: In order to fetch the stacks, you must have access to the stacks.

Kind: instance method of Stack

Returns: Object - A Promise object which will be resolved with details of the stacks in the organization.

This API allows you to retrieve details of current branch of the stack, if available. If the Branches plan is not available, it will return null.

Note: Branch feature is plan based.

Kind: instance method of Stack

Returns: Object - An object which will be resolved with details of the current branch.

This API allows you to retrieve details of all the available branches in the stack. If the Branches plan is not available, it will return an empty array.

Note: Branch feature is plan based.

Kind: instance method of Stack

Returns: Array - An Array of object which will be resolved with details of all the branches.

This is the interface of the branch returned by the stack.getCurrentBranch() and stack.getAllBranches() methods.

BranchDetail{ api_key: string; uid: string; source: string; alias: { uid: string;}[];}

This API allows you to retrieve data of a single entry variant of a stack using the Variants API requests. This method returns a Promise object.

Kind: instance method of Stack

Returns: Object - A promise object which will be resolved with variant entry details.

This API allows you to retrieve data of a single global field of a stack using the Global Field API requests. This method returns a Promise object.

Kind: instance method of Stack

Returns: Object - A promise object which will be resolved with global field details.

This API allows you to retrieve data of all global fields of a stack using the Global Fields API requests. This method returns a Promise object.

Kind: instance method of Stack

Returns: Object - A promise object which will be resolved with global field details.

Kind: global class

• Store
  • .get(key) ⇒ Promise
  • .getAll() ⇒ Promise
  • .set(key, value) ⇒ Promise
  • .remove(key) ⇒ Promise
  • .clear() ⇒ Promise

It fetches the value of a key.

Kind: instance method of Store

Example

extension.store.get("key").then((value)=>console.log(value));// will log value for the given key

It fetches an object with all the stored key-value pairs.

Kind: instance method of Store

Example

extension.store.getAll().then((obj)=>obj);

It sets the value of a key

Kind: instance method of Store

Example

extension.store.set("key","value").then((success)=>console.log(success));// will log 'true' when value is set

It removes the value of a key.

Kind: instance method of Store

Example

extension.store.remove("key").then((success)=>console.log(success));// will log 'true' when value is removed

It clears all the stored data of an extension.

Kind: instance method of Store

Example

Example

extension.store.clear().then((success)=>console.log(success));// will log 'true' when values are cleared

Creates an instance of the query

Kind: global class
Version: 2.2.0

• Query
  • .lessThan ⇒ Query
  • .lessThanOrEqualTo ⇒ Query
  • .only([key], values) ⇒ Query
  • .except([key], values) ⇒ Query
  • .addQuery(key, value) ⇒ Query
  • .greaterThan(key, value) ⇒ Query
  • .greaterThanOrEqualTo(key, value) ⇒ Query
  • .notEqualTo(key, value) ⇒ Query
  • .containedIn(key, value) ⇒ Query
  • .notContainedIn(key, value) ⇒ Query
  • .exists(key) ⇒ Query
  • .notExists(key) ⇒ Query
  • .ascending(key) ⇒ Query
  • .descending(key) ⇒ Query
  • .skip(skip) ⇒ Query
  • .limit(limit) ⇒ Query
  • .or(Array) ⇒ Query
  • .and(Array) ⇒ Query
  • .addParam(key, value) ⇒ Query
  • .includeReference() ⇒ Query
  • .includeSchema() ⇒ Query
  • .language(languageCode) ⇒ Query
  • .includeContentType() ⇒ Query
  • .includeOwner() ⇒ Query
  • .environment(environment_uid) ⇒ Query
  • .equalTo(key, value) ⇒ Query
  • .count() ⇒ Query
  • .query(query) ⇒ Query
  • .tags(values) ⇒ Query
  • .includeCount() ⇒ Query
  • .getQuery() ⇒ Query
  • .regex(key, value, [options]) ⇒ Query
  • .search(value) ⇒ Query
  • .find()
  • .findOne()

This method provides only the entries with values less than the specified value for a field.

Kind: instance property of Query

Example

extension.stack.ContentType("blog").lessThan("created_at","2015-06-22");

This method provides the entries with values less than or equal to the specified value for a field.

Kind: instance property of Query

Example

extension.stack.ContentType("blog").lessThanOrEqualTo("created_at","2015-03-12");

This method is used to show the selected fields of an entry in the result set.

Kind: instance method of Query

Example( Only with field UID )

extension.stack.ContentType("content_type_uid").Entry.Query().only("title").find();

Example( Only with field UID )

extension.stack.ContentType("content_type_uid").Entry.Query().only("BASE","title").find();

Example( Only with field UIDs(array) )

extension.stack.ContentType("content_type_uid").Entry.Query().only(["title","description"]).find();

This method is used to hide the selected fields of an entry in the result set.

Kind: instance method of Query

Example( Except with field uid )

extension.stack.ContentType("content_type_uid").Entry.Query().except("title").find();

Example( Except with field uid )

extension.stack.ContentType("content_type_uid").Entry.Query().except("BASE","title").find();

Example( Except with field uids(array) )

extension.stack.ContentType("content_type_uid").Entry.Query().except(["title","description"]).find();

This method includes a query parameter in a query.

Kind: instance method of Query

Example

extension.stack.ContentType("content_type_uid").Entry.Query().addQuery("key","value").find().then().catch();

This method provides the entries with values greater than the specified value for a field.

Kind: instance method of Query

Example

extension.stack.ContentType("blog").greaterThan("created_at","2015-03-12");

This method provides the entries with values greater than or equal to the specified value for a field.

Kind: instance method of Query

Example

extension.stack.ContentType("blog").greaterThanOrEqualTo("created_at","2015-06-22");

This method provides the entries with values not equal to the specified value for a field.

Kind: instance method of Query

Example

extension.stack.ContentType("blog").notEqualTo("title","Demo");

This method provides the entries with values matching the specified values for a field.

Kind: instance method of Query

Example

extension.stack.ContentType("blog").containedIn("title",["Demo","Welcome"]);

This method provides the entries that do not contain values matching the specified values for a field.

Kind: instance method of Query

Example

extension.stack.ContentType("blog").notContainedIn("title",["Demo","Welcome"]);

This method provides the entries that contain the field matching the specified field UID.

Kind: instance method of Query

Example

extension.stack.ContentType("blog").exists("featured");

This method provides the entries that do not contain the field matching the specified field UID.

Kind: instance method of Query

Example

extension.stack.ContentType("blog").notExists("featured");

This parameter sorts the entries in the ascending order on the basis of the value of the specified field.

Kind: instance method of Query

Example

extension.stack.ContentType("blog").ascending("created_at");

This method sorts the entries in the descending order on the basis of the specified field.

Kind: instance method of Query

Example

extension.stack.ContentType("blog").descending("created_at");

This method skips the specified number of entries.

Kind: instance method of Query

Example

extension.stack.ContentType("blog").skip(5);

This method limits the response by providing only the specified number of entries.

Kind: instance method of Query

Example

extension.stack.ContentType("blog").limit(10);

This method performs the OR operation on the specified query objects and provides only the matching entries.

Kind: instance method of Query

Example( OR with query instances)

letQuery1=extension.stack.ContentType("blog").Entry.Query().where("title","Demo");letQuery2=extension.stack.ContentType("blog").Entry.Query().lessThan("comments",10);letblogQuery=extension.stack.ContentType("blog").or(Query1,Query2);

Example( OR with query instances)

letQuery1=extension.stack.ContentType("blog").Entry.Query().where("title","Demo").getQuery();letQuery2=extension.stack.ContentType("blog").Entry.Query().lessThan("comments",10).getQuery();letblogQuery=extension.stack.ContentType("blog").or(Query1,Query2);

This method performs the AND operation on the specified query objects and provides only the matching entries.

Kind: instance method of Query

Example( AND with raw queries)

letQuery1=extension.stack.ContentType("blog").Entry.Query().where("title","Demo");letQuery2=extension.stack.ContentType("blog").Entry.Query().lessThan("comments",10);letblogQuery=extension.stack.ContentType("blog").and(Query1,Query2);

Example( .and with raw queries)

letQuery1=extension.stack.ContentType("blog").Entry.Query().where("title","Demo").getQuery();letQuery2=extension.stack.ContentType("blog").Entry.Query().lessThan("comments",10).getQuery();letblogQuery=extension.stack.ContentType("blog").and(Query1,Query2);

This method includes a query parameter in a query.

Kind: instance method of Query

Example

extension.stack.ContentType("content_type_uid").Entry.Query().addParam("key","value").find().then().catch();

This method is used to include the referenced entries from other content types.

Note: This method is only valid for querying Entry.

Kind: instance method of Query

Example( .includeReference with reference_field_uids as array )

stack.ContentType("contenttype_uid").Entry.Query().includeReference(["category","author"]).find();

Example( .includeReference with reference_field_uids )

stack.ContentType("contenttype_uid").Entry.Query().includeReference("category","author").find();

This method is used to include the schema of the current content type in the result set along with the entry/entries.

Note: This method is only valid for querying Entry.

Kind: instance method of Query

Example

extension.stack.ContentType("contenttype_uid").Entry.Query().includeSchema().find();

This method is used to set the language code of which you want to retrieve the data.

Note: This method is only valid for querying Entry.

Kind: instance method of Query

Example

extension.stack.ContentType("contenttype_uid").Entry.Query().language("en-us").find();

This method is used to include the current content type in the result set along with the entry(ies).

Note: This method is only valid for querying Entry.

Kind: instance method of Query

Example

extension.stack.ContentType("contenttype_uid").Entry.Query().includeContentType().find();

This method is used to include the owner of the entry(ies) in the result set.

Note: This method is only valid for querying Entry.

Kind: instance method of Query

Example

extension.stack.ContentType("contenttype_uid").Entry.Query().includeOwner().find();

This method is used to set the environment name of which you want to retrieve the data.

Kind: instance method of Query

Example

extension.stack.ContentType("contenttype_uid").Entry.Query().environment("development").find();

This method provides only the entries containing field values that match the specified condition.

Kind: instance method of Query

Example

extension.stack.ContentType("blog").where("title","Demo");

This method provides only the number of entries that match the specified filters.

Kind: instance method of Query

Example

extension.stack.ContentType("blog").count();

This method is used to set raw queries on the Query instance.

Kind: instance method of Query

The 'tags' parameter allows you to specify an array of tags to search for objects.

Kind: instance method of Query

Example

extension.stack.ContentType("blog").tags(["technology","business"]);

This method also includes the total number of entries returned in the response.

Kind: instance method of Query

Example

extension.stack.ContentType("blog").includeCount();

This method provides raw{json} queries based on the filters applied on the Query object.

Kind: instance method of Query

Summary: returns Returns the raw query which can be used for further calls (.and/.or).

Example

extension.stack.ContentType("blog").where("title","Demo").getQuery();

This method provides only the entries that match the regular expression for the specified field.

Kind: instance method of Query

Example( .regex without options)

letblogQuery=extension.stack.ContentType('blog').regex('title','^Demo')|

Example( .regex with options)

letblogQuery=extension.stack.ContentType('blog').regex('title','^Demo','i')|

This method is used to search data in entries.

Kind: instance method of Query

Example

extension.stack.ContentType("blog").search("Welcome to demo");

This method provides all the entries which satisfy the specified query.

Kind: instance method of Query

Example

letblogQuery=extension.stack.ContentType('blog').find()|

This method provides a single entry from the resultant set.

Kind: instance method of Query

Example:

letblogQuery=extension.stack.ContentType('blog').findOne()|

The Promise object represents the eventual completion (or failure) of an asynchronous operation and its resulting value.

Kind: global external

See: Promise

localStorage is the read-only property that allows you to access a Storage object for the Document’s origin. The data that gets stored is saved across browser sessions.

Kind: global external

See: localStorage

In this document, we will discuss the API requests that a JSON RTE Plugin can use to communicate with Contentstack.

Prerequisites

• Basic understanding of JSON Rich Text Editor
• JSON structure and terminology associated with it

{ "type": "doc", "children": [ { "type": "p", "children": [ { "text": "Paragraph" } ] }, { "type": "h1", "children": [ { "text": "Heading One" } ] } ] }

In the JSON Rich Text Editor, the JSON structure is represented as a Node which consists of two types:

1. Block Node
2. Leaf Node

The editor content that is inside a Node of type doc acts as a root for the content. Where a Block node is a JSON structure with a “children” key in it. Whereas a Leaf node will just have “text” which may include formatting properties (mark) such as “bold”, “italic”, etc.

Mark: You'll see a mark used in below example which is nothing but a leaf property on how to render content.

For example:

{ "text": "I am Bold", "bold": true }

Here, bold is the mark or the formatting to be applied to the "I am Bold" text.

A Block node can be rendered in three different ways as follow:

1. Block
2. Inline
3. Void

Path arrays are a list of indexes that describe a node's exact position.

In the JSON Rich Text Editor, a Path has the following structure:

Number[]

For example, the path for doc is [0], paragraph is [0,0] from the above given example.

Point objects refer to a specific location of text in the leaf node. Its path refers to the location of the node in the tree, and its offset refers to distance into the node's string of text.

In the JSON Rich Text Editor, a Point has the following structure:

{path: Path,offset: Number}

A Range is a set of start (anchor) and end (focus) points that specify a range in a JSON document.

png

The structure of a Range is as follows:

{anchor: Point,focus: Point}

Location is one of the ways to specify the location in a JSON document. It could be a Path, Point, or Range.

For JSON RTE Plugins, you will need to install @contentstack/app-sdk in your React project. You will also need to clone the boilerplate GitHub repository that contains the template needed to create a JSON RTE plugin.

This method allows you to create a JSON RTE plugin instance.

Kind: Instance property of the JSON RTE plugin

Returns: Object - Plugin Object

IConfig: This user-defined object will have all the essential metadata for the plugin.

The following table contains the possible properties of IConfig:

rte: An instance which has all the essential functions required to interact with the JSON RTE.

Following are a list of helpful properties and methods of the JSON RTE instance.

rte.ref: Returns the HTML reference of the JSON RTE.

rte.fieldConfig: Contains metadata about the JSON RTE field which can be specified in the content type builder page.

Provides configuration which is defined while creating the plugin or while selecting a plugin in the content type builder page.

For example, if your plugin requires API Key or any other config parameters, then you can specify these configurations while creating a new plugin or you can specify field specific configurations from the content type builder page while selecting the plugin. These configurations can be accessed through the getConfig() method.

These methods are part of the RTE instance and can be accessed as rte.methodName().