Javascript SDK


Problems Widget JavaScript SDK

The Sphere Engine JavaScript SDK library for Problems Widget (or simply Javascript SDK) is loaded asynchronously. For this reason, before using the functions provided by the library, we must be sure that it has been initialized.

First, place the following snippet just after the Sphere Engine Problems Widget:

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

As a result, the initialization code should look as follows:

<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>

The above code defines the SE.ready() function which has been designed in a way that ensures that features that use JavaScript SDK will be used only after all the required components have been loaded.

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 to the widget

We gain access to the widget by using the SE.widget() function, which based on the given widget ID (previously defined by the data-id attribute) returns the object of SEWidget class used to manage the widget. For example:

SE.ready(function() {
    var widget = SE.widget("widget");
    // variable "widget" is ready to use
});

The SEWidget class provides the following options for managing the widget:

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

Methods

The global SE object provides public methods for managing widgets.

SE.widget(id)

An object of class SEWidget, which represent the widget, is created.

Parameters

Name Type Description
id* string widget's identifier placed in the HTML document (data-id attribute)

Returned value

The object of class SEWidget is returned.

Example

Press the button to load the widget
Load widget
<div data-id="example-widget" data-widget="{widget_hash}"></div>
<script>
    SE.ready(function() {
        $('#btn-load-widget').on('click', function(e) {
            e.preventDefault();
            var SEWidget = SE.widget("example-widget");
        });
    });
</script><a href="#" id="btn-load-widget">Load widget</a>

SEWidget.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-widget" data-widget="{widget_hash}"></div>
<script>
SE.ready(function() {

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

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

});
</script>

SEWidget.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-widget" data-widget="{widget_hash}"></div>
<script>
SE.ready(function() {

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

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

});
</script>

Events

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

beforeSendSubmission

The event is invoked before sending a submission to the Sphere Engine system (i.e. after pressing the Submit button but before actually sending the submission).

Data sent to the callback function

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

Name Type Description
submission.source string the source code of the program sent in the submission
submission.language integer the identifier of programming language used to write the program

The value returned by the callback function

The value returned by the callback function determines whether the submission will be sent to the Sphere Engine system:

  • true - the submission is to be sent,
  • false - the submission will be stopped from being sent.

Example

Data:
Submit submission to see the result
<div data-id="example-widget" class="se-widget" data-widget="{widget_hash}"></div>
<script>
    SE.ready(function() {

        var beforeSendSubmission = function(data) {

            $('#result').html('')
                .append("> data.submission.language: " + data.submission.language + "<br><br>")
                .append("> data.submission.source: <br>" + data.submission.source + "<br><br>");

            return true;
        };

        var SEWidget = SE.widget("example-widget");
        SEWidget.events.subscribe('beforeSendSubmission', beforeSendSubmission);
    });
</script>

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

afterSendSubmission

The event is invoked immediately after the submission has been sent to the Sphere Engine system.

Data sent to the callback function

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

Name Type Description
submission.id integer submission identifier in the Sphere Engine system
submission.apiId integer submission identifier in the Sphere Engine system used to access submission using API; use getSubmission() API method to fetch all submission details
user.uuid string user identifier generated by the Sphere Engine system
user.id string user identifier provided during widget initialization (user-id parameter)
user.name string user name provided on the welcome page
user.email string user e-email address provided on the welcome page

Example

Data:
Submit submission to see the result
<div data-id="example-widget" class="se-widget" data-widget="{widget_hash}"></div>
<script>
    SE.ready(function() {

        var afterSendSubmission = function(data) {

            $('#result').html('')
                .append("> data.submission.id: " + data.submission.id + "<br><br>");
        };

        var SEWidget = SE.widget("example-widget");
        SEWidget.events.subscribe('afterSendSubmission', afterSendSubmission);
    });
</script>

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

checkStatus

The event is invoked regularly while checking the status of the submission during execution.

