Installation and integration

Quickstart

The JavaScript client implementation is shipped with the django module. After you’ve installed the django-omnibus according the documentation you are able to insert the script as followed

{% load static %}
<script type="text/javascript" src="{% static 'omnibus/omnibus.min.js' %}"></script>

All JavaScript sources are available as non-minified or minified version. The minified scripts uses .min.js as extension.

django-omnibus gives you the possibility to use them as an AMD module to use with RequireJS or as CommonJS-like environments that support module.exports such as browserify.

Dependencies

The client library is dependency free. When you want to support older Browsers which don’t support WebSockets and/or JSON by default, embed the following libraries. These are also shipped with the django-omnibus module:

SockJS

SockJS can be used as alternative transport implementation. It delivers the same API as the browsers standard Web Websockets.

<script type="text/javascript" src="{% static 'omnibus/sockjs.min.js' %}"></script>

or get the latest version from SockJS via GitHub

JSON2

JSON2 implements the functions JSON.parse and JSON.stringify for browsers without the standard JSON API.

<script type="text/javascript" src="{% static 'omnibus/json2.min.js' %}"></script>

or get the latest version from JSON2 via GitHub

Setup

After inserting the django-omnibus JavaScript library as described above, you can follow these steps to setup a connection

// Select a transport implementation:
var transport = WebSocket; // SockJS can be used alternatively

// Receive the path for the connection from the django template context:
var endpoint = '{{ OMNIBUS_ENDPOINT }}';

// Define connection options:
var options = {
    // Get the omnibus authentication token:
    authToken: '{{ OMNIBUS_AUTH_TOKEN }}'
};

// Create a new connection using transport, endpoint and options
var connection = new Omnibus(transport, endpoint, options);

After you’ve created an instance, it will automatically open a connection and identify itself through them. For more informations about the connection instance visit the usage site.

The communication between client and server takes place through a channel. You can easily open a channel instance and send a ping using the following lines of code

var channel = connection.openChannel('ping-channel');
channel.send('ping-event', {
    message: 'hello world'
});

For more information about the use of a channel instance take a look at the usage site or visit the examples.