Skip to content
Fetching contributors…
Cannot retrieve contributors at this time
175 lines (122 sloc) 7.24 KB

Configuration and load

A web application can configure the various implementations of the JavaScript API components used and URLs contacted for login, logout, and session preparation. If the application wishes to deviate from the default configuration, it must define a :data:`cowebConfig` object of its own before importing the coweb/main module. After loading that module, both the web application and the framework should consider the :data:`cowebConfig` read-only.

Bootstrapping a coweb application

As noted in :doc:`concepts`, the JavaScript portions of the |coweb api| follow the `Asynchronous Module Definition`_ and require an `AMD`_ loader. The rough steps needed to bootstrap a coweb application are the following:

  1. The application HTML page loads.
  2. The page includes a script tag that loads an AMD loader.
  3. The application uses the AMD loader to load the coweb/main module and any other dependencies it may have (e.g., cowebx widgets, its own modules, third-party libraries).
  4. The application initializes one or more :class:`CollabInterface` instances (e.g., one per cooperative widget) and subscribes for various notifications (e.g., session ready, coweb sync events).
  5. After the DOM load event, the application initializes the :class:`SessionInterface` singleton and uses it to prepare the session.
  6. When the :class:`SessionInterface` finishes preparing, joining, and updating, all :class:`CollabInterface.subscribeReady` callbacks fire.

Example application template

A template for a coweb application having a couple of cooperative widgets follows and a non-default admin URL follows. The application uses `RequireJS`_ as its AMD loader. It assumes all of its AMD resources reside under :file:`lib/` and its subfolders.

For a more complete example, revisit the tutorial about :doc:`/tutorial/shopping`.


<!DOCTYPE html>
    <meta charset="utf-8" />
    <title>My Cooperative Web Application</title>
    <script data-main="app-main" src="lib/require.js"></script>


RequireJS loads this script after it loads because of the data-main attribute on its script tag. It is relative to the page that included RequireJS, not the path in which RequireJS resides.

// e.g., server has admin in same path as application, not default /admin
var cowebConfig = {
   adminUrl : './admin'

], function(coweb, widget1, Widget2) {
   // instantiate the widget class
   var w = new Widget2('widget2');

   // wait for window onload
   require.ready(function() {
      // initialize the session instance
      var session = coweb.initSession();
      // do the session prepare
      session.prepare().then(function() {
         // prepare success, widget ready callbacks invoked after this
      }, function() {
         // prepare failure


This widget module has no public interface and is totally self-contained.

define(['coweb/main'], function(coweb) {
   // internal widget state
   var state = {};
   // widget CollabInterface instance
   var collab = coweb.initCollab({id : 'widget1'});

   collab.subscribeReady(function(info) {
      // called when the widget can start sending/receiving coweb events
   collab.subscribeStateRequest(function(token) {
      // called when a remote instance with the same id requests full state
      collab.sendStateResponse(state, token);
   collab.subscribeStateResponse(function(state) {
      // called when this instance receives a copy of the shared state from
      // a remote instance with the same id


This widget module defines a class which the importer must instantiate.

define(['coweb/main'], function(coweb) {
   var Widget = function(id) {
      // widget CollabInterface instance
      this.collab = coweb.initCollab({id : id});
      // subscribe methods for callbacks
      this.collab.subscribeReady(this, 'onReady');
      // subscribeStateRequest, subscribeStateResponse, etc. like widget1

   Widget.prototype.onReady = function() {
      // similar to widget #1

   // onStateRequest, onStateResponse, etc. like widget1

   // return the Widget class
   return Widget;
Jump to Line
Something went wrong with that request. Please try again.