Presence & Message Persistence w/the AngularJS Library
- an Angular service to inject the data sync PubNub connector into controllers
- an Angular-friendly mechanism for binding events to the root scope
- additional bookkeeping functions for providing easy access to collections (such as the presence and channels lists)
We’re continuously updating this library – for example, updated presence API support will be coming soon. We’re also actively exploring more features in this library, such as PubNub-enabled Angular directives and integration with the AngularJS promise framework. So stay tuned and let us know here PubNub AngularJS on GitHub if you have any ideas for future enhancements! The PubNub AngularJS library should look familiar to experienced developers in Angular app development as well as to folks who have explored the PubNub API a bit.
For this blog entry, we’ll presume you are somewhat familiar with the ideas from an earlier PubNub AngularJS SDK Blog, at least enough to get started. If you like what you see here, you can jump right into a live version of the app at https://pubnub.github.io/angular-js/#/chat or the source code at https://github.com/pubnub/angular-js/ . Let’s take a look at the contents of https://pubnub.github.io/angular-js/index.html, the main entry point for the application.
Quick Recap: Setting Up
You’ll first need to sign up for a PubNub account. Once you sign up, you can get your unique PubNub keys in the PubNub Developer Portal. Once you have, clone the GitHub repository, and enter your unique PubNub keys on the PubNub initialization, for example:
Here are the script includes you’ll need to get started: The web app is Angular-enabled with an ng-app attribute: The code for our app lives in: The app requires a dependency on the PubNub Angular library (pubnub.angular.service, defined in pubnub-angular.js): The code for our controllers lives in: Once that’s set, the PubNub service can be injected into the controller by name!
Quick Recap: Publish and Subscribe
Publishing to channels is trivial – just use the
PubNub.ngPublish() method. Subscribing to channels is accomplished by calling the
PubNub.ngSubscribe() method. After the channel is subscribed, the app can register root scope message events by calling
$rootScope.$on with the “event name” string returned by
Wiring Up Presence Events into your Application
The Presence API makes it very easy to build presence-aware applications — without the Presence API, you’d have to track all of the join/leave/timeout events yourself on the server side. Which is really tough if you’re building a pure JS web application with no server side! Presence fixes that. To keep things simple, wiring up Presence events using the PubNub AngularJS API is very similar to wiring up Message events. It all boils down to registering an event handler callback for the presence events: In this case,
PubNub.ngPrsEv(theChannel) returns the “event name” string that identifies presence events for the specified channel. The presence event payload contains a bunch of useful information for your app: the channel and PubNub event itself. In the case of a single-user event (which you can tell by the presence of the ‘uuid’ field,
payload.event contains action (join/leave/timeout), occupancy (number of users in the channel), timestamp, and uuid of the relevant user. In the case of a multi-user event (such as the one triggered by
payload.event contains the occupancy count as well as a ‘uuids’ field (note pluralization) which contains the list of current user ids. In addition to the callback-based API, there is also a convenient collection-based API that keeps track of channel membership automatically. To obtain the list of users, just call the
ngListPresence() function with the name of the channel you’d like to list. Of course, you’ll want to already be subscribed to the channel and initialized the ‘here now’ status as in the example below. Often times, we combine both approaches to make sure that our Angular views always have the most up-to-date user list: And just like that, your app is wired for presence!
Using the Storage & Playback Functions to Backfill Messages
In addition to Presence, the PubNub AngularJS API includes some helpers for building real-time message-based applications. One convenient feature we’d like to point out is the Persistence API, which allows applications to retrieve previous messages from PubNub channel storage and fire them as application message events. The Persistence API will require a channel subscription and message event handler as shown below. Once that’s set up, simply call the
gHistory() function with the number of messages to retrieve.
Wrapping Up AngularJS
In this blog post, we had fun showing you a how to integrate your angular app with the PubNub AngularJS library. We hope you find this information to be useful — it is really cool to see the number of PubNub and AngularJS applications growing over the past few weeks!
The PubNub API has many more features we didn’t cover in this blog post, but which are explained in detail in the GitHub API Guide and Reference. The documentation walks you through additional topics which really enhance your real-time-enabled web application. In future blog posts, we’ll cover other features of the PubNub Angular API. In the meantime, please give the AngularJS integration a try, have fun, and reach out if you have ideas visit GitHub pubnub/angular-js. Or, do you need a hand (firstname.lastname@example.org)!