Setting up a SwellRT Web App

Pablo Ojanguren edited this page Mar 20, 2017 · 1 revision

In this page you can learn about:

Configuring SwellRT JavaScript API client

Add the a script tag in your web page

<script type="text/javascript" src="http://<swellrt-server-host>:<swellrt-server-port>/swellrt.js"></script>

The server runs by default at http://localhost:9898.

In order to know when SwellRT is ready to use, you can register function callbacks:

SwellRT.ready(function() {

  console.log("SwellRT is ready to use");

  });

Sessions

SwellRT objects are always handled in the context of user sessions. To create new users please read the "Working with users" page.

It is a best practise to map SwellRT users with the app's users. However there is no restrictions to use the same SwellRT user for different app's users.

A work flow diagram of a SwellRT app follows:

A session is started with the login() method passing the user's credentials as parameters:


    SwellRT.login(

    // Parameters

    {
        id : "john@local.net",
        password : s8sjf72z!3"
    },


    // onComplete callback

    function(response) {

        if (response.error) {

            // ERROR

        } else if (response.data) {

           // OK
           // response.data => user profile data
        }

    });

The response will return user's profile info.

Sessions are closed using the logout() method. Call it to close the current opened session.

    SwellRT.logout(

        function(res) {

            if (res.error) {

                // ERROR

            } else if (res.data) {

                // OK
            }

        });

Also it can be used to close one specific user session:

SwellRT.logout(
    {
        id: "john@local.net"
    },

    function(res) {

        if (res.error) {

            // ERROR

        } else if (res.data) {

            // OK
        }

    });

Anonymous Sessions

To start an anonymous sessions use the user SwellRT.user.ANONYMOUS and no password. The session will be only valid during the browser session.

    SwellRT.login(

    // Parameters

    {
        id : SwellRT.user.ANONYMOUS
    },

    function(res) {
        ...
    });

Resuming Sessions

If a previous session exists in the browser, apps can try to resume it using following method:

SwellRT.resume(

    // onComplete callback

    function(response) {

        if (response.error) {

            // ERROR

        } else if (response.data) {

           // OK
           // response.data => user profile data
        }

    });

SwellRT supports different sessions in each browser tab. Sessions not explicitly closed (see logout() method) can be resumed from any new tab. To resume a specific session, pass the user's id as first argument of the resume() method.

Session Lifecycle and Events

During a session, applications (and users) will work with collaborative objects performing live communications behind the scenes. Therefore, apps must be aware of network issues that can prevent further interaction.

The following diagram shows the session lifecycle through those network events triggered by SwellRT:

These events can be handled by applications registering callback function with the method

SwellRT.on(SwellRT.events.<global_event>, <callback_function>(data));

Session / Network Events

SwellRT.events.NETWORK_CONNECTED

Event triggered on network new connection or reconnection. The client app can resume API operations.

SwellRT.events.NETWORK_DISCONNECTED

Event triggered on a temporary or total network disconnection. The app should prevent further calls to the API until a NETWORK_CONNECTED event is received.

SwellRT.events.DATA_STATUS_CHANGED

Event triggered on data changes performed by your app. It provides three status indicators each time your app makes changes to a data model:

data.inFlightSize:

  • Number of changes made in the current opened data model but not sent to the server yet.

data.uncommittedSize:

  • Number of changes made in the current opened data model, already sent to the server but not commited in server storage yet.

data.unacknowledgedSize:

  • Number of changes made in the current opened data model commited in the server without acknowledge.

Any local changes should trigger eventually this event with all values equals to 0. This fact will confirm that all your changes are properly stored and distributed among other participants.

Be aware of uncommited and unacknowledge changes: if a relative period of time goes by but a DATA_STATUS_CHANGED event with all values equals to zero doesn't occur, probably a communication problem exists and the app should prevent further use of the API.

SwellRT.events.FATAL_EXCEPTION

Event triggered on fatal exception in the client or server. You should stop your app. You can check data.cause for more information. The app should start a new session (and open a model) before resuming API operations.

Tips using Sessions

  • Disable user interaction with collaborative objects during network disconnection periods.
  • Control if DATA_STATUS_CHANGED events having all values equals to 0 are not received in an interval of 2-10 seconds. In that situation, assume you must restart the session.
  • Restart a session when a fatal exception occurs or changes are not commited (see previous tip). Remeber that collaborative object instances must be open again.
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.