Skip to content
Fetching contributors…
Cannot retrieve contributors at this time
208 lines (151 sloc) 10.4 KB

Session preparation and join

A web application creates one :class:`SessionInterface` instance per browser document frame to control authentication, session preparation, session joining, and session exiting operations against a coweb server. The application receives callbacks from the :class:`SessionInterface` as these operations progress, succeed, or fail.

The use of the session API has the following requirements:

  1. If the application needs a custom :data:`cowebConfig`, the configuration must be defined before before loading any coweb module.
  2. The application must use an `AMD`_ loader to import the the coweb/main module.

Initializing the session singleton

Using the session instance

Singleton encapsulating the session APIs for web application use. A web application should use the :func:`coweb.initSession` factory function instead of instantiating this object directly.

Use cases

The following code snippets demonstrate some common uses of the session API.

Application attempts to enter a session

Assume an application wants to enter a session without delay.

// get session interface
var sess = coweb.initSession();
// use defaults, collaborative session, join and update automatically
sess.prepare().then(function(info) {
   // invoked after prepare, join, and update complete
}, function(err) {
   // invoked on any error during the sequence
});

Application acts on session info before joining

Imagine an application wants to configure its UI based on the session information returned in the response to the prepare request before joining the session.

// get session interface
var sess = coweb.initSession();
// use defaults to prepare
sess.prepare({autoJoin : false}).then(function(info) {
   // invoked after prepare completes
   // app can do work here (e.g., shows session info in its UI)
   // then app can continue with join
   return sess.join();
}, function(err) {
   // invoked on any error during prepare
}).then(function() {
   // invoked after join and update complete
}, function(err) {
   // invoked on any error during join or update
});

Application does its own authentication

Say an application wants to collection credentials from a user before attempting to prepare the session.

// get session interface
var sess = coweb.initSession();
// assume username / password vars contain info collected via a form or
// some other means
sess.login(username, password).then(function() {
   // invoke session prepare now; callback/errback omitted
   sess.prepare();
}, function(err) {
   // auth failed, prompt again
});
Something went wrong with that request. Please try again.