From Ape Wiki

Jump to: navigation, search

Contents

[edit] Uni pipe and Multi pipe with APE JSF

Pipe is the communication system in APE. This tutorial show the basics of pipes in APE JSF :

  • Create a multi pipe.
  • Read a property from a multi pipe
  • Read a property from a uni pip
  • Create a uni pipe.
  • Send data to a uni pipe.

Before start this tutorial :

[edit] Create a class and connect to APE Server

First, create an HTML page with the following 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/apeClientJS.js"></script>
    </head>
    <body>
    </body>
</html>


1) We will create a JavaScript demoChat class and make this class inherit from APE.Client. In that way, our class will have all functionality of APE.Client. The constructor of our class will load APE Core and call the demoChat.initEvents that will intercept load & ready event from APE JSF

2) When the APE Core is loaded we will connect to APE Server using APE Core start() function and passing it a username (needed by libape-chat) 


//1) Create demoChat class and make it inherit from APE.Client
var demoChat = function () {
    //Load APE Core
    this.load();
    //call initEvents to handle events
    this.initEvents();
}
 
//Make demoChat class inherit from APE.Client
demoChat.prototype = new APE.Client;
 
demoChat.prototype.initEvents = function() {
    this.addEvent('load', this.clientLoad);//Call demoChat.clientLoad when the load event is fired
    this.addEvent('ready', this.clientReady); //Call demoChat.clientReady
}
 
//This function is called when the load event is fired
demoChat.prototype.clientLoad = function() {
    //2) Ask the user for a nickname, and connect to APE Server
    var nickname;
    while (!nickname) {
        nickname = prompt('Nickname?');
    }
    //Connect to APE Server and send user nickname
    this.core.start({'name':nickname});
}
 
//This function is called when the ready event is fired
demoChat.prototype.clientReady = function() {
    //This function is empty for now, we will fill it in the next part of this tutorial
}


MooTools users : APE JSF provides a special Client for MooTools to take advantage of MooTools Class. For more information read APE JSF with MooTools

[edit] Multi pipe

In this step of the tutorial we will join a channel, and then read and display properties from it.

A multi pipe is automatically created when you join a channel by using join() function of core. When you successfully joined a multi pipe the event multiPipeCreate is fired. In this event you will be able to get the pipe object and perform actions on it. See pipe documention and multi pipe documentation for more information.


3) Update function clientReady to make it join the channel 'testChannel'

4) Add to the function initEvents the interception of multiPipeCreate event

5) Output pipe name. You can acces to pipe properties trough pipe.properties.<property name>. For example if you want to read the property name use pipe.properties.name 

//3) Update function clientReady
demoChat.prototype.clientReady = function() {
    //When client is ready (connected to APE Server) we send a request to join the multi pipe 'testChannel'
    this.core.join('testChannel');
}
 
demoChat.prototype.initEvents = function() {
    this.addEvent('load', this.clientLoad);//Call demoChat.clientLoad when the load event is fired
    this.addEvent('ready', this.clientReady); //Call demoChat.clientReady
 
    //4) When multiPipeCreate event is received, call multiPipeCreate of our class
    this.addEvent('multiPipeCreate', this.multiPipeCreate);
}
 
//5) Output some information about the pipe
demoChat.prototype.multiPipeCreate = function(pipe, options) {
    console.log('You joined the multi pipe ' + pipe.properties.name, 'Pipe object :', pipe);
}

[edit] Uni pipe

In this step of the tutorial, we will catch userJoin event to know when new user come to a channel (this event is also fired when you join a channel for all user on this channel) then we will read properties from user then transform the user into a Uni Pipe and then send data on the pipe.

Why transform user into a pipe? In APE JSF users are standard javascript object for performance purpose. Imagine if you join a channel with 10 000 users, transforming 10k users object into a Pipe will take around 5sec! To transform user object into a pipe use getPipe. getPipe will return you a Uni Pipe and you will be able to perform actions on it. See pipe documention and FIXME uni pipe documentation for more information.

6) Add to the function initEvents the interception of userJoin and uniPipeCreate

7) Read name property of the user. Reading property for user work in the same way than reading property for pipe. For example if you want to read the property name use pipe.properties.name.

8) Open a confirm box to ask you if you want to send a message to the user and then what message do you want to send to him

9) Get the pipe object for the user with getPipe. The first time you call getPipe for a user, a new pipe will be created and the uniPipeCreate event will be fired.

10) Send the message on the pipe

11) Output some information when a new uni pipe is created. 

demoChat.prototype.initEvents = function() {
    this.addEvent('load', this.clientLoad);//Call demoChat.clientLoad when the load event is fired
    this.addEvent('ready', this.clientReady); //Call demoChat.clientReady
 
    //4) When multiPipeCreate event is received, call multiPipeCreate of our class
    this.addEvent('multiPipeCreate', this.multiPipeCreate);
 
    //6) When userJoin event is received call userJoin() of our class    
    this.addEvent('userJoin', this.userJoin);
 
    //6) When uniPipeCreate event is receveid call uniPipeCreate() of our class
    this.addEvent('uniPipeCreate', this.uniPipeCreate);
}
 
demoChat.prototype.userJoin = function(user, pipe) {     
    //7) Read name property
    var name = user.properties.name;             
    //8) Ask you if you want to send a message to the user.
    if (confirm('New user, ' + name + 'do you want to create a pipe and send a message to him?')) {
        //Ask you what message send to the user?
        var msg = prompt('Message to send : ?');
        if (msg) {
            //9) Transform the user into a pipe
            var userPipe = this.core.getPipe(user.pubid);
 
            //10) Send the message to the user pipe
            userPipe.send(msg);
        } 
    }
}
 
//11) Output some information when a new Uni Pipe is created.
demoChat.prototype.uniPipeCreate = function(pipe, options) {                                          
    console.log('New Uni Pipe', pipe.properties.name);                                                
}
Retrieved from "http://www.ape-project.org/wiki/index.php/Tutorial:Uni_pipe_and_Multi_pipe_with_APE_JSF"