ampersand-io
Provides a socket.io wrapper to be used with ampersand modules. Developed mainly to be used with ampersand-io-model and ampersand-io-collection
Install
npm install ampersand-io
API Reference
AmpersandIO.extend([attributes])
extend Supports the normal extend behavior (through usage of ampersand-class-extend).
Note that neither the events property nor the listeners property are extendable through this method.
IO.socket
socket Override this property to specify the socket that will be used when a new object reference is created. Useful for when you have a pre-existing socket connection that you would like to use. Defaults to an socket.io-client instance resulting from io.connect()
.
var io = ;var IO = AmpersandIO;
IO.events
events Overridable property containing a key-value reference to the events to be used by the socket conection. Useful for usage with the listeners
property and methods, as well as with the emit
emit.
events: eventOne: 'my-awesome-event' eventTwo: 'my-super-awesome-event'
It also supports the usage of arrays of different events tied to a single key.
events: eventArray: 'this-event' 'other-event'
IO.listeners
listeners Overridable property containing a set of listeners to be used by the socket connection. The key may be an entirely unreferenced event or one of properties from the events
property object. The fn
property contains the callback function to be called when the event is fired. The active
option is a Boolean that, if set to true, will set this listener to be initialized upon construction.
Note: this
property inside the fn
callback will be a reference to the whole ampersand-io instance, allowing you to access any property in your object, including the socket object.
events: myEvent: 'thisEvent' arrayOfEvents: 'event1' 'event2' listeners: myEvent: { console; console; //Will output: //events:{ // myEvent: 'thisEvent', // arrayOfEvents: ['event1', 'event2'] //} } arrayOfEvents: { console; } active: true //will be active when the object is created 'otherEvent': { console; }
new AmpersandIO([socket], [options])
constructor/initialize When creating an AmpersandIO
object, you may choose to pass in either a socket
object or a string to be used as a namespace for a new socket.io-client instance. If none of those are provided the AmpersandIO
instance will use the socket object defined in the class. Options support a listeners and events objects according to the ones mentioned above (note that these will override the class definitions) and also an initListeners
prop which, if passed true
, will set the class listeners active.
var IO = 'chat' events: receive: 'new-message' listeners: receive: { console; } active: true ;
IO.addListeners(listeners)
addListeners Add a set of listeners to the listeners property of the object. Pass a listeners
object as described above. If a listener by that name already exists and is currently active it should be removed first or else it will be ignored.
IO.setListeners([listeners])
setListeners Set the given listeners active. Accepts an array of strings containing the names of the events associated with the listeners. If no argument is provided the method will set all the listeners from the current object. Nothing done to listeners which are already active.
// sets the listeners associated with the receive and send eventsIO; // sets all the listeners in the IO objectIO;
IO.removeListeners([listeners])
removeListeners Sets the given listeners unactive. Accepts an array of strings containing the names of the events associated with the listeners. If no argument is provided the method will remove
all the listeners from the current object. Nothing done to listeners which are already unactive.
Note: the respective properties from the listeners property aren't deleted. The active
property is set to false
.
// removes the listeners associated with the receive and send eventsIO; // removes all the listeners in the IO objectIO;
IO.emit(event, data, [options], [callback])
emit Method responsible for emitting events. The event
name may be one of the events listed in the events property or other of your choice. The data sent to the socket connections will be an object {data: data, options: options}
containing the arguments passed to this function. Pass options.room
if you want to emit to a particular room and an options.callback
that will be also passed to the socket emit
method. You may choose to pass the callback
function directly as an argument (options.callback
will be ignored in this case).
IO;
credits
Created by @JGAntunes, with the support of @SINFO and based on a series of Ampersand Modules.
license
MIT