jQuery Integration

Overview

The modular approach to the jQuery framework allows the creation of powerful and dynamic web pages and web applications, because of it's architecture, other developers can use its constructs to create plug-in code to extend its functionalities. Currently there are thousands of jQuery plug-ins available but there was not a jWebSocket plug-in available. In this tutorial the user will see how was created jWebSocket jQuery PlugIn, also will be explained a basic example that the user will be able to reproduce when reading all this document.

Why jQuery?
jQuery is a well written cross-browser JavaScript library designed to simplify the client

side scripting of HTML. It is used by over 43% of the 10,000 most visited websites, jQuery is the most popular JavaScript library in use today.

What is jWebSocket jQuery Plug-in?

jWebSocket jQuery Plug-in is a simple library that is aimed to embed all the logic of the WebSocket communication using a simple wrapping structure for our jWebSocket Token Client within a jQuery namespace ($.jws).

The first prototype of the jWebSocket Plug-in for jQuery was created since 2010, since the beginning both libraries were supported by this plug-in, jQuery and jQueryMobile, for them many example apps were created, right now jWebSocket has most of the demos using this Plug-in for its flexibility and it's simple structure, (see Figure 1).


Figure 1: jWebSocketJQueryPlugIn-1.0 Class Diagram
As this Plug-in only depends on jQuery library, it can be used in both, jQuery or jQueryMobile, depending on the WebSockets support within the mobile or the stationary client browsers.
The API
The PlugIn is accessible from the namespace ($.jws)
Implementation of the jWebSocketTokenClient class inside Query framework.

+ $.jws.open(aURL, aTokenClient, aTimeout)

Description: Opens the jWebSocket connection and fires the corresponding events. If the browser doesn't support WebSocket and no other fallback mechanism is established then an exception is fired "WebSocket not supported".
Arguments:
  • aURL (String): The server URL. This field is optional.
  • aTokenClient (jWebSocketTokenClient): Any TokenClient (JSON, XML, CSV) already instantiated. This field is optional, by default will be created a jWebSocketJSONClient.
  • aTimeout (Integer): The timeout number in miliseconds to wait for the server response when opening the connection. This field is optional.
Returns: void

Examples:

// The simplest way takes the url automatically from your localhost or ip number
$.jws.open();

If you want to define jWebSocket JavaScript Client (jws.jWebSocketBaseClient)
//creating a jWebSocket JSON Client
var lTokenClient = new jws.jWebSocketJSONClient();
$.jws.open($.jws.getAutoServerURL(), lTokenClient);

// Or you can also use the url that you like
var lMyServerURL = "ws://jwebsocket.org/jWebSocket/jWebSocket";
$.jws.open(lMyServerURL);
Events: 
After the connection opens the following events will be triggered within the namespace $.jws:
  • open: Fired when the connection is opened.
  • timeout: Fired when the connection takes too long and exceeds the specified timeout.
  • close: Fired when the server closes the connection or the client forces to close it.
  • welcome: Fired when a new user is connected to jWebSocket Server, the welcome event brings a token with all the data from the user and the jWebSocket System.
  • message: Fired whenever a new message comes from the server to the client.
  • logon: Fired when the user is correctly authenticated into the jWebSocket Server.
  • logoff: Fired when the user is deauthenticated with the server.

How to listen to these events before opening the connection:

// In case that we want to listen to some events
$.jws.bind({
     open: function(){
        console.log("connection opened");
     },
     welcome: function(aWelcomeToken){
        console.log(aWelcomeToken);
     },
     logon: function(){
        console.log("Logged on jWebSocket Server");
     },
     logoff: function(){
        console.log("logged off");
     },
     close: function(){
        console.log("Connection closed");
     }
});
$.jws.open();


+ $.jws.send(aNs, aType, aArgs, aCallbacks, aOptions)

Description: Allows sending data to an specified jWebSocket server application or PlugIn.
Arguments: 
  • aNS:String: The namespace of the application in the server that will process the message, required.
  • aType:String: The token type to be sent to the server with which it will process the message, required.
  • aArgs:Object: The parameters of the request, not required.
  • aCallbacks:Object: An object with the functions (success, failure, timeout) to be executed if the server responds, not required.
  • aOptions:Object: The jWebSocket default send options, not required.
  •  
Returns: void

