home

SWire4js documentation

Introduction

SWire4js is a JavaScript library which facilitates the development of SWire web applications. The main purpose of this library is to provide the developer with utility functions for managing the SWire protocol, namely functions for encoding SWire requests and decoding SWire responses. Secondly, it provides a function for generating Stata missing values. SWire4js is self-contained in the swire4js.js file.

A SWire web application is a web page which interacts with Stata through SWire. The web page can be loaded from the local file-system or from the web. The advantages of the latter case are:

  • no local installation of the app is required
  • a web browser is the only requirement to run the app
  • developers can easily share their app with other users throughout the web.

Examples of SWire web applications include those of the SWire web apps collection. This is a collection of demo SWire applications which is useful in learning how to develop with SWire and SWire4js. These apps can been tried online here.

Security

Remember that the SWire server accepts any incoming connection, thus web pages and other clients applications can silently read or modify your current Stata data. It is recommended to activate the SWire server only if you are sure that there are no malicious clients on your local network and you do not open suspicious web pages.

Requirements

SWire4js requires the msgpack-lite library (http://kawanet.github.io/msgpack-lite/).

Encoding and decoding in the SWire protocol

A SWire message is a base64 encoding of a MessagePack serialization of a JSON string which represents the SWire request or the SWire response.
Let us suppose that we wish to encode the following SWire JSON request:

:::json
{
     "job":[{"method":"com.stata.sfi.Data.getVarCount"}]
}

The corresponding MessagePack serialization is:

81 A3 6A 6F 62 91 81 A6 6D 65 74 68 6F 64 BE 63 6F 6D 2E 73 74 61 74 61 2E 73 66 69 2E 44 61 74 61 2E 67 65 74 56 61 72 43 6F 75 6E 74

and its base64 encoding is:

gaNqb2KRgaZtZXRob2S+Y29tLnN0YXRhLnNmaS5EYXRhLmdldFZhckNvdW50

You can do the before described complete encoding by simply using the swire.encode function from the SWire4js library:

:::JavaScript
swire.encode({job:[{method:'com.stata.sfi.Data.getVarCount'}]});
// returns "gaNqb2KRgaZtZXRob2S+Y29tLnN0YXRhLnNmaS5EYXRhLmdldFZhckNvdW50"

The aforementioned complete encoding can be performed by simply using the swire.encode function from the SWire4js library:

:::JavaScript
swire.decode('gqZvdXRwdXSRgqZzdGF0dXOib2umb3V0cHV0DKZzdGF0dXOib2s=');
// returns {status:'ok',output:[{status:'ok',output:12}]}

Getting started with SWire4js

The following is a minimal SWire application, which has been developed with SWire4js:

:::html
<!DOCTYPE html>
<html>
    <head>
        <title>Test</title>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <script src="js/msgpack.min.js"></script>
        <script src="js/swire4js.js"></script>
    </head>
    <body>
        <script>alert(swire.getMissingValue());</script>
    </body>
</html>

The output of this minimal application is an alert window, displaying the standard Stata missing value (8.98846567431158e+307). This value is obtained via the swire.getMissingValue function. The previous minimal example is useful in highlighting how to include the SWire4js library and the required msgpack-lite library.

A more complex application using SWire4js is the following which consists of example.html and example.js files:

example.html:

:::html
<!DOCTYPE html>
<html>
    <head>
        <title>Minimal SWire web application</title>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <script src="js/jquery.js"></script>
        <script src="js/msgpack.min.js"></script>
        <script src="js/swire4js.js"></script>
        <script src="js/example.js"></script>
    </head>
    <body>
        <p>Obs count: <span id="count">?</span></p>
    </body>
</html>

example.js:

:::JavaScript
$(document).ready(function() {
    var request = {
        job: [
            {
                method: 'com.stata.sfi.Data.getObsCount'
            }      
        ]  
    };    

    $.ajax({
        url: 'http://127.0.0.1:50000',
        data: swire.encode(request),
        method: "POST",
        success: function(data) {
            var response = swire.decode(data);
            if (response.status === 'ok')
                $('#count').text(response.output[0].output);
        },
        error: function() {
            alert('network error');
        }
    }); 
});

The purpose of this application is to report the number of observations in the current Stata dataset on a web page. Once loaded, the web page will make an AJAX request to the SWire server. The SWire request is encoded by using the swire.encode function, while the SWire response is decoded via the swire.decode function. Note that the example web page uses the jQuery JavaScript library.

Reference

swire.encode(jsonRequest)

Encode a JSON request.

Parameters

jsonRequest - a JSON object representing a SWire request.

Returns

Nothing.

Examples

:::JavaScript
swire.encode({job:[{method:'com.stata.sfi.Data.getVarCount'}]});
// returns "gaNqb2KRgaZtZXRob2S+Y29tLnN0YXRhLnNmaS5EYXRhLmdldFZhckNvdW50"

swire.decode(base64String)

Decode a base64 response string.

Parameters

base64String - a base64 encoded string representing a SWire response.

Returns

A JSON.

Examples

:::JavaScript
swire.decode('gqZvdXRwdXSRgqZzdGF0dXOib2umb3V0cHV0DKZzdGF0dXOib2s=');
// returns {status:'ok',output:[{status:'ok',output:12}]}

swire.getMissingValue(value)

Parameters

value - an “a” to “z” optional string, representing a Stata missing value. If value is not provided, then a standard missing value (.) will be returned.

Returns

A number representing the requested Stata missing value.

Examples

:::JavaScript
swire.getMissingValue(); // returns 8.98846567431158e+307
swire.getMissingValue('g'); // returns 9.003826821704202e+307

Also see

SWire
A software interface, enabling us to query Stata for the executing of basic operations, such as reading or writing data

2016 Italian Stata Users Group Meeting, Rome 17-18 November
Abstract and slides presented at the Italian Stata Users Group Meeting 2016

SWire Web Apps Collection
A collection of web apps, interacting with Stata through SWire

SWire4R
An R package enabling R to interact with Stata for exchanging data

Swire4QGIS
A QGIS plugin enabling data exchange with Stata

SQuery
A web application for collecting questionnaires' responses in Stata