Hello world

In this tutorial you will discover how to connect a client to an APE Server and send data to a channel. This tutorial cover all the basics of client/server interaction.

Before starting this tutorial

Make sure your APE Server and Client are setup and working properly.
You should read APE Server Core and JSF General overview to learn how APE and APE JSF works before continue.
If you use Firefox, please install firebug. For other browsers, find out where your browser displays console log messages. Opera does not know the console-object.
If you want to use APE you must have some HTML and javascript knowledge.

Initializing APE Client

The first thing to do is create an HTML page with the file needed for the client and instantiate the client. In this tutorial we will use the javascript client.

Note : The Mootools client work in the same way as the javascript client.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" dir="ltr" lang="en">
    <head>  
        <!-- Load APE Client -->
        <script type="text/javaScript" src="Build/uncompressed/apeClientJS.js"></script>
    </head>
 
    <body>
        <script type="text/javaScript">
            //Instantiate APE Client
            var client = new APE.Client();
        </script>
    </body>
</html>

You will have to configure a few things in Build/uncompressed/apeClientJS.js :

/***
 * APE JSF Setup
 */
APE.Config.baseUrl = 'http://yourdomain.com/APE_JSF/'; //APE JSF 
APE.Config.domain = 'auto'; 
APE.Config.server = 'ape.yourdomain.com'; //APE server URL

Connect to APE server

Before connecting to the APE server, you must call the load() function on the Client. This function creates an iframe and loads the APE Core inside it.
Client and Core communicate through an event system. Once the Core is loaded, the load event is fired. You can intercept Core events from the client using addEvent(), to associate a callback function to an event.
Once the Core is Loaded, the core variable is set in the client, this variable is a reference to the APE Core. The first function you must call is start() . This function sends a "login" request to the APE server.
The last step is to listen for the ready event which is fired once the Client is connected to APE Server.
Add the following code to your page :

//Instantiate APE Client
var client = new APE.Client();
 
//1) Load APE Core
client.load();
 
//2) Intercept 'load' event. This event is fired when the Core is loaded and ready to connect to APE Server
client.addEvent('load', function() {
    //3) Call core start function to connect to APE Server, and prompt the user for a nickname
    client.core.start({"name": prompt('Your name?')});
});
 
//4) Listen to the ready event to know when your client is connected
client.addEvent('ready', function() {
    console.log('Your client is now connected');
});

Hello World!

Now your client is connected and you can send requests to the APE Server. You have access to all Core function.

The first thing we are going to do is to join a channel in order to be able to receive and send data from/to it. To join a channel use the join() function of core. Remember to put this in the ready-handler.
The event multiPipeCreate is fired when you successfully join a channel and are ready to send/receive data on/from it. Three arguments are passed to the callback function :
- A pipe object. A pipe object allow you to perform some operation on a pipe : sending data, receiving data, listen for event, ...
- Options of the pipe FIXME.
Then send a message to the channel (Multi pipe) by using the pipe's send() function. The send function triggers a 'SEND' command. The 'SEND' command is used to send messages to multi or uni pipes. The message will be send to all users on the pipe. Note : you don't receive messages, you send them!
When you receive a message a raw event is fired. A raw event is an event fired each time you receive data from the server. Raw events can be intercepted with the onRaw function. The raw corresponding to the reception of a message is the raw 'DATA'

//1) join 'testChannel'
client.core.join('testChannel');
 
//2) Intercept pipeCreate event
client.addEvent('multiPipeCreate', function(pipe, options) {
    //3) Send the message on the pipe
    pipe.send('Hello world!');
    console.log('Sending Hello world');
});
 
//4) Intercept the reception of new message.
client.onRaw('data', function(raw, pipe) {
    console.log('Receiving : ' + unescape(raw.data.msg));
});

To fully test this sample, open the page you've created in two different browser pages or tabs. When the second page is loaded you'll see this message in the console log of the first window : "Hello world!"

Complete source code

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" dir="ltr" lang="en">
    <head>  
        <!-- Load APE Client -->
        <script type="text/javaScript" src="Build/uncompressed/apeClientJS.js"></script>
    </head>
 
    <body>
        <script type="text/javaScript">
            //Instantiate APE Client
            var client = new APE.Client();
 
            //Load APE Core
            client.load();
 
            //Intercept 'load' event. This event is fired when the Core is loaded and ready to connect to APE Server
            client.addEvent('load', function() {
                //Call core start function to connect to APE Server
                client.core.start({"name":prompt('Your name?')});
            });
 
            //4) Listen to the ready event to know when your client is connected
            client.addEvent('ready', function() {
                console.log('Your client is now connected');
                //1) join 'testChannel'
                client.core.join('testChannel');
 
                //2) Intercept multiPipeCreate event
                client.addEvent('multiPipeCreate', function(pipe, options) {
                //3) Send the message on the pipe
                pipe.send('Hello world!');
                    console.log('Sending Hello world');
                });
 
                //4) Intercept the reception of new message.
                client.onRaw('data', function(raw, pipe) {
                    console.log('Receiving : ' + unescape(raw.data.msg));
                });
            });
        </script>
    </body>
</html>

Provide feedback

Saved searches