Class: wsUtil

wsUtil

Server side websocket utility extension library for Enonic XP

Version:
  • 1.1.1
Author:
  • Per Arne Drevland
Source:
Requires:
  • module:/lib/xp/websocket
  • module:/lib/xp/io
  • module:/lib/xp/portal
Example
var ws = require('/lib/wsUtil');

Requires

  • module:/lib/xp/websocket
  • module:/lib/xp/io
  • module:/lib/xp/portal

Classes

SocketEmitter

Methods

(static) addHandlers(event, handler)

Add additional socket event handlers. This is the secondary handlers for the event and they are being pushed to the additional event handlers array

Parameters:
Name Type Description
event string

The name of the socket event
handler function

The handler to bind to the event
Since:
  • 0.0.1
Source:

(static) addUserToGroup(id, group, autoCreateopt)

Adds a user to a group if it exists. Create the group if it doesn't exist and the autoCreate flag is set or log an error if not

Parameters:
Name Type Attributes Description
id string

The id of the user
group string

The name of the group
autoCreate boolean <optional>

The flag to create the group if it doesn't exist
Since:
  • 0.0.1
Source:

(static) createGroup(name, autoRemoveopt)

Creates a group with given name. If the autoRemove flag is set, if removes a user from the group when user closes connection

Parameters:
Name Type Attributes Description
name string

The name of the group
autoRemove boolean <optional>

Removes the user from the group on close connection
Since:
  • 0.0.1
Source:

(static) expandClient(name, func)

Expand the client library with new functionalities. NOTE: The expansion object have direct access to the client library's inner variables and functions

Parameters:
Name Type Description
name string | object

Name of the new client function or an object with key=name value=function
func function

The function for the new client interface.
Source:
Example
// service/websocket/websocket.js
var ws = require('path/to/wsUtil');

ws.expandClient('hello', function() { send('Hello'); // use the inner send function });

ws.openWebsockets(exports);

// socket.js

var cws = new ExpWs();

cws.hello();

(static) extend(exportObject)

Extends the library functionalities to create reusable extensions

Parameters:
Name Type Description
exportObject object

The object that extends the library
Source:
See:
Example
// lib/extension.js
var ws = require('/lib/wsUtil');

var extensionObject = { extension: extension };
ws.extend(extensionObject);

function extension() {
  ws.addHandler('open', function(event) { log.info('Extension says hi!'); });
}
exports.extension = ws;


// service/extensionService/extensionService.js

var extensionLib = require('extension').extension

extensionLib.openWebsockets(exports);
extensionLib.extension(); // Activate extension

(static) getGroupUsers(group) → (nullable) {Array.<string>}

Get all connected users from a group

Parameters:
Name Type Description
group string

Name of the group
Since:
  • 0.0.1
Source:
Returns:

The array of users or undefined if group doesn't exist

Type
Array.<string>

(static) getWsEvents(event)

The function that binds to the exports webSocketEvent method. This function checks the ws event object for type and calls the appropriate handler. Then it loops over the additional handlers and calls each one of them.

Parameters:
Name Type Description
event object

The event sent from the client
Since:
  • 1.1.0
Source:

(static) openWebsockets(exp, hostopt)

Opens the websocket connection and delegate events to handlers

Parameters:
Name Type Attributes Default Description
exp object

The exports object from the Enonic module that is assigned to handle websocket events
host string <optional>
 portal.serviceUrl({ service: 'websocket'})

The host for the service that serves the web sockets
Since:
  • 0.0.1
Source:

(static) removeUserFromGroup(name, id)

Removes a user from a group of given name, if the group is empty, it removes the group

Parameters:
Name Type Description
name string

Name of the group
id string

The id of the user
Since:
  • 0.0.1
Source:

(static) send(id, message)

Sends a message to given client, if the message is of type object it will be stringified

Parameters:
Name Type Description
id string

The id of the user
message string | object

The message to send
Since:
  • 0.0.1
Source:

(static) sendSocketResponse(req, hostopt) → {SocketResponse}

Send the socket response for a socket request

Parameters:
Name Type Attributes Default Description
req object

The request object passed to the server
host string <optional>
 portal.serviceUrl({ service: 'websocket'})

The url to the service that serves the web sockets
Since:
  • 0.0.1
Source:
Returns:

The response object

Type
SocketResponse
Example
// someSocketService.js
ws = require('/lib/wsUtil');
exports.get = ws.sendSocketResponse;
// or
exports.get = function(req) {
 return ws.sendSocketResponse(req);
 }

(static) sendToGroup(name, message)

extends the sendToGroup function from EnonicXP to stringify objects

Parameters:
Name Type Description
name string

Name of the group
message object | string

Message to send to the group
Since:
  • 0.0.1
Source:
Example
// send to space 'global'
ws.sendToGroup('global', { hello: 'everyone in global' });

(static) setEventHandler(event, handler)

Sets a handler for given socket event

Parameters:
Name Type Description
event 'open' | 'close' | 'message' | 'error'

The name of the event
handler function

The event handler
Since:
  • 0.0.1
Source:

(static) setEventHandlers(handlers)

Set all socket event handlers

Parameters:
Name Type Description
handlers object
Since:
  • 0.0.1
Source:

(static) setSocketRequestResponse(response)

set custom socket response object. Default object is taken from Enonic doc

Parameters:
Name Type Description
response SocketResponse

The socket response object
Since:
  • 0.0.1
Source:

Type Definitions

SocketResponse

The response object sent from the server

Type:
  • object
Properties:
Name Type Description
webSocket object

Main response object

Properties
Name Type Description
data object

Additional data object
subProtocols Array.<string>

Array of sub protocols to support
Source: