ActionheroWebsocketClient

ActionHero. ActionheroWebsocketClient

new ActionheroWebsocketClient()

Source:
Tutorials:
  • Tutorial: websocket

Create a new Websocket ActionHero Client. This is for use in the browser. We use the Primus library to abstract our websocket connections, and to allow you to create connections that gracefully fall back to long-polling and other methods to support older browsers if needed. There are clients for other languages/client types as well, but this is to be the prototypical example. Note that this class is not written using ES6 convestions so that it will function properly in the browser. Defaults will be built from the options you set in api.config.servers.websocket

Example
// <script type="text/javascript" src="/public/javascript/ActionheroWebsocketClient.min.js"></script>

var client = new ActionheroWebsocketClient();

client.on('connected',    function(){ console.log('connected!') })
client.on('disconnected', function(){ console.log('disconnected :(') })
client.on('error',        function(error){ console.log('error', error.stack) })
client.on('reconnect',    function(){ console.log('reconnect') })
client.on('reconnecting', function(){ console.log('reconnecting') })

client.on('welcome',      function(message){ alert(message); }) // server welcome message
client.on('say',          function(message){ alert(message); }) // say messages from rooms client is in
client.on('message',      function(message){ alert(message); }) // all messages (noisy)

client.connect(function(error, details){
  if(error){ return console.warn(error) }
  client.action('createChatRoom', {name: 'defaultRoom'}, function(){
    client.roomAdd("defaultRoom");
  });
});

Methods

(static) action(action, params, callback)

Source:

Call an action from this client. As a note, if you are not connected yet (via client.connect()), the action will still be attempted, over XHR/JSONp. That means that you can use this same client libarary for simple AJAX clients if you wish.

Example
client.on('error', function(error) { alert(error) })

// no params
client.action('cacheTest', function (data) {
  if (data.error) { alert(data.error) }
})

// with params
client.action('cacheTest', {key: 'key', value: 'value'}, function (data) {
  if (data.error) { alert(data.error) }
})
Parameters:
Name Type Description
action string

The name of the action to run.

params Object

(optional) (default: {}). Any params to pass to the action.

callback function

Will reurn (data) (no error!). The client will emit error if there is a connection error, otherwise any errors from the action will be contained within data.error.

(static) configure(callback)

Source:
See:

Will set this.state, this.rooms, this.fingerprint, and this.id. You should only need this method if you are having connection errors.

Parameters:
Name Type Description
callback function

Will reurn (error, details), where details is the same as calling client.detailsView().

(static) connect(callback)

Source:
See:

Connect to the ActionHero server. Will emit welcome when connected, and return the callback. Will aslo set this.state, this.rooms, this.fingerprint, and this.id. Clients will automatically try to reconect, unless prevented with client.disconnect()

Parameters:
Name Type Description
callback function

When the connection is connected, will reurn (error, details), where details is the same as calling client.detailsView().

(static) detailsView(callback)

Source:

View the server's details about this connection.

Parameters:
Name Type Description
callback function

Will reurn (data), where data contains the connections details (fingerprint, connection time, etc)

(static) disconnect(callback)

Source:
See:

Close the client connection. Will prevent any re-connects from attempting.

Parameters:
Name Type Description
callback function

(static) documentation(callback)

Source:

View details of this server's actions.

Parameters:
Name Type Description
callback function

Will reurn (data), where data conatins the results of api.documentation.documentation, details of all documented actions on the server.

(static) file(file, callback)

Source:

Request a public file from the server.

Example
client.file('/public/simple.html', function(data) {
  data = {
    content: "<h1>ActionHero</h1> I am a flat file being served to you via the API from ./public/simple.html<br />",
    context: "response",
    error: null,
    length: 101,
    messageCount: 3,
    mime: "text/html"
  }
})
Parameters:
Name Type Description
file string

The file requeted. The file should look like a the path from a browser, ie: /public/name/of/file.jpg

callback function

Will reurn (data), where the file's contents and medadata will be included. Likley a large payload.

(static) roomAdd(room, callback)

Source:
See:

Join an existing chat room. You may not be able to join this room (based on connection properties or other configuration on the server, so check for data.error). Once in the room, you will recive all say messages from the room as events.

Parameters:
Name Type Description
room string

The room to join.

callback function

Will reurn (data), where data contains errors and success.

(static) roomLeave(room, callback)

Source:
See:
  • ActionHero.ActionheroWebsocketClient.roomAddd

LEave a chat room you are already a member of. You may not be able to leave this room (based on connection properties or other configuration on the server, so check for data.error)

Parameters:
Name Type Description
room string

The room to leave.

callback function

Will reurn (data), where data contains errors and success.

(static) roomView(room, callback)

Source:
See:

View the other members of a room.

Parameters:
Name Type Description
room string

The room to inspect. Client must be a member of room already via client.roomAdd()

callback function

Will reurn (data), where data contains a list of other members in the room.

(static) say(room, message, callback)

Source:
See:

Say a message to a chatRoom the connection is a member of.

Parameters:
Name Type Description
room string

The room to chat in. Client must be a member of room already via client.roomAdd()

message Object | string

The message to send. Can be a string, Object, or Array.

callback function

Will reurn (data), where data.OK will exist.