core.js

Candy

Chats are not dead yet.

Authors

Patrick Stadler patrick.nosp@m..stadler@gmai.nosp@m.l.com
Michael Weibel michael.nosp@m..weibel@gmai.nosp@m.l.com

Copyright

Summary

core.js
Candy.Core	Candy Chat Core
Variables
autojoin	If set to `true` try to get the bookmarks and autojoin the rooms (supported by ejabberd, Openfire).
presencePriority	Default priority for presence messages in order to receive messages across different resources
resource	JID resource to use when connecting to the server.
Private Functions
_addNamespace	Adds a namespace.
_addNamespaces	Adds namespaces needed by Candy.
Functions
init	Initialize Core.
registerEventHandlers	Adds listening handlers to the connection.
connect	Connect to the jabber host.
Events
candy:core.before-connect	Triggered before a connection attempt is made.
Functions
attach	Attach an already binded & connected session to the server
disconnect	Leave all rooms and disconnect
addHandler	Wrapper for Strophe.Connection.addHandler() to add a stanza handler for the connection.
getUser	Gets current user
setUser	Set current user.
getConnection	Gets Strophe connection
removeRoom	Removes a room from the rooms list
getRooms	Gets all joined rooms
getStropheStatus	Get the status set by Strophe.
setStropheStatus	Set the strophe status
isAnonymousConnection	Returns true if Candy.Core.connect was first called with a domain instead of a jid as the first param.
getOptions	Gets options
getRoom	Gets a specific room
onWindowUnload	window.onbeforeunload event which disconnects the client from the Jabber server.
rawInput	(Overridden from Strophe.Connection.rawInput)
log	Overridden to do something useful if debug is set to true.

Candy.Core

Candy Chat Core

Parameters

(Candy.Core) self	itself
(Strophe) Strophe	Strophe JS
(jQuery) $	jQuery

Summary

Variables
autojoin	If set to `true` try to get the bookmarks and autojoin the rooms (supported by ejabberd, Openfire).
presencePriority	Default priority for presence messages in order to receive messages across different resources
resource	JID resource to use when connecting to the server.
Private Functions
_addNamespace	Adds a namespace.
_addNamespaces	Adds namespaces needed by Candy.
Functions
init	Initialize Core.
registerEventHandlers	Adds listening handlers to the connection.
connect	Connect to the jabber host.
Events
candy:core.before-connect	Triggered before a connection attempt is made.
Functions
attach	Attach an already binded & connected session to the server
disconnect	Leave all rooms and disconnect
addHandler	Wrapper for Strophe.Connection.addHandler() to add a stanza handler for the connection.
getUser	Gets current user
setUser	Set current user.
getConnection	Gets Strophe connection
removeRoom	Removes a room from the rooms list
getRooms	Gets all joined rooms
getStropheStatus	Get the status set by Strophe.
setStropheStatus	Set the strophe status
isAnonymousConnection	Returns true if Candy.Core.connect was first called with a domain instead of a jid as the first param.
getOptions	Gets options
getRoom	Gets a specific room
onWindowUnload	window.onbeforeunload event which disconnects the client from the Jabber server.
rawInput	(Overridden from Strophe.Connection.rawInput)
log	Overridden to do something useful if debug is set to true.

Variables

autojoin

autojoin: undefined

If set to `true` try to get the bookmarks and autojoin the rooms (supported by ejabberd, Openfire). You may want to define an array of rooms to autojoin: `[‘ro.nosp@m.om1@conferenc.nosp@m.e.host.tld’, ‘room2...]` (ejabberd, Openfire, ...)

presencePriority

presencePriority: 1

Default priority for presence messages in order to receive messages across different resources

resource

resource: Candy.about.name

JID resource to use when connecting to the server. Specify `’’` (an empty string) to request a random resource.

Private Functions

_addNamespace

Adds a namespace.

Parameters

(String) name	namespace name (will become a constant living in Strophe.NS.*)
(String) value	XML Namespace