Examples:
// Chat application
var lMessage = $('.someselector').val(),
lNS = "org.jwebsocket.plugins.chat",
lTokenType = "broadcast",

lData = {
    message: lMessage,
    date: new Date().toString()
},
lCallbacks: {
    success: function(aToken){
        console.log(aToken); // the success token
        console.log("Success received from the server");
    },
    failure: function(aToken){
        console.log(aToken); // the failure token
        console.log("Success received from the server");
    },
    timeout: function(){
        console.log("timeout catched");
    }
}

$.jws.send(lNS, lTokenType, lData, lCallbacks)
 

+ $.jws.close()

Description: Closes the connection with the server, fire the event "close" within the $.jws namespace.
Arguments: none
Returns: void

 

- $.jws.processToken()

Description: Private method that is executed when the connection is opened, this gives to jQuery PlugIn an special event handling structure for the WebSocket messages. Whenever a new message comes from jWebSocket server it always brings a Namespace and a Token type. If we put together this namespace and this token type we would get something like "org.jwebsocket.plugins.system" : "logon". So, we realized that if we fire an event whenever a new message comes from jWebSocket Server with the namespace and the tokentype it would be much better to manage the incoming messages within the application.
Note: This method can't be used directly, it is automatically executed by the open method.
Arguments: none
Returns: void
Events & Examples: 
For every incoming token from the server will be fired 4 events in the $.jws Namespace with the following structure:
  • 'all:all'
  • 'all:' + aToken.type
  • aToken.ns + ':all'
  • aToken.ns + ':' + aToken.type

So it will be very easy for the user when we are working in our application to listen for an specific message from an specific namespace with just one line of code:

$.jws.bind('org.jwebsocket.plugins.chat:all', function(aToken){
      // Here we are listening all the messages incoming
      // for the chat application
});


$.jws.bind('org.jwebsocket.plugins.chat:broadcast', function(aToken){
      // Here we are listening a broadcast message
});

$.jws.bind('all:all', function(aToken){
      // Here we are listening all incoming messages from the server side
});
$.jws.bind('all:broadcast', function(aToken){
      // Here we bind all the messages from all namespaces
      // that has a token type "broadcast"
});

$.jws.getConnection()

Description: Can be used to access directly to the jWebSocket Token Client, this one represents the low level connection to jWebSocket Server.
Arguments: none
Returns: jWebSocketTokenClient

$.jws.isConnected()

Description: Used to check if the connection is still alive with the server.
Arguments: none
Returns: Boolean,
the result state of the connection.

$.jws.addPlugIn(aPlugIn)
Description: Adds an object with a processToken method to the jWebSocket Client PlugIn chain, whenever a new message comes will be automatically passed to the processToken method of the added PlugIns.
Arguments:

  • aPlugIn (Object): The object passed should contain a processToken method, otherwise an error is thrown. 

Returns: void

Examples:

var lPlugIn = {
     processToken: function(aToken){
         // will be executed whenever a new message 
         // comes from the server
         console.log(aToken);
     }
}
$.jws.addPlugIn(lPlugIn);
How to use the PlugIn

1- Go to the download 

download section of jWebSocket, make sure that you click in the green button:
 "download" of the client section which will always point your download to the latest client side release from jWebSocket.

2- From the downloaded package jWebSocketClient-<version>-<build>.zip you will need the extract it somewhere and take the required files from it:

- jWebSocketClient-1.0/
         res/js/jWebSocket.js

         lib/jQuery/jquery.js

         lib/jQuery/jws-plugin-1.0.js

3- Include the dependencies in your main HTML:

<!-- JQUERY DEPENDENCIES -->
<script type="text/javascript" src='../../lib/jQuery/jquery.js'></script>

<!-- JWEBSOCKET JAVASCRIPT CLIENT LIBRARIES -->
<script type="text/javascript" src="../../res/js/jWebSocket.js"></script>

<!-- THE PLUGIN DEPENDENCIES -->
<script type="text/javascript" src="../../lib/jQuery/jws-plugin-1.0.js"></script>

Examples videos coming soon...

Conclussions

With the creation of this jQuery and jQueryMobile PlugIn for jWebSocket we provide to the jQuery and jWebSocket communities a reusable and simple structure, easy to learn and adaptable to any platform or browser giving a complete communication infrastructure for creating real time WebSocket applications under jQuery.

 

Copyright © 2013 Innotrade GmbH. All rights reserved.