Data sent to the callback function

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

Name Type Description
submission.id integer submission identifier in the Sphere Engine system
submission.apiId integer submission identifier in the Sphere Engine system used to access submission using API; use getSubmission() API method to fetch all submission details
submission.time float execution time in seconds (available after execution)
submission.memory integer memory consumption in kilobytes (available after execution)
status.number integer numeric value of the submission's status (see: list of statuses)
status.description string description of the submission's status
user.uuid string user identifier generated by the Sphere Engine system
user.id string user identifier provided during widget initialization (user-id parameter)
user.name string user name provided on the welcome page
user.email string user e-email address provided on the welcome page

Example

Data:
Submit submission to see the result
<div data-id="example-widget" class="se-widget" data-widget="{widget_hash}"></div>

<script>
    SE.ready(function() {

        var checkStatus = function(data) {
            $('#result')
                .append("<br><br>")
                .append("> submission.id: " + data.submission.id + "<br>")
                .append("> status.number: " + data.status.number + "<br>")
                .append("> status.description: " + data.status.description + "<br>")
                .append("> submission.memory: " + data.submission.memory + "<br>")
                .append("> submission.time: " + data.submission.time + "<br>");

            $('#result').scrollTop($('#result').prop("scrollHeight"));
        };

        var SEWidget = SE.widget("example-widget");
        SEWidget.events.subscribe('checkStatus', checkStatus);
    });
</script>

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

sessionOver

The event is invoked after the time set for solving the task has expired.

Example

Data:
Start the session and wait 1 minute
<div data-id="example-widget" class="se-widget" data-widget="{widget_hash}"></div>

<script>
    SE.ready(function() {
        var sessionOver = function() {
            $('#result').html('the session is over');
        };

        var SEWidget = SE.widget("example-widget");
        SEWidget.events.subscribe('sessionOver', sessionOver);
    });
</script>

Data:
<pre id="result" style="height: 50px;">Start the session and wait 1 minute</pre>

welcomeUser

The event is invoked after sending the username and email address entered on the welcome page (available only for the configuration of the widget with the welcome page enabled).

Data sent to the callback function

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

Name Type Description
user.uuid string user identifier generated by the Sphere Engine system
user.id string user identifier provided during widget initialization (user-id parameter)
user.name string user name provided on the welcome page
user.email string user e-email address provided on the welcome page

Example

Data:
Complete the form to see the result
<div data-id="example-widget" class="se-widget" data-widget="{widget_hash}"></div>

<script>
    SE.ready(function() {
        var welcomeUser = function(data) {
            $('#result').html('')
                .append("> user.name: " + data.user.name + "<br><br>")
                .append("> user.email: " + data.user.email + "<br><br>");
        };

        var SEWidget = SE.widget("example-widget");
        SEWidget.events.subscribe('welcomeUser', welcomeUser);
    });
</script>

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

Compilers Widget JavaScript SDK

The Sphere Engine JavaScript SDK library for Compilers Widget (or simply Javascript SDK) is loaded asynchronously. For this reason, before using the functions provided by the library, we must be sure that it has been initialized.

First, place the following snippet just after the Sphere Engine Compilers Widget:

<script>SEC.ready=function(e){"loading"!=document.readyState&&"interactive"!=document.readyState?e():window.addEventListener("load",e)};</script>

As a result, the initialization code should look as follows:

<script>SEC_HTTPS = false;
SEC_BASE = "<customized_link>"; 
(function(d, s, id){ SEC = window.SEC || (window.SEC = []);
  var js, fjs = d.getElementsByTagName(s)[0];
  if (d.getElementById(id)) return; js = d.createElement(s); js.id = id; 
  js.src = (SEC_HTTPS ? "https" : "http") + "://" + SEC_BASE + "/static/sdk/sdk.js";
  fjs.parentNode.insertBefore(js, fjs);   
}(document, "script", "sphere-engine-compilers-jssdk"));
SEC.ready=function(e){"loading"!=document.readyState&&"interactive"!=document.readyState?e():window.addEventListener("load",e)};
</script>

