Home IV. Client-side scripting

IV. Client-side scripting

a. Instantiation and initialization

Just like any client-server application, you need to connect to the server in order to utilize the services. But this time, you will connect it in JavaScript. First include the JsRS library to your html file. Put this line in your head section.

<head>
  […]
  <script language="JavaScript" type="text/javascript" src="/javascript/jsrs.js"></script>
</head>

Now you need to instantiate a socket object from the JsRS library. You can put this code right after the opening <body> tag or you can wrap it up within a function and call it later (onclick from a button).

<script language="JavaScript" type="text/javascript">
var socket = new Jsrs({
    "proxy" : "Proxy/proxy.php",
    "cf" : {
        "functionName" : function(client, param1, param2) {
            // Your remote function body here.
        }
    },
    "events" : {
        "onConnected" : function(newClient, clientId) {
            // When you’ve successfully connected.
        },
        "onDisconnected" : function() {
            // When you’ve disconnected unexpectedly.
        },
        "onClientConnected" : function(client) {
            // When a new client connected.
            // client["id"] will return you the ID.
        },
        "onClientDisconnected" : function(client) {
            // When a client disconnected.
            // client["id"] will return you the ID.
        }
    }
});
socket.connect();
</script>

The codes above will instantiate the socket object and initialize it with the proxy path, the event handler and the remote function or the common function.

The functions that stored in the "events" object is used to handle when a certain event is fired. For example the "onConnected" function will be called when the connection was successfully established. The parameters inside the event function is passed by the server. The first parameter (newClient) is a boolean value to determine whether you are a new client or not. Because in some case, a user might open few tab or window of a same browser. JsRS is able tell that they are the same client through their session’s ID or client’s ID (Depends on your application). The second parameter (clientId) is the ID of the client that connected to the server. It is like a IP address.

For functions that stored in "cf" is the remote functions. Those are the functions that able to call by other clients. For your understanding, those function inside "cf" is like an event. They must be call by other client in order to run the function.

 

b. Basic remote scripting

Before you calling a remote function, you must define it. You can define the remote function either during the initialization or runtime:
Initialization:

var socket = new Jsrs({
    "cf" : {
        "sayHello" : function(client, message) {
            alert(client["id"] + " has sent you a message: " + message);
        }
    }
});

Runtime:

socket.cf.sayHello = function(client, message) {
    alert(client["id"] + " has sent you a message: " + message);
};

Both are having the same result. Once you have defined the remote function, you can call it using the client remote calling function, "callCF".
Note: The first parameter is always the client’s (sender) object. The basic element is "id". You may get more info of the client through the "info" property. Eg: client["info"].

i. Client remote function

Calling a remote function is very simple. You have to specify the recipient’s ID and the function name.

socket.callCF(client, funcName, [[params], callback]);

The third and fourth parameters are optional. You must provide array for the first parameter even though there is only one recipient. Example:

socket.callCF([12], "sayHello", ["Hi there!"]);


Same goes to the function’s parameters, the third one. You must provide array even though it is only one parameter for the function. The acceptable parameter types are object, string, number and array.

The code above will call the remote client with the ID: 12 to invoke the remote function "sayHello" and passed the string "Hi there!" to the second parameter.

ii. Server remote function

Under certain circumstances, you might want to retrieve information from the server. Please refer to the Server’s APIs for more details. It is very similar to calling a client remote function:

socket.callSF(funcName, [[params], callback]);

 

You have to specify the function’s name that you want to call on the server. Example:

socket.callSF("plus", [10, 70], function(result) {
 alert("The result is: " + result);
});

The function "plus" is a test function from the server which take the parameters passed by you and do a summation. The returned result will be 80. If the message was successfully passed, you should received an alert message, "The result is 80".
Note: The function parameter has to be an array even though it’s only has one parameter.

 

c. Getting remote clients

Without the client’s ID, you can’t do any remote scripting. It is depend on what application you are writing and it will affect on how you store your client’s ID. I will explain how you going to get the client’s ID but I ain’t going to talk about how you store it.

There are two way you can get the connected clients: (1) Calling server functions, (2) Event functions.
Currently, there is one server function named: "getConnectedClients". This will return you a list of clients with their ID and info. With this, you can get the connected clients. Again, depends on your application on where you want to store them.

socket.callSF("getConnectedClients", function(clients) {
    for (var i in clients) {
        var client = clients[i];
        var clientId = client["id"];
        var clientInfo = client["info"];  // This is optional and might different depend on your application.
    }
});


The second way is the event. Through the event, you can get the newly connected client. Jsrs::events::onClientConnected allowed you to handle when there are new clients connected. With this, you can update the list of connected clients in your application (JavaScript). Of course, you might need to keep track of disconnected clients, Jsrs::events.onClientDisconnected allowed you to handle when there is a client disconnected from the server. Please refer to the API for more details.

 

d. Returning data from remote function

In section b. ii., you know how to get the result from the server’s function. You can do the same thing for client. Meaning you send a remote function call to a specific client and ask the client to process and send back the data. For example you wanted to know the client’s name. You might need to define the remote function first:

socket.cf.getName = function(client, sendResult) {
     var name = prompt(client["id"] + " is asking your name.", "");
    if (name) {
        sendResult(name);
    }
};

The remote function above will prompt the user (using prompt function) and get the input as the result (user’s name) and then send back to the sender using the sendResult function.

If you are defining a remote function that required a callback, the last parameter is always a function for you to send back your result. Don’t get confused, lets read on first.

Now you’ve defined the remote function, it is time to call it:

socket.sendCF([12], "getName", function(clientName, client) {
     alert("The client's name ("+ client["id"] +") is: " + clientName);
});

The first and second parameters are the client’s ID and the remote function’s name respectively. Because the remote function do not required any parameter, so we skipped it. The third parameter will be your callback function.

The callback function will be invoked once the recipient processed and return back the result using "sendResult" function. The execution context within the callback function is the Jsrs instance. Meaning this.proxy will return you the proxy URL.

 

e. Event handlers

Event handlers allowed you to catch any events happened. Below is the list of event handlers:

Event’s name Parameter(s) Description
onConnected i.) newClient - To check whether you are a new client or a existing client (open new tab or window).
ii.) clientId - Your connected client’s ID.
It is happened when you’ve successfully connected to the server.
onDisconnected N/A When you get disconnected from the server.
onClientConnected i.) client - The client’s object that connected to the server. It is happened only once when the client is newly connected to the server.
onClientDisconnected i.) client - The client’s object that disconnected from the server. It is happened when none of the client connection are connected to the server.
onExpired N/A When the client’s connection expired. This is to keep the heartbeat connection stay alive.
Last modified on Monday, 26 July 2010 20:23