Events list

There are a handful of built-in events in the framework. Some more useful and advance then others. This built-in commands should not be manually sent as it might brake the framework workflow. Below is a list of the events.

client: connect | ready | restored | user*Update | channel*Update | notJoined | error* | dead | quit

channel: joined | join | left | message | data

client.user: This is the the user object of the current user, it is a hybrid object that acts more like a channel. The channel's message and data events also apply to this object. To learn more about this special object check The current user's special object

---

client

• connect:

  This event is triggered right before the client sends the command to connect to the APE Server along with the user information/object client.user. This event is probably the must powerful and useful in the whole framework, it makes use of the smart trigger by holding the connect process when returned false.

  Take a look at this example where the connect event is used to get the user's name prior to connecting to the server without breaking your application workflow:

   //Create new client object
   var client = new APS("localhost:6969");
   
   //Adds the `connect` event to the client
   client.on("connect", function(){
   	//Check if the user's name is known
   	if(!!client.user.name){
   		//Simply ask for the user name
   		client.user.name = prompt("Which nick name would you like?", "Pablo");
   	}
   	//the framework continues connecting
   })
   
   //Subscribes to the channel `chat`
   client.sub("chat");

  Below is a more advance and useful example. It uses jQuery to make an ajax request to get the user's info without breaking the workflow of your application still:

   //Create new client object
   var client = new APS("localhost:6969");
   
   //Adds the `connect` event to the client
   client.on("connect", function(){
   	//Check if the user's name is known
   	if(!!client.user.name){
   		//Ajax call to get the user info
   		$.getJSON("script_to_get_user_info.php", function(data){
   			client.user = data.user;
   			//Resumes the connecting process
   			client.connect();
   		});
   		
   		//Holds the connecting process
   		return false;
   	}
   	//We have a name, continue connecting to the APE server
   })
   
   //Subscribes to the channel `chat`
   client.sub("chat");

  Please note that the client.connect() will re-trigger the connect events so if your ajax callback function does not sets a value to client.user.name you might create a infinity loop in this specific example.

• ready:

  When this event is triggered the client object has been completely initiated and connected to the APE Server. No parameter are passed to this event.

• restored:

  this event is triggered when the client has been completely restored from a session. When the client is restored from a session the connect event is never triggered. No parameters are passed to this event.

• userUpdate: function( propertyName, newValue, user)

  this event is triggered every time a user's property has been updated. The following parameters are passed to this event function( propertyName, newValue, user)

  You can listen for a property specific event, user{propertyName}Update. For example to listen for changes of user's status property, assuming your application adds the custom status property, you would add an event listener to the userStatusUpdate. I this case the following parameters are passed to the handler function( newValue, user )

• channelUpdate: function( propertyName, newValue, channel)

  this event is triggered every time a channel's property has been updated. The following parameters are passed to this event function( propertyName, newValue, channel)

  You can listen for a property specific event, channel{propertyName}Update. For example to listen for changes of channel's status property, assuming your application adds the custom status property, you would add an event listener to the channelStatusUpdate. In this case the following parameters are passed to the handler function( newValue, channel )

• notJoined: function( params )

  this event is triggered when a user attempts to subscribe to a channel without success. The event is sent to the client after a beforeJoin server channel event handler returns false. The following parameters are passed to the handler function( params ) where params are the arguments sent to subscribe to a channel.

• error: function( errorCode, errorTitle )

  this event is triggered when an error is explicitly sent from the server. The error code and name are passed as parameter to this event. You can also add an error event for an specific error code, for example to add event for the error code 007 you would add the event error007. For a full list of error codes check Error codes. The following parameters are passed to the handler function( errorCode, errorTitle )

• dead:

  This event is triggered when the client can no longer communicate with the APE Server. No parameters are passed to this events.

• quit:

  This event is triggered when the client is intentionally disconnected using the client.quit() function.

channel:

There are two ways you could add events to a channel. Directly from an existing channel object channel.on() or at any time from the client object using client.onChannel(). Remember that channel's events are triggered in a per channel basis. If you want to add a global event for all channels you have to add the channel event to the client object. For example if you add a joined event to client it will be triggered every time the current user joins any channel.

• joined: function( user, channel )

  triggered when the current user successfully joins the channel. It can been seen as the sub() method's callback function. The following parameters are passed to the handler function( user, channel )

• join: function( user, channel )

  Not to be confused with joined, this event is triggered when other users join the channel. The following parameters are passed to the handler function( user, channel )

• left: function( user, channel )

  This event is triggered when a user has left the channel. The following parameters are passed to the handler function( user, channel )

• message: function( message, user, channel )

  This event is triggered when a message is received in the channel. The event is sent when a string has been publish via the .pub() method. The following parameters are passed function( message, user, channel )

• data: function( data, user, channel )

  This event is triggered when an object/array is received in the channel. The event is sent when an object/array has been publish via the .pub() method. The following parameters are passed function( data, user, channel )