Skip to content
This repository has been archived by the owner on Jan 7, 2019. It is now read-only.

API

Jump to bottom
Pablo Tejada edited this page Nov 16, 2013 · 49 revisions

Client

Client.channel

Client.user

Server

Server.channel

Server.user

Client

The client is the framework's main object. It is created with the APS( server, events, options) constructor. Note that only the first parameter is necessary the last two are optional and can be configured after initialization.

properties

  • user: before it is connected to the server this is a simple object with the current user's properties to be sent to the server when connecting the APE server. After it is connected it becomes a special user object. For more information about this user object take a look at The current user's special object.

  • session: a simple object for the current session.

    • getID(): get the current session ID
    • getFreq(): get the current frequency number
    • destroy(): function to clear all cookies related to sessions. Takes one parameter, if true keeps the frequency cookie.
    • set( key, value ): Save a value to the current user session
    • get( key ): Retrieve a value from the session

  • option: simple object with client options

    • debug: Boolean to toggle browser's console logging, default is false
    • session: Boolean to toggle the use of sessions, default is true
    • transport: a string specifying the transport to use or an array of transport, the default is ["ws","lp"]. With the default option the client would attempt to connect using websockets first and then long polling if it fails. All built-in transports are cross-domain compatible.
    • secure: a Boolean to toggle the use of a secure connection protocol https/wss, default is false
    • eventPush: Set this option to a script path where events will be routed/push to. For more info check the Routing Events for PHP processing.
    • addFrequency: a Boolean to toggle weather to add dynamic sub domains for session. Default value is true. Read Sessions with single domain - no wildcard subdomain
    • autoUpdate: a Boolean to toggle weather to auto update the user and channel objects with updated infomration recieved from the server. This option enables a lazy mechanism to update objects in the sense that updates only propagate to client with active users and channels.

methods

  • sub() - client.sub( channelName, events, callback)

    This method is use to subscribe to a channel and optionally add event listeners as well as a callback function.

    • channelName: a string, the channel name
    • events: an object of events to add to the channel. Ex: {join: function(){}, left: function()}
    • callback: this is basically a shortcut to add a joined event which runs after successfully subscribed to the channel

  • pub() - client.pub( channelName, data , sync, callback)

    This method is use to publish either a string, an array or simple object in channel.

    • channelName: a string, the channel name
    • data: a string, an array or simple object to publish in the channel
    • sync: a Boolean to toggle weather to synchronize the message across the user session or not
    • callback: a function that runs after the data is published

  • on() - client.on( eventName , event_handler)

    This method is use to add events in the client object. It also acts as the global event handler for all channels. For example: every channel receives the join event when a user joins a channel. If you add a join event handler to the client it will be triggered every time a user joins channel, any channel, existing and future ones.

    • eventName: a string, the name of the event
    • event_handler: the function/action of the event. The usual event arguments are apply to this function. [Arguments applied to event handlers](Event handlers)

    This method can also be use to add multiple events at once. In this case only the first argument is required client.on( events ). In this case events is an object of eventName and event_handler. Ex: {name1: handler1, name2: handler2}

  • trigger() - client.trigger( eventName , arguments )

    This method is use to trigger/fire the stack of an event. The events are triggered automatically by the framework so there is no need to trigger then manually. But even then it is included in this API just in case.

    • eventName: a string, the name of the event stack to trigger
    • arguments: is an array of arguments to be applied to the event_handler. Learn more about event handlers in Event handlers

  • reconnect() - client.reconnect()

    If some how you can detect the client lost connection with the server you can attempt to reconnect with this method. For example you can listen for the client dead event and attempt to reconnect every 5 seconds:

client.on("dead", function(){
    setTimeout(this.reconnect.bind(this), 5000);
})

  • getPipe() - client.getPipe( pubid )

    This function gets either a user or channel by its pubid. It returns false if an object witht the given pubid does not exists locally in the client.

  • getChannel() - client.getChannel( name )

    This function gets a channel object by its name. It returns false if the channel with the given name does not exists locally in the client.

  • onChannel() - client.onChannel( channelName, eventName, handler )

    This function adds an event handler to a channel, even if the channel has not been joined yet. Multiple event handlers can also be added by passing an object of events and handlers in the second parameter, {eventName: handler}.

    • channelName: a string, the name of the channel to add the event handler
    • eventName: a string, the name of the event handler
    • handler: the function to serve as the event handler, for arguments passed to event handlers refer to Events list

  • quit() - client.quit()

    This function kills the client and disconnects the user for good.

