-
Getting Started
-The HTML page includes 3 key libraries:
--
-
- The core PubNub JS Library (generally from the CDN) -
- AngularJS (usually as a Bower component) -
- PubNub Angular (copy & paste for now - bower component coming soon!) -
The HTML script includes look like this:
-<script src="http://cdn.pubnub.com/pubnub.min.js"></script> -<script src="components/angular/angular.js"></script> -<script src="scripts/pubnub-angular.js"></script>-
The app is Angular-enabled with an ng-app attribute:
<body ng-app="PubNubAngularApp">-
Where 'PubNubAngularApp' is the name of the Angular module containing our app.
-The code for the app lives in:
-<script src="scripts/app.js"></script>-
-
PubNub Angular API Tour
-The PubNub Angular API lives in the scripts/pubnub-angular.js file.
Notice the dependency on the PubNub Angular library (pubnub.angular.service):
angular.module('PubNubAngularApp', ["pubnub.angular.service"])
-The code for the controllers lives in:
-<script src="scripts/controllers/main.js"></script>-
Now, the PubNub service can be injected into the controller by name!
.controller('JoinCtrl', function($scope, PubNub) { ... });
-Using the Special AngularJS PubNub API
-Publishing to channels is trivial - just use the PubNub.ngPublish() method.
$scope.publish = function() {
- PubNub.ngPublish({
- channel: $scope.selectedChannel,
- message: $scope.newMessage
- });
-};
--As you can see, we call the PubNub publish method passing in the desired -channel and message to transmit. It is also possible to transmit structured -data as JSON objects, so go wild! -
--It's not necessary to subscribe to a channel in order to publish to a channel. -
-
-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 string returned by
-PubNub.ngMsgEv(channel).
-
$scope.subscribe = function() {
- ...
- PubNub.ngSubscribe({ channel: theChannel })
- ...
- $rootScope.$on(PubNub.ngMsgEv(theChannel), function(event, payload) {
- // payload contains message, channel, env...
- console.log('got a message event:', payload);
- })
--This is the core of the PubNub API - allowing clients to subscribe and -publish to channels, and have those events propagate in real-time to other -applications connected to the same channels. -
-Integrating Presence Events
-
-It's also easy to integrate presence events using the Angular API. In
-the example above, we just add an additional couple lines of code to
-call the PubNub.ngHereNow() method (retrieve current users), and register
-for presence events by calling $rootScope.$on with the event string
-returned by PubNub.ngPrsEv(channel).
-
$scope.subscribe = function() {
- ...
- PubNub.ngSubscribe({ channel: theChannel })
- $rootScope.$on(PubNub.ngMsgEv(theChannel), function(event, payload) { ... })
- ...
- $rootScope.$on(PubNub.ngPrsEv(theChannel), function(event, payload) {
- // payload contains message, channel, env...
- console.log('got a presence event:', payload);
- })
-
- PubNub.ngHereNow { channel: theChannel }
-
-Using the presence event as a trigger, we retrieve the Presence
-list for a channel using the PubNub.ngListPresence(channel)
-function.
-
$rootScope.$on(PubNub.ngPrsEv(theChannel), function(event, payload) {
- $scope.users = PubNub.ngListPresence(theChannel);
-})
-
-It's also possible to retrieve the extended Presence state data
-for a channel using the PubNub.ngPresenceData(channel)
-function.
-
$rootScope.$on(PubNub.ngPrsEv(theChannel), function(event, payload) {
- $scope.userData = PubNub.ngPresenceData(theChannel);
-})
-Retrieving History
--It can be super-handy to gather the previous several hundred messages -from the PubNub channel history. The PubNub Angular API makes this easy -by bridging the event model of the PubNub JS history API and the AngularJS -event broadcast model so that historical messages come through the same -event interface. -
-PubNub.ngHistory({channel:theChannel, count:500});
-// messages will be broadcast via $rootScope...
-Listing & Unsubscribing from Channels
-
-The PubNub Angular API takes care of keeping track of currently subscribed
-channels. Call the PubNub.ngListChannels() method to return a
-list of presently subscribed channels.
-
$scope.channels = PubNub.ngListChannels()-
-Unsubscribing is as easy as calling the PubNub.ngUnsubscribe()
-method. The library even takes care of removing the Angular event handlers
-for you to prevent unsightly memory leaks!
-
PubNub.ngUnsubscribe({channel:theChannel})
-Restricting Access (Advanced)
-
-Often times, it's desirable to lock down applications and channels.
-With PAM (PubNub Access Manager), it's easy. There are 2 calls:
-grant which grants access for users having a specified
-auth key, and audit which returns the current policy
-configuration.
-
-Note: to perform access control operations, the PubNub client must -be initialized with the secret key (which should always be protected -by server-only access). -
-PubNub.ngGrant({channel:theChannel,auth_key:'readers_must_have_this_secret',read:true,write:false,callback:function(){...}});
-# now clients providing the auth key can read...
-
-PubNub.ngAudit({channel:theChannel,auth_key:'readers_must_have_this_secret',callback:function(policy){...}});
-# calls back with the policy description as a JSON object...
--If this is interesting to you, see http://www.pubnub.com/docs/javascript/overview/security.html -for more details! -
--
PubNub Angular API Reference
-Core Angular API Methods
--
-
PubNub.init({publish_key:'your_key',subscribe_key:'your_key',uuid:'an_optional_user_uuid'}): initialize the PubNub Angular API with the specified values
-PubNub.ngSubscribe({channel:aChannel,message:aCallback,presence:anotherCallback}): subscribe to the specified channel; the provided callbacks (if any) will be invoked by wrapper functions that also maintain the Angular data structures for channels list and presence
-PubNub.ngUnsubscribe({channel:aChannel}): unsubscribe from the specified channel including any message/presence events
-PubNub.ngPublish({channel:aChannel,message:aMessage}): publish a message to the specified channel
-PubNub.ngHistory({channel:aChannel}): calls PUBNUB.history with the specified channel to produce root scope message broadcast events (make sure the code is subscribed to the channel and channel message events)
-PubNub.ngHereNow({channel:aChannel}): calls PUBNUB.here_now with the specified channel to produce root scope presence broadcast events (make sure the code is subscribed to the channel and channel presence events)
-PubNub.ngWhereNow(): returns user/channel subscription data
-PubNub.ngAuth(): updates the auth_key associated with the PubNub session
-PubNub.ngAudit(): displays PAM (PubNub Access Manager) settings, see http://www.pubnub.com/docs/javascript/api/reference.html#access
-PubNub.ngGrant(): grants acccess via PAM (PubNub Access Manager), see http://www.pubnub.com/docs/javascript/api/reference.html#grant
-PubNub.ngRevoke(): revokes acccess via PAM (PubNub Access Manager), see http://www.pubnub.com/docs/javascript/api/reference.html#grant
-PubNub.ngListPresence(channel): returns the list of subscribers for a channel
-PubNub.ngPresenceData(channel): returns the map of uuid to extended state data for a channel
-PubNub.ngListChannels(): returns the list of channels that the PubNub Angular API is connected to
-PubNub.ngListPresence(channel): returns the list of subscribers for a channel
-PubNub.ngState({channel:channel}): retrieves extended user state for a channel
-PubNub.ngState({channel:channel,state:newState}): updates extended user state for a channel
-PubNub.ngMsgEv(channel): returns the root scope broadcast event name for message events for a given channel
-PubNub.ngPrsEv(channel): returns the root scope broadcast event name for presence events for a given channel
-
Using the PubNub JS API directly (advanced)
-
-In unusual cases where you need to access the PubNub API directly, we make it
-easy by exposing the PUBNUB methods via the PubNub.jsapi.*. So if
-you really need to call PUBNUB.each(), you can do it by calling
-PubNub.jsapi.each().
-
For example:
--
-
PubNub.jsapi.publish
-PubNub.jsapi.subscribe
-PubNub.jsapi.unsubscribe
-PubNub.jsapi.here_now
-PubNub.jsapi.history
-
-NOTE -These methods do not call the internal AngularJS bookkeeping methods -to make sure the channel lists and rootScope broadcast events -get propagated - make sure you know what you're doing! -
--And... Stay tuned! We're adding support for more PubNub APIs all the -time. -
-
-
-
-
-
-
-
-
-