Document Sandbox

The document sandbox is a sandboxed JavaScript execution environment, which allows to execute add-on's JavaScript code securely and synchronously in another JavaScript environment e.g., browser.

Overview

The document sandbox exposes three categories of APIs, which each have their own specific references and are outlined below.

Communication APIs

The communication APIs allow you to communicate between the document sandbox and the iframe runtime where your add-on is running via exposed APIs.

Web APIs

The document sandbox does NOT provide a full fledged browser’s JavaScript execution environment. Most of the browsers APIs/Global Objects are not available. For these, the developers can use iframe runtime environment and communicate the result back to the script running inside document sandbox environment. Some of the commonly used Web APIs (with limited scope) have been provided inside document sandbox environment.

Document APIs

The document APIs provide access to the user's document structure and properties, and allow you to make changes and author content to the Adobe Express document via the provided APIs.

Please see the tutorials section to learn more about using the document sandbox and Adobe Express Document APIs.

Document Sandbox's JavaScript Engine

The document sandbox is a sandboxed JavaScript execution environment, which allows to execute add-on's JavaScript code securely and synchronously in another JavaScript environment e.g., browser.

Some key concepts to note about the document sandbox include:

Limited access to browser APIs (see the Web APIs reference). Note however, you can use the communication APIs to expose browser APIs (ie: fetch) from the iframe environment to be used in the document sandbox.
Runs in a slower execution environment.
Provides no debugging capabilities other than those provided by the injected console functions.
Runs in the same context/thread as the host's application business logic, thus providing access to interact with it via the injected APIs.

Getting Started with the APIs

The methods defined in the communication API reference are used to expose and use the API proxies between the iframe and script environments of your add-on. Start with the communication reference to learn more about how to expose APIs and use them from either environment.

Document sandbox entry point

To use the document sandbox APIs in your add-on, start by defining a new documentSandbox entry point in your manifest.json file with the value set to the name of the file containing the JavaScript code you're using with the document sandbox APIs:

    "entryPoints": [
        {
            "type": "panel",
            "id": "panel1",
            "main": "index.html",
            "documentSandbox": "code.js"
        }
    ]
Copied to your clipboard
    "entryPoints": [
        {
            "type": "panel",
            "id": "panel1",
            "main": "index.html",
            "documentSandbox": "code.js"
        }
    ]

The JavaScript code in the file referenced can then access any of the injected global objects and module APIs defined in all of the APIs outlined in this set of references (communication APIs, Web APIs and document APIs).

CLI Generated Document Sandbox Add-on

The quickest way to get started with a scaffolded project set up with the document sandbox bindings for you is via the CLI. When creating a new add-on, you can specify a template name that includes the document sandbox support:

npx @adobe/create-ccweb-add-on helloworld --template javascript-with-document-sandbox

or the CLI will prompt you to choose from the base templates, then ask if you want to include the document sandbox:

CLI prompt for document sandbox

Choose Yes at the prompt to include the document sandbox setup in your generated project. The project structure that's generated will differ depending on which base template you chose, but the two important additions to note, are the existence of a script entry point in your manifest.json, and the code.js file it references.

"entryPoints": [
        {
            "type": "panel",
            "id": "panel1",
            "main": "index.html",
            "documentSandbox": "code.js"
        }
    ]
Copied to your clipboard
"entryPoints": [
        {
            "type": "panel",
            "id": "panel1",
            "main": "index.html",
            "documentSandbox": "code.js"
        }
    ]

The screenshot below shows what the default script-based add-on generated from the CLI looks like when running:

script add-on sample screenshot

Please refer to the Using the CLI section to get more information on how to use the CLI and create new add-on.

Code Samples

The following code samples have also been provided to help you get started using these new document sandbox APIs.

communication-iframe-documentSandbox sample

Demonstrates the use of the communication APIs to expose and proxy APIs bidirectionally between the iframe and document sandbox environments. Also includes demonstrating how to use some of the Web APIs such as console.log().

editor-apis sample

Demonstrates how to use the document APIs to create various shapes and add them to the document.

image-and-page sample

A more comprehensive example of using the document APIs to add a page, images and shapes, as well as clear the artboard.

Debugging script based add-ons

Debugging with breakpoints from the document sandbox (via code.js) is currently not supported and for the time-being, only console logging (via console.log()) can be used. However, support for debugging by applying breakpoints in the code will be available in the near future. Please refer to Example Code Snippet, where a rectangle object is printed to console for debugging purpose.

constants

Communication APIs