Client.channel

properties

  • users: the list/array of users subscribed in this channel.
  • name: the unique channel name (string).
  • pubid: the 32 characters long publisher id.

Any other defined public property can be directly access from the channel object

methods

  • pub() - channel.pub( data , sync, callback)

    This method is use to publish either a string, an array or simple object in the channel.

    • data: a string, an array or simple object to publish in the channel
    • sync: a Boolean to toggle weather to synchronize the message across the user session or not
    • callback: a function that runs after the data is published

  • send() - channel.send( event, data , sync, callback)

    This method is use to send custom events on the channel.

    • event: a string, the event name to send to the channel
    • data: a string, an string/array or simple object to send with the event
    • sync: a Boolean to toggle weather to synchronize the event across the user session or not
    • callback: a function that runs after the event has been sent

  • on() - channel.on( eventName , event_handler)

    This method is use to add events in the channel object.

    • eventName: a string, the name of the event
    • event_handler: the function/action of the event. The usual event arguments are applied to this function ( data, from, channel )

    This method can also be use to add multiple events at once. In this case only the first argument is required channel.on( events ). In this case events is an object of eventName and event_handler. Ex: {name1: handler1, name2: handler2}

  • trigger() - channel.trigger( eventName , arguments )

    This method is use to trigger/fire the stack of an event. The events are triggered automatically by the framework so there is no need to trigger then manually. But even then it is included in this API just in case.

    • eventName: a string, the name of the event stack to trigger
    • arguments: is an array of arguments to be applied to the event handler. By default ( data, from, channel ) are applied to channel's event handlers.

  • leave() - channel.leave()

    This function makes a user leave the the channel. Is an equivalent to client.unSub( channelName )

  • log() - channel.log( info )

    Logs information in the browser console, it is specify in the console from which channel the info was logged. info could be a string or object. The function is only useful for debugging purposes. The output of this function will be disabled with the the client.option.debug flag.

Client.user

This applies to all channels objects, the user object of the current user is a little different. For more information check The current user's special object

properties

Aside from the built-in properties below, the custom properties can also be directly accessed from the object.

  • channels: the list/array of channels the user is subscribe to.
  • pubid: the 32 characters long publisher id.

Note: that the custom name property is special and yet optional. If you want your user's to have unique username you should use the name property otherwise just use any other property such as nick or username for your users. Is worth mentioning that the server getUserByName depends on the name property

methods

  • pub() - user.pub( data , sync, callback)

    This method is use to publish either a string, an array or simple object directly to the corresponding user.

    • data: a string, an array or simple object to publish to the user
    • sync: a Boolean to toggle weather to synchronize the message across the user session or not
    • callback: a function that runs after the data is published

  • send() - user.send( event, data , sync, callback)

    This method is use to send custom events on the user.

    • event: a string, the event name to send to the user
    • data: a string, an string/array or simple object to send with the event
    • sync: a Boolean to toggle weather to synchronize the message across the user session or not
    • callback: a function that runs after the event has been sent

Server

The APE Server has a few useful built-in interfaces which are included weather you have the APS framework installed or not. A Sockets and a MySQL interface is available.

methods