_addNamespaces

Adds namespaces needed by Candy.

Functions

init

self.init = function( service,
options )

Initialize Core.

Parameters

(String) service	URL of BOSH/Websocket service
(Object) options	Options for candy

registerEventHandlers

self.registerEventHandlers = function()

Adds listening handlers to the connection.

Use with caution from outside of Candy.

connect

self.connect = function( jidOrHost,
password,
nick )

Connect to the jabber host.

There are four different procedures to login

connect(‘JID’, ‘password’)	Connect a registered user
connect(‘domain’)	Connect anonymously to the domain. The user should receive a random JID.
connect(‘domain’, null, ‘nick’)	Connect anonymously to the domain. The user should receive a random JID but with a nick set.
connect(‘JID’)	Show login form and prompt for password. JID input is hidden.
connect()	Show login form and prompt for JID and password.

See

Candy.Core.attach() for attaching an already established session.

Parameters

(String) jidOrHost	JID or Host
(String) password	Password of the user
(String) nick	Nick of the user. Set one if you want to anonymously connect but preset a nick. If jidOrHost is a domain and this param is not set, Candy will prompt for a nick.

Events

candy:core.before-connect

Triggered before a connection attempt is made.

Plugins should register their stanza handlers using this event to ensure that they are set.

Parameters

(Strophe.Connection) conncetion

Strophe connection

Functions

attach

self.attach = function( jid,
sid,
rid )

Attach an already binded & connected session to the server

See Strophe.Connection.attach

Parameters

(String) jid	Jabber ID
(Integer) sid	Session ID
(Integer) rid	rid

disconnect

self.disconnect = function()

Leave all rooms and disconnect

addHandler

self.addHandler = function( handler,
ns,
name,
type,
id,
from,
options )

Wrapper for Strophe.Connection.addHandler() to add a stanza handler for the connection.

Parameters

(Function) handler	The user callback.
(String) ns	The namespace to match.
(String) name	The stanza name to match.
(String) type	The stanza type attribute to match.
(String) id	The stanza id attribute to match.
(String) from	The stanza from attribute to match.
(String) options	The handler options

Returns

A reference to the handler that can be used to remove it.

getUser

self.getUser = function()

Gets current user

Returns

Instance of Candy.Core.ChatUser

setUser

self.setUser = function( user )

Set current user. Needed when anonymous login is used, as jid gets retrieved later.

Parameters

(Candy.Core.ChatUser) user

User instance

getConnection

self.getConnection = function()

Gets Strophe connection

Returns

Instance of Strophe.Connection

removeRoom

self.removeRoom = function( roomJid )

Removes a room from the rooms list

Parameters

(String) roomJid

roomJid

getRooms

self.getRooms = function()

Gets all joined rooms

Returns

Object containing instances of Candy.Core.ChatRoom

getStropheStatus

self.getStropheStatus = function()

Get the status set by Strophe.

Returns

(Strophe.Status.*)

one of Strophe’s statuses

setStropheStatus

self.setStropheStatus = function( status )

Set the strophe status

Called by

Candy.Core.Event.Strophe.Connect

Parameters

(Strophe.Status.*) status

Strophe’s status

isAnonymousConnection

self.isAnonymousConnection = function()

Returns true if Candy.Core.connect was first called with a domain instead of a jid as the first param.

Returns

(Boolean)

getOptions

self.getOptions = function()

Gets options

Returns

Object

getRoom

self.getRoom = function( roomJid )

Gets a specific room

Parameters

(String) roomJid

JID of the room

Returns

If the room is joined, instance of Candy.Core.ChatRoom, otherwise null.

onWindowUnload

self.onWindowUnload = function()

window.onbeforeunload event which disconnects the client from the Jabber server.

rawInput

self.rawInput = function( data )

(Overridden from Strophe.Connection.rawInput)

Logs all raw input if debug is set to true.

log

self.log = function()

Overridden to do something useful if debug is set to true.

See: Candy.Core#init