Containers - Workspaces - JavaScript SDK - Sphere Engine documentation

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 = 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 workspace identifier, previously defined by the data-workspace 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:

By calling the SDK getFileContent method directly,
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.