CMS Commands in JavaScript

you are here (click to zoom) - discover the stack

Whenever you press a button in the edit-ui, a edit-command is handled by the javascript layer. These commands are things like:

edit an item on the screen
open the layout-picker dialog for a content-block

Each command needs 3 things

a short CommandName like new
parameters entityId which differ for each command
a context - usually the current module

It always returns a promise.

Discover More in the Razor Tutorials

We have an rich series of Razor tutorials. You should really check them out 👍.

Run Commands and Parameters

Two commands in the 2sxc APIs allow running CMS commands

$2sxc.cms.run(params: RunParamsWithContext)
This is the run on the Global Cms object
sxc.cms.run(params: RunParams)
This is the run on the Instance Cms object

Both of these commands will run a CMS command with parameters.

Important

There are some possibilities for confusion which you should be aware of.

The $2sxc.cms.run(...) has a few old overloads with other parameters. We plan to discontinue these, as it had to do some magic to figure out what is what. So even if you find such code, please use the method described here.

Requirements and Prerequisites

For this to work, the CMS JavaScripts must be loaded. This is done automatically or manually.

If your user is an admin/editor, this happens automatically.
If your user is not defined as an editor, but should still have these commands (possibly because the Content-Type allows editing for this user), you'll need to activate it manually.

To activate these features manually just use the IPageService and activate 2sxc.JsCms.

How to use (v14+)

Simple example:

@* enable editing for all users *@
@Kit.Page.Activate("2sxc.JsCms")

<script>
  // Run the command and handle the returned promise
  // This uses the Instance object retrieved using $2sxc(tag)
  function addProject(tag) {
    $2sxc(tag).cms.run({ action: "new", params: { contentType: "Project"} })
      .then(function () {
        alert("Thanks - we'll review your entry and publish it.")
      });
  }

  // This is the alternate way to write the code, using the Global object
  function addProjectAlternative(tag) {
    $2sxc.cms.run({ tag: tag, action: "new", params: { contentType: "Project"}})
      .then(function () {
        alert("Thanks - we'll review your entry and publish it.")
      });
  }</script>

<span onclick='window.addProject(this)'>
  add your project
</span>

the tag is an HTML tag in the DOM, which is used to look up the context automatically (see edit-context)
the action is the verb for the cms-command to run
the params contains additional parameters for that command

Returned Promise

The run always returns a promise. As you can see in the sample above, this lets you show a specific message or do other things after the command has run.

To handle special cases like prevent a page-refresh or to do custom JS actions at certain points, check out the Workflows.

RunParams and RunParamsWithContext

Both commands take one object with named properties, to help keep the API stable across changes.

Tip

The Instance call on sxc.cms.run(...) uses the RunParams. It will throw an error if a context is also provided, because that indicates you're doing something wrong.

On the other hand the Global call on the $2sxc.cms.run(...) explicitly needs RunParamsWithContext either tag or context, and will throw an error if both are missing.

Command Workflow Example

Commands can be called with additional workflow steps which are processed before or after certain steps. For example, you can prevent the page from refreshing - to trigger an own JS-Reload or something.

👉 Read more about Workflows and Steps.

Command With Custom Code

There is a command called custom which is meant to be used for this. Check out the example on Custom Code

All Commands & Parameters

👉🏼 CommandNames

Details about some specific commands:

Demo App and further links

You should find some code examples in this demo App

JS Manage / Toolbar API Tutorial App
Blog post about Calling commands from links