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.