All the methods below reside on a default Ape object in the server. Ape.{methodName}()

  • getUserByName() - Ape.getUserByName( userName )

    This method gets a user object by its user name. Note: users must connect to server with a name property in order to be added to index other wise the function wont work as expected.

    • userName: a string, a user's name

  • getUserByPubid() - Ape.getUserByPubid( pubid )

    This method gets a user object by its unique pubid( Publisher iD).

    • pubid: a string, a user's 32 character long pubid hash

  • getChannelByName() - Ape.getChannelByName( name )

    This method gets a channel object by its unique name.

    • name: a string, the channel name

  • getChannelByPubid() - Ape.getChannelByPubid( pubid )

    This method gets a channel object by its unique pubid( Publisher iD).

    • pubid: a string, a channels's 32 character long pubid hash

  • onChannel() - Ape.onChannel( channelName, eventName, handler )

    This function adds an event handler to a channel, even if the channel has not been created yet. Multiple event handlers can also be added by passing an object of events and handlers in the second parameter, {eventName: handler}. For more info and a list of the built-in events for channels in the server side check Handling Channel Events in the Server

    • channelName: a string, the name of the channel to add the event handler
    • eventName: a string, the name of the event handler
    • handler: the function to serve as the event handler, for arguments passed to event handlers refer to Events list

  • Request() - Ape.Request( method, url, params, responseHandler )

    Use this function to make an HTTP request. The function can either be instantiated with new or used directly from the namespace.

     	Ape.Request('GET', 'http://ptejada.com/robots.txt', params, responseHandler );

 	//OR

 	var page = new Ape.Request('GET', 'http://ptejada.com/robots.txt');
 	page.addParam( key, value);
 	page.addParam( params );
 	page.getResponse( responseHandler );

    For the list of documented methods for a Ape.Request instance refer to Code Reference

    • method: a string, either POST or GET
    • url: a string, the url to make the request to
    • params: a object, a keypair values of GET|POST parameters to send with the request
    • responseHandler: a function, callback to handle the request response. Three parameter are passed to the callback: function(responseBody, responseStatusCode, responseHeaders)

    If no params need to be sent you can passed the handler instead so the call would be Ape.Request( method, url, responseHandler ).

  • GetRequest() - Ape.GetRequest( url, params, responseHandler )

    This method is an alias for Ape.Request('GET', ...), refer to Ape.Request() for more info.

  • PostRequest() - Ape.PostRequest( url, params, responseHandler )

    This method is an alias for Ape.Request('POST', ...), refer to Ape.Request() for more info.

Server.channel

properties

The channel object does not has many directly accessible properties. Properties directly added to the channel object are consider to be private properties because they don't get distributed to clients, only the server is aware of this properties and their value.

  • users: the list/array of users subscribed to the channel, indexed by user pubid.
  • pipe: the channel pipe object.

methods

  • prop() - channel.prop( propertyName , value)

    Use to write and read public properties to a channel object. Public properties are distributed along with the channel object.

    • channel.prop("title", "Hello World") sets the channel's title public property to Hello World
    • channel.prop("title") gets/reads the channel's title public property value, returns false if not defined
    • channel.prop() returns an array of all the channel's public properties

  • update() - channel.update( propertyName , value)

    Adds or updates a channel's public property and broadcast it to all its users. For info on listening for properties updates events on the client side refer to the Event Lists | channelUpdate

    • propertyName: a string, property name to add/update
    • value: any data, the new property value

    You can also update multiple properties at once by passing an object of { propertyName: value } in the first parameter.

  • sendEvent() - channel.sendEvent( eventName , eventData, options)

    This method sends an event to all users in the channel.

    • eventName: a string, name of the event to send
    • eventData: data to send with the event. Could be an integer, string, object or array
    • options: an object with two properties: {from:.., restrict:..}.
      • from: An user.pipe reference that will be added in the from field, the event will not be sent to this user.
      • restrict: A user which will not receive the event.

Server.user

properties

The user object does not has many directly accessible properties. Properties directly added to the user object are consider to be private properties because they don't get distributed to clients, only the server is aware of this properties.

  • channels: the list/array of channels the user is subscribe to, indexed by the channel name.
  • pipe: the channel pipe object.

methods

  • prop() - user.prop( propertyName , value)

    Use to write and read public properties to a user object. Public properties are distributed along with the user object.

    • user.prop("name", "Pablo") sets the user's name public property to Pablo
    • user.prop("name") gets/reads the user's name public property value, returns false if not defined
    • user.prop() returns an array of all the user's public properties

  • update() - user.update( propertyName , value)

    Adds or updates a user's public property and broadcast it to all its channels. For info on listening for properties updates events for users on the client side refer to the Event Lists | userUpdate

    • propertyName: a string, property name to add/update
    • value: any data, the new property value

    You can also update multiple properties at once by passing an object of { propertyName: value } in the first parameter.

  • join() - user.join( channelName )

    Joins the user to the specify channel

    • channelName: a string, the name of the channel to join

  • left() - user.left( channelName )

    Makes the user leave the specify channel

    • channelName: a string, the name of the channel to leave

  • sendEvent() - user.sendEvent( eventName , eventData, options)

    This method sends an event to the user. If sessions are being used and the user connected from different points (browsers, or browser's tabs) the event will be send to all ends. To send an event to a single end check subuser.sendEvent

    • eventName: a string, name of the event to send
    • eventData: data to send with the event. Could be an integer, string, object or array
    • options: an object with two properties: {from:.., restrict:..}.
      • from: An user.pipe reference that will be added in the from field, the event will not be sent to this user.
      • restrict: A subuser which will not receive the event.
Clone this wiki locally