Containers
Workspaces - JavaScript SDK

JavaScript Integration

You need to insert two snippets of HTML code responsible for the initialization and display of the workspace.

Initializing the workspace

The code responsible for workspace initialization should be inserted only once, immediately after the <body> element.

<script>(function(d, s, id){
  SE_BASE = "<customer_id>.containers.sphere-engine.com";
  SE_HTTPS = true;
  SE_USE_APPEND_CHILD = true;
  SE = window.SE || (window.SE = []);
  var js, fjs = d.getElementsByTagName(s)[0];
  if (d.getElementById(id)) return;
  js = d.createElement(s); js.id = id;
  js.src = (SE_HTTPS ? "https" : "http") + "://" + SE_BASE + "/static/sdk/sdk.min.js";
  fjs.parentNode.insertBefore(js, fjs);
}(document, "script", "sphere-engine-jssdk"));

SE.ready = function(f) {
  if (document.readyState != "loading" && document.readyState != "interactive") f();
  else window.addEventListener("load", f);
};
</script>

Displaying the workspace

The following code should be inserted on the page in the spot where you want the workspace to be displayed:

<div data-id="example-workspace" data-workspace="<workspace_id>"></div>
<script>
SE.ready(function() {
    var workspace = SE.workspace("example-workspace");
});
</script>

The workspace_id parameter which is the value of the data-workspace attribute is the unique identifier of the workspace in the Sphere Engine system. It can be found in API response.

Features

The following table lists features available to extend functionality of the workspaces:

Name Description
fullscreenmode allows to use full-screen mode

To add features to the workspace, add the data-features attribute containing a list of features seperated by a comma to the workspace's div element:

<div data-id="example-workspace" data-features="fullscreenmode" data-workspace="<workspace_id>"></div>

Full-screen mode

Enables management of the full-screen mode. It delivers:

  • full-screen toggle button embedded in the workspace,
  • enterFullScreen and exitFullScreen SDK methods,
  • SDK events notifying about toggling full-screen mode.
<div data-features="fullscreenmode" (...)></div>

JavaScript SDK

The Sphere Engine JavaScript SDK library for the Containers module (or simply JavaScript SDK) is loaded asynchronously. For this reason, before using the functions provided by the library, it has to be initialized.

All operations that use JavaScript SDK should be performed through the SE.ready() function, i.e., according to the following scheme:

<script>
SE.ready(function() {
    // Sphere Engine JavaScript SDK usage
});     
</script>

Using the SE.ready() function ensures that the library has been loaded, the SE object has been initialized, and no errors will occur while scripts are being executed.

Access

We gain access to the workspace by using the SE.workspace() function, which (basing on the given identifier, previously defined by the data-id attribute) returns the object of SEWorkspace class used to manage the workspace. For example:

<script>
    SE.ready(function() {
        var workspace = SE.workspace("example-workspace");
        // variable `workspace` is ready to use
    });
</script>

The SEWorkspace class provides the following options for managing the workspace:

  • creating a workspace,
  • dedicated events for handling actions performed by the workspace.

Methods

The global SE object provides public methods for managing workspace.

METHOD SE.workspace(id)

An object of class SEWorkspace, which represent the workspace, is created.

Parameters
Name Type Description
id * string

workspace's identifier placed in the HTML document (data-id attribute)
Returned value

An object of class SEWworkspace is returned.

Example
<div data-id="example-workspace" data-workspace="{workspace_id}"></div>
<script>
    SE.ready(function() {
        document.addEventListener("click", function(event) {
            if (event.target && event.target.id === "btn-load-workspace") {
                var SEWorkspace = SE.workspace("example-workspace");
            }
        });
    });
</script>
<a href="#" id="btn-load-workspace">Load workspace</a>

METHOD SEWorkspace.destroy()

Destroys the workspace.

Example
<div data-id="example-workspace" data-workspace="{workspace_id}"></div>
<script>
    SE.ready(function() {
        document.addEventListener("click", function(event) {
            if (event.target && event.target.id === "btn-destroy-workspace") {
                var SEWorkspace = SE.workspace("example-workspace");
                SEWorkspace.destroy();
            }
        });
    });
</script>
<a href="#" id="btn-destroy-workspace" class="btn btn-default">Destroy workspace</a>

METHOD SEWorkspace.getFileContent(file_path)

