View Source

h1. JavaScript Integration

This is the lowest-level client-side integration, and assumes only a basic HTML page with an embedded JavaScript implementation that initializes and interacts with the ICEpush client.

h2. Initialization and Page Inclusion

The ICEpush Javascript Bridge must be included in the page.
{code}
<html>
<head>
<script type="text/javascript" src="code.icepush"></script>
</head>
<body>
...
</body>
</html>
{code}
The script tag will cause the browser to request ./code.icepush, which, by convention, is mapped to the ICEpush Servlet in your web.xml file.
{code}
<servlet>
<servlet-name>icepush</servlet-name>
<servlet-class>org.icepush.servlet.ICEpushServlet</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>icepush</servlet-name>
<url-pattern>*.icepush</url-pattern>
</servlet-mapping>
{code}
The ICEpush Servlet will serve the javascript code when this url is requested, and the ICEpush Bridge will then be loaded and initialized in the client browser.

h2. Usage

Once the ICEpush bridge is loaded and initialized in the client browser, it is possible for JavaScript application logic to register for inclusion in a group, register notification callbacks, get current notifications, and initiate notifications as follows:
{code}
<script type="text/javascript">
var pushId = ice.push.createPushId();
ice.push.addGroupMember("rooms", ice.push.createPushId());
ice.push.register([pushId], window.refreshChatRoomsList);
</script>
{code}
h2. ICEpush Javascript API

h3. {{ice.push.createPushId(retries);}}

_(Until 4.0)_

Creates a unique push id that can be used for group registration. Multiple push ids can be created for a single page in an application.

h3. {{ice.push.createPushId(retries, callback);}}

_(As of 4.1)_

Creates a unique push id that can be used for group registration. This function *replaced* the previous {{ice.push.createPushId(retries)}} function and requires a callback function which is used to pass the newly created unique push id. Multiple push ids can be created for a single page in an application.

h3. {{ice.push.addGroupMember(groupName, pushId);}}

Adds a previously created push id to a group.

h3. {{ice.push.register(pushIds, callback);}}

Registers a callback function to a list of push ids. When a push notification occurs for a group that has a registered push id, the ICEpush Bridge will call the registered callback listener function in the browser.

h3. {{ice.push.deregister(pushId);}}

Unregisters a previously created push id with any groups and callback listener functions.

h3. {{ice.push.getCurrentNotifications();}}

Can be called in a callback function to find the current push ids which are being notified.

h3. {{ice.push.notify(groupName, options);}}

_(As of 3.4)_

Trigger a notification event for the specified _groupName_. The optional _options_ parameter can be a JS object with properties that are read as name-value pairs.
For example:
{code}
ice.push.notify(groupName, {subject:'hello', detail:'how are you'});{code}
h3. {{ice.push.removeGroupMember(groupName, pushId);}}

Removes a push id from a previously joined group.


h3. Payload Processing

Payload processing is entirely application-specific. A {{callback-function}} is registered against a {{pushId}} and application logic within that {{callback-function}} must initiate payload retrieval from the server using an {{XMLHttpRequest}} and processing the payload in an application-specific way.