Handling Channel Events in the Server

As of version 1.5.6 the server side scripts now implements an interface that will allow you to listen to events for channels. This is a very powerful implementation as it lets you manipulate and validate the data of an event prior to the propagation thus changes made in these event handlers will be reflected in the response that clients will received.

Adding channel event handlers

To add event handler you would use Ape.onChannel( channelName, eventName, handler). Consider the example below

Ape.onChannel("music","message", function(params, user, channel){
	params.data += " [ok]"
})

The above example will prepend the string [ok] to all messages sent in the music channel. Multiple event handlers can also be added once:

Ape.onChannel("music",{
	message: function(params, user, channel){
		...
	},
	data: function(params, user, channel){
		...
	}
	...
)

Note: To all client sent events three parameters are passed to the event handler/function function(params, user, channel). The first, params, is an object that holds the event parameters as sent by the client. params.data will hold the data of the event, for example in case of the message event it will be a string and in case of the data event an object. The second, user, is the object of the user who sent the event. The third, channel, is the object of the channel in which the event was sent.

Internal Events

Internal events are events triggered in the server automatically without having a client sending it. The parameters passed to this events varies, below is the list of the these events and their parameters:

• create: The event is triggered when the channel is created. This is useful if you want to add default properties to channels. function( channel )

• destroy: The event is triggered when the channel is deleted from the server, a channel is deleted from the server when it has no users/subscribers. function( channel )

• beforeJoin: The event is triggered right before a user joins the channel. If the event handler returns false the user wont be subscribed to the channel and a notJoined event will be triggered in the client. function( params, info )

  • params:
    • channels: an array of channel names attempting to join, usually just one.
  • info:
    • user: object of user attempting to join channel
    • subuser:

  The params object is sent with the notJoined event so if declining a user to join a channel you can add extra information to the params object and be able to use in the client side with an event handler for the notJoined event.

• restored: The event is triggered when a user is been restored back in the channel from a session. Sometimes the user might not be on the page where he joined the channel and return to that page before the left event is triggered, this is when this event comes in handy allowing you yo handle this scenarios. function( user, channel )

• join: The event is triggered when a user joins the channel. function( user, channel )

• left: The event is triggered when a user leaves the channel. function( user, channel )

Example:

Ape.onChannel("music",{
	create: function(channel){
		Ape.log("The channel " + channel.prop("name") + " has been created.");
	},
	destroy: function(channel){
		Ape.log("The channel " + channel.prop("name") + " has been deleted.");
	}
	join: function(user, channel){
		Ape.log("The user " + user.prop("name") + " joined the " + channel.prop("name") + " channel.");
	},
	left: function(user, channel){
		Ape.log("The user " + user.prop("name") + " left the " + channel.prop("name") + " channel.");
	}
)

Global channel events

Global events can also be added to channels, this events will be triggered for all channels. To add a global channel event just use the special character * as the channel name on the Ape.onChannel() call.

Ape.onChannel("*",{
	create: function(channel){
		Ape.log("The channel " + channel.prop("name") + " has been created.");
	},
	destroy: function(channel){
		Ape.log("The channel " + channel.prop("name") + " has been deleted.");
	}
	join: function(user, channel){
		Ape.log("The user " + user.prop("name") + " joined the " + channel.prop("name") + " channel.");
	},
	left: function(user, channel){
		Ape.log("The user " + user.prop("name") + " left the " + channel.prop("name") + " channel.");
	}
)

The events above will be triggered for all channels.