Retrieve the content of the specified file. The file's content will be delivered as the fileContent event.

Parameters
Name Type Description
file_path * string

path to the file; relative to /home/user/workspace (e.g., TEST.txt) or absolute path
Example
<div data-id="example-workspace" data-workspace="{workspace_id}"></div>
<script>
SE.ready(function() {

    var callback = fileContentCallback(e) {
        // Your code goes here
    };

    var SEWorkspace = SE.workspace("example-workspace");
    SEWorkspace.events.subscribe('fileContent', fileContentCallback);
    SEWorkspace.getFileContent('TEST.txt');

});
</script>

METHOD SEWorkspace.getStageStream(stage, stream)

Retrieve the contents of the specified stage stream. It will be delivered as the stageStream event.

Parameters
Name Type Description
stage * string

stage name; must be one of the following values: init, build, run, test, post
stream * string

stream name; must be one of the following values: output, error
Example
<div data-id="example-workspace" data-workspace="{workspace_id}"></div>
<script>
SE.ready(function() {

    var callback = stageStreamCallback(e) {
        // Your code goes here
    };

    var SEWorkspace = SE.workspace("example-workspace");
    SEWorkspace.events.subscribe('stageStream', stageStreamCallback);
    SEWorkspace.getStageStream('run', 'output');

});
</script>

METHOD SEWorkspace.enterFullScreen()

Toggles the workspace to full-screen mode.

This method requires adding fullscreenmode feature to the feature list.

Example
<div data-id="example-workspace" data-workspace="{workspace_id}" data-features="fullscreenmode"></div>
<script>
SE.ready(function() {
    const SEWorkspace = SE.workspace("example-workspace");
    SEWorkspace.enterFullScreen();
});
</script>

METHOD SEWorkspace.exitFullScreen()

Exits the full-screen mode in the workspace.

This method requires adding fullscreenmode feature to the feature list.

Example
<div data-id="example-workspace" data-workspace="{workspace_id}" data-features="fullscreenmode"></div>
<script>
SE.ready(function() {
    const SEWorkspace = SE.workspace("example-workspace");
    SEWorkspace.exitFullScreen();
});
</script>

METHOD SEWorkspace.runScenario(scenario, options)

Runs scenario in the workspace. It can only be run if the entire IDE is loaded (i.e., the editor and other components are visible).

This function raises the Error exception unless the entire IDE is loaded, e.g., the workspace is still loading, is no longer available, or cannot be loaded.

Parameters
Name Type Description
scenario * string

scenario name to be run
options object

additional options
options.onScenarioStartSuccess function 
function () {}

This will be called when the scenario starts successfully. It means that the user will begin to see the output of the scenario.

Important: it doesn't signify that the scenario has ended.
options.onScenarioStartFailure function 
function (message: string) {}

This will be called when a scenario fails to start.

It can mean, among other things, a connection issue, that the runScenario method is being called too often, or that a scenario is already in the process of starting.

The message parameter contains the cause of the failure.
Example
<div data-id="example-workspace" data-workspace="{workspace_id}"></div>
<script>
SE.ready(function() {
    const SEWorkspace = SE.workspace("example-workspace");
    SEWorkspace.runScenario('run', {
        onScenarioStartSuccess: function () {}, 
        onScenarioStartFailure: function (message) {},
    });
});
</script>

METHOD SEWorkspace.events.subscribe(event, callback)

Assigns a function to the event (see list of events).

Parameters
Name Type Description
event * string

the name of the event to assign a function to
callback * function

function to be called on an event
Example
<div data-id="example-workspace" data-workspace="{workspace_id}"></div>
<script>
SE.ready(function() {

    var callback = function(data) {
        // Your code goes here
    };

    var SEWorkspace = SE.workspace("example-workspace");
    SEWorkspace.events.subscribe('{name_of_the_event}', callback);

});
</script>

METHOD SEWorkspace.events.unsubscribe(event, callback)

Removes a function from the list of functions assigned to the event (see list of events).

Parameters
Name Type Description
event * string

the name of the event to remove the function from
callback * function

function to be removed from the list of functions assigned to the event
Example
<div data-id="example-workspace" data-workspace="{workspace_id}"></div>
<script>
SE.ready(function() {

    var callback = function(data) {
        // Your code goes here
    };

    var SEWorkspace = SE.workspace("example-workspace");
    SEWorkspace.events.unsubscribe('{name_of_the_event}', callback);

});
</script>

