- Sphere Engine overview
- Compilers
- Overview
- API integration
- JavaScript widget
- Resources
- Problems
- Overview
- API integration
- JavaScript widget
- Handbook
- Resources
- Containers
- Overview
- API
- Workspaces
- Handbook
- RESOURCES
- Programming languages
- Modules comparison
- Webhooks
- Infrastructure management
- API changelog
- FAQ
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 = "<customized_link>";
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.
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:
SE.ready(function() {
// Sphere Engine JavaScript SDK usage
});
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:
SE.ready(function() {
var workspace = SE.workspace("<id>");
// variable `workspace` is ready to use
});
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.
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 ( |
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>
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>
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 |
Example
<div data-id="example-workspace" data-workspace="{workspace_id}"></div>
<script>
SE.ready(function() {
var callback = fileContentCallback(data) {
// Your code goes here
};
var SEWorkspace = SE.workspace("example-workspace");
SEWorkspace.events.subscribe('fileContent', fileContentCallback);
SEWorkspace.getFileContent('TEST.txt');
});
</script>
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: |
stream * | string | stream name; must be one of the following values: |
Example
<div data-id="example-workspace" data-workspace="{workspace_id}"></div>
<script>
SE.ready(function() {
var callback = fileContentCallback(data) {
// Your code goes here
};
var SEWorkspace = SE.workspace("example-workspace");
SEWorkspace.events.subscribe('fileContent', fileContentCallback);
SEWorkspace.getStageStream('run', 'output');
});
</script>
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>
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.
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.name: " + 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>
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 | |
data.result.status.name | string | |
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 | stage termination exit code |
data.stages.{stage}.signal | integer | termination interrupt signal for stage |
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.name: " + 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>
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 | file content encoded with |
data.error | string | error message |
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 |
data.stream | string | stream name |
data.content | string | stream content encoded with |
data.error | string | error message |
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.