The above code defines the SEC.ready() function which has been designed in a way that ensures that features that use JavaScript SDK will be used only after all the required components have been loaded.

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

SEC.ready(function() {
    // Sphere Engine JavaScript SDK usage
});

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

Access to the widget

We gain access to the widget by using the SEC.widget() function, which based on the given widget ID (previously defined by the data-id attribute) returns the object of SECWidget class used to manage the widget. For example:

SEC.ready(function() {
    var widget = SEC.widget("widget");
    // variable "widget" is ready to use
});

The SECWidget class provides the following options for managing the widget:

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

Methods

The global SEC object provides public methods for managing widgets.

SEC.widget(id)

An object of class SECWidget, which represents the widget, is created.

Parameters

Name Type Description
id* string widget's identifier placed in the HTML document ("data-id" attribute)

Returned value

An object of class SECWidget is returned.

Example

Press the button to load the widget
Load widget
<div data-id="example-widget" data-widget="{widget_hash}"></div>
<script>
    SEC.ready(function() {
        $('#btn-load-widget').on('click', function(e) {
            e.preventDefault();
            var SECWidget = SEC.widget("example-widget");
        });
    });
</script><a href="#" id="btn-load-widget" class="btn btn-default">Load widget</a>

SECWidget.config(config)

Setting the widget's configuration data.

Parameters

Name Type Description
config.code.compiler integer programming language identifier
config.code.source string program's source code
config.code.input string input data
config.compilers.list array[int] list of language identifiers (see. list of languages)

Example

<div data-id="example-widget" data-widget="{widget_hash}"></div>
<script>
    SEC.ready(function() {
        var SECWidget = SEC.widget("example-widget");
        SECWidget.config({
            code: {
                compiler: 28,
                source: "#!/bin/bash\n\necho test",
                input: "",
            },
            compilers: {
                list: [11, 21, 28, 33]
            }
        });
    });
</script>

SECWidget.loadSourceCode(compiler, sourceCode, input)

Loading data (source code, programming language, input data) to the running editor.

Parameters

Name Type Description
compiler integer programming language identifier (see list of languages)
sourceCode string program's source code
input string input data

Example

<div data-id="example-widget" data-widget="{widget_hash}"></div>
<script>
    SEC.ready(function() {
        var sourceCode = "<?php \n\n$hi = fopen('php://stdin', \"r\");\nfscanf($hi, \"%d\", $n);\n\
fclose($hi);\n\necho 'number: ' . $n;";
        var SECWidget = SEC.widget("example-widget");
        SECWidget.loadSourceCode(29, sourceCode, "5");
    });
</script>

SECWidget.setCompilers(compilersList)

Selection of programming languages ​​available in the widget.

Parameters

Name Type Description
compilersList array[int] list of language identifiers (see. list of languages)

Example

<div data-id="example-widget" data-widget="{widget_hash}"></div>
<script>
    SEC.ready(function() {
        var SECWidget = SEC.widget("example-widget");
        SECWidget.setCompilers([1,2]);
    });
</script>

SECWidget.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-widget" data-widget="{widget_hash}"></div>
<script>
SEC.ready(function() {

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

    var SECWidget = SEC.widget("example-widget");
    SECWidget.events.subscribe('{name_of_the_event}', callback);

});
</script>

SECWidget.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-widget" data-widget="{widget_hash}"></div>
<script>
SEC.ready(function() {

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

    var SECWidget = SEC.widget("example-widget");
    SECWidget.events.unsubscribe('{name_of_the_event}', callback);

});
</script>

Events

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

beforeSendSubmission

The event is invoked before sending a submission to the Sphere Engine system (i.e. after pressing the Submit button but before actually sending the submission).

Data sent to the callback function

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