Events

An object of the SEWorkspace class has a collection of dedicated events called at specific moments of the workspace's operation.

EVENT afterScenarioExecution

The event is invoked immediately after the scenario finishes executing.

Data sent to the callback function

An object with the following fields is sent to the callback function

Name Type Description
data.scenario string

scenario name
Example
<div data-id="example-workspace" data-workspace="{workspace_id}"></div>
<script>
    SE.ready(function() {

        var afterScenarioExecution = function(e) {
            console.log("> scenario: " + e.data.scenario);
        };

        var workspace = SE.workspace("example-workspace");
        workspace.events.subscribe('afterScenarioExecution', afterScenarioExecution);
    });
</script>

Data:
<pre id="result" style="height: 100px;">Submit submission to see the result</pre>

EVENT afterScenarioExecutionExt

The event is invoked after the scenario finishes executing and once the workspace receives the execution details from the backend. It always follows the afterScenarioExecution event.

(Previously, this method was named scenarioResultJson)

Data sent to the callback function

An object with the following fields is sent to the callback function

Name Type Description
data.scenario string

scenario name
data.result.status.code integer

result status code (see section: submission status)
data.result.status.name string

status name
data.result.time float

execution time [seconds]
data.result.score float

obtained score
data.stages.{stage}.skipped boolean

whether the stage has been skipped
data.stages.{stage}.exit_code integer or null

stage termination exit code;
null if exit code is not available (e.g. stage skipped)
data.stages.{stage}.signal integer or null

interrupt signal for the stage termination;
null if signal is not available (e.g. stage skipped)
data.stages.{stage}.time float

stage execution time [seconds]
Example
<div data-id="example-workspace" data-workspace="{workspace_id}"></div>
<script>
    SE.ready(function() {
        var afterScenarioExecutionExt = function(e) {
            console.log("> scenario: " + e.data.scenario);
            console.log("> status: " + e.data.result.status.code);
        };

        var workspace = SE.workspace("example-workspace");
        workspace.events.subscribe('afterScenarioExecutionExt', afterScenarioExecutionExt);
    });
</script>

Data:
<pre id="result" style="height: 100px;">Submit submission to see the result</pre>

EVENT fileContent

The event is invoked after calling the getFileContent method or after using se_utils_cli event command in the stage script during the scenario execution.

Data sent to the callback function

An object with the following fields is sent to the callback function

Name Type Description
data.file_path string

file path
data.content string or null

file content encoded with base64 (if no errors occurred)
data.error string or null

error message

EVENT stageStream

The event is invoked after calling the getStageStream method.

Data sent to the callback function

An object with the following fields is sent to the callback function

Name Type Description
data.stage string

stage name (init, build, run, test, post)
data.stream string

stream name (output, error)
data.content string or null

stream content encoded with base64 (if no errors occurred)
data.error string or null

error message

EVENT enterFullScreen

The event is invoked when the workspace has entered the full-screen mode.

Example
<div data-id="example-workspace" data-workspace="{workspace_id}" data-features="fullscreenmode"></div>
<script>
    SE.ready(function() {
        const enterFullScreen = function() {
            alert('enter fullscreen');
        };

        const workspace = SE.workspace("example-workspace");
        workspace.events.subscribe('enterFullScreen', enterFullScreen);
    });
</script>

EVENT exitFullScreen

The event is invoked when the workspace has exited the full-screen mode.

Example
<div data-id="example-workspace" data-workspace="{workspace_id}" data-features="fullscreenmode"></div>
<script>
    SE.ready(function() {
        const exitFullScreen = function() {
            alert('exit fullscreen');
        };

        const workspace = SE.workspace("example-workspace");
        workspace.events.subscribe('exitFullScreen', exitFullScreen);
    });
</script>

Downloading files from the workspace

To retrieve a selected file from the workspace, you can use the SDK in two ways:

  1. By calling the SDK getFileContent method directly,
  2. By executing the command se_utils_cli event fileContent file_path in the integrated terminal inside the workspace.

In both cases, the SDK will receive a fileContent event containing the file content encoded using base64. In the case of an error, the event will have an error field indicating the reason for the error.

  Contents