Name Type Description
submissionSource string the source code of the program sent in the submission
submissionLanguage string the programming language used to write the program
submissionInput string input data sent in the submission

The value returned by the callback function

The value returned by the callback function determines whether the submission will be sent to the Sphere Engine system:

  • true - the submission is to be sent,
  • false - the submission will be stopped from being sent.

Example

Data:
Submit submission to see the result
<div data-id="example-widget" data-widget="{widget_hash}"></div>
<script>
    SEC.ready(function() {
        var beforeSendSubmission = function(data) {
            $('#result').html('')
                .append("> submissionLanguage: " + data.submissionLanguage + "<br><br>")
                .append("> submissionInput: <br>" + data.submissionInput + "<br><br>")
                .append("> submissionSource: <br>" + data.submissionSource + "<br><br>");
            return true;
        };
        var SECWidget = SEC.widget("example-widget");
        SECWidget.events.subscribe('beforeSendSubmission', beforeSendSubmission);
    });
</script>
Data:
<pre id="result" style="height: 300px;">Submit submission to see the result</pre>

afterSendSubmission

The event is invoked immediately after the submission has been sent to the Sphere Engine system.

Data sent to the callback function

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

Name Type Description
submissionId integer submission identifier in the Sphere Engine system

Example

Data:
Submit submission to see the result
<div data-id="example-widget" data-widget="{widget_hash}"></div>
<script>
    SEC.ready(function() {
        var afterSendSubmission = function(data) {
            $('#result').html('')
                .append("> submissionId: " + data.submissionId + "<br><br>");
        };
        var SECWidget = SEC.widget("example-widget");
        SECWidget.events.subscribe('afterSendSubmission', afterSendSubmission);
    });
</script>
Data:
<pre id="result" style="height: 100px;">Submit submission to see the result</pre>

checkStatus

The event is invoked regularly while checking the status of the submission during execution.

Data sent to the callback function

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

Name Type Description
submissionId integer submission identifier in the Sphere Engine system
submissionTime integer execution time in seconds (available after execution)
submissionMemory integer memory consumption in kilobytes (available after execution)
statusNumber integer numeric value of the submission's status (see: list of statuses)
statusDescription string description of the submission's status

Example

Data:
Submit submission to see the result
<div data-id="example-widget" data-widget="{widget_hash}"></div>
<script>
    SEC.ready(function() {
        var checkStatus = function(data) {
            $('#result')
                .append("<br><br>")
                .append("> submissionId: " + data.submissionId + "<br>")
                .append("> statusNumber: " + data.statusNumber + "<br>")
                .append("> statusDescription: " + data.statusDescription + "<br>")
                .append("> submissionMemory: " + data.submissionMemory + "<br>")
                .append("> submissionTime: " + data.submissionTime + "<br>");
            $('#result').scrollTop($('#result').prop("scrollHeight"));
        };
        var SECWidget = SEC.widget("example-widget");
        SECWidget.events.subscribe('checkStatus', checkStatus);
    });
</script>        
Data:
<pre id="result" style="height: 300px;">Submit submission to see the result</pre>

enterFullScreen

The event is invoked when the widget is switched to full screen mode.

Example

<div data-id="example-widget" data-widget="{widget_hash}"></div>
<script>
    SEC.ready(function() {
        var enterFullScreen = function() {
            alert('enter fullscreen');
        };
        var SECWidget = SEC.widget("example-widget");
        SECWidget.events.subscribe('enterFullScreen', enterFullScreen);
    });
</script>

exitFullScreen

The event is invoked when leaving the full screen mode.

Example

<div data-id="example-widget" data-widget="{widget_hash}"></div>
<script>
    SEC.ready(function() {
        var exitFullScreen = function() {
            alert('exit fullscreen');
        };
        var SECWidget = SEC.widget("example-widget");
        SECWidget.events.subscribe('exitFullScreen', exitFullScreen);
    });
</script>