seneca-ng-web - a Seneca plugin

Seneca Angular Web Plugin

This plugin provides an Angular API for Seneca. It provides:

• An Angular service for web API requests
• An Angular service for simple client-side pubsub events

For a gentle introduction to Seneca itself, see the senecajs.org site.

If you're using this plugin module, feel free to contact me on twitter if you have any questions! :) @rjrodger

Current Version: 0.1.2

Tested on: Seneca 0.5.20, Node 0.10.29

Quick Example

In your server-side Node.js app, load this plugin using:

var seneca = require('seneca')()

seneca.use('ng-web')

Then in your HTML, load the Seneca client-side initialisation script:

    <script src="/seneca/init.js"></script>

And in your client-side angular code, use it like so:

angular
  .module('fooModule')
  .service('fooAPI',      seneca.ng.web({prefix:'/api/1.0/'}))
  .service('fooPubSub',   seneca.ng.pubsub())
  .controller('fooBar',function( $scope, fooAPI, fooPubSub ) {

    // load a resource from /api/1.0/foo
    fooAPI.get('foo',function(data){
      fooPubSub.pub('foo-loaded',[data])
    })

    fooPubSub.sub('foo-loaded',function(data){
      $scope.data = data
    })
  })

Standalone Example

Check out the simple Express/Angular app in the test folder. Run with:

$ cd test/web
$ node test-app.js

The test/web/index.html contains some example client-side code.

Web API

This is a convenience API for web requests. Use this to make requests against URL end points you have defined with seneca-web.

Construction

Construct a new instance of an Angular service using seneca.ng.web(). This returns an Angular service function of the form function( $http ) { ... }. You can create as many separate instances as you like.

You can pass in an options object to customize the service. In this example, all request URLs are prefixed with /foo/bar/.

angularModuleObject.service('serviceName', seneca.ng.web({
  prefix: '/foo/bar/'
}))

The available options are:

• prefix - URL path prefix; optional, default: ""
• fail - generic failure function, called when request fails; optional; default: console.log
• win - generic success function, called when request returns successfully; optional; default: console.log

The generic win and fail functions can be overridden for each API call.

Methods

• get - perform a GET request
• post - perform a POST request
• put - perform a PUT request
• delete - perform a DELETE request
• call - perform any HTTP request

Perform a GET request. Responses are not cached, so a new network request is generated each time. The suffix is concatenated to the options.prefix value as a string. Forward slashes are not automatically inserted.

Example

angular
  .module('fooModule')
  .service('fooAPI', seneca.ng.web({prefix:'/foo/'}))
  .controller('fooBar',function( $scope, fooAPI ) {

    // GET /foo/bar
    fooAPI.get('bar',function(data,details){
      console.log(data,details)
    })
  })

Arguments

• suffix - Suffix string to append to options.prefix to form full URL path; optional.
• win - Success callback; signature: win( data, details ); optional.
  • data - result object provided by Angular $http.
  • details - details object describing the orginal request:
    • method - HTTP method
    • prefix - URL path prefix used
    • suffix - URL path suffix used
    • status - HTTP status code
    • headers - Response headers
    • config - Angular request configuration

Perform a POST request. Responses are not cached. The URL path is constructed in the same way as the GET request. You supply the data for the POST request as a plain JavaScript object. This will be serialized to JSON by Angular.

Example

angular
  .module('fooModule')
  .service('fooAPI', seneca.ng.web({prefix:'/foo/'}))
  .controller('fooBar',function( $scope, fooAPI ) {

    // POST /foo/bar
    // { "color": "red" }
    fooAPI.post('bar',{color:'red'},function(data,details){
      console.log(data,details)
    })
  })

Arguments

• suffix - Suffix string to append to options.prefix to form full URL path; optional.
• data - Request data as a JavaScript object, wil be JSONified; optional
• win - Success callback; signature: win( data, details ); optional.
  • data - result object provided by Angular $http.
  • details - details object describing the orginal request, as per GET.
• fail - Failure callback; signature: fail( data, details ); optional; callback arguments as per win.

Perform a PUT request. This method has the exact same API as POST.

Perform a DELETE request. This method has the exact same API as GET.

Perform any HTTP request. For those HTTP methods that do not require data, the data argument is ignored. The callopts argument can be used to set Angular http$ options. All arguments are optional - use a null as a placeholder.

Arguments

• method - HTTP request method; optional; default:GET.
• suffix - Suffix string to append to options.prefix to form full URL path; optional.
• data - Request data as a JavaScript object, wil be JSONified; optional
• callopts - Angular http$ settings; optional
• win - Success callback; signature: win( data, details ); optional.
  • data - result object provided by Angular $http.
  • details - details object describing the orginal request, as per GET.
• fail - Failure callback; signature: fail( data, details ); optional; callback arguments as per win.

PubSub API

This provides a simple publish/subscribe service for custom events within your Angular app. This avoids perfomance issues with $rootScope, and avoids Angular scoping issues in general. That means you can use it for arbitrary event-based communication between any Angular object types.

Construction

Construct a new instance of an Angular service using seneca.ng.pubsub(). This returns an Angular service function of the form function() { ... }. You can create as many separate instances as you like. There are no options.

Methods

• pub - Publish a named event with optional arguments.
• sub - Subscribe to a named event.

Publish an event to a topic. The topic is an arbitrary string, and does not need to be defined in advance. You provide the event arguments as an array, and these are passed to any subscribers.

Example

angular
  .module('fooModule')
  .service('fooPubSub', seneca.ng.pubsub())
  .controller('fooBar',function( $scope, fooPubSub ) {

    fooPubSub.pub('hello',['World'])
  })

Arguments

• topic - Topic string identifying the event; required.
• args - Arguments array; optional.

Subscribe to an event topic. Whenever the pub method is called, your callback function will be invoked. The arguments supplied to the pub method as an array will be used as the actual arguments of the callback.

Example

angular
  .module('fooModule')
  .service('fooPubSub', seneca.ng.pubsub())
  .controller('fooBar',function( $scope, fooPubSub ) {

    fooPubSub.sub('hello',function(who) {
      console.log('Hello '+who+'!')
    })
  })

Arguments

• topic - Topic string identifying the event; required.
• callback - Function invoked when event is fired; signature: function( arguments... ); required.

Ad hoc Console Testing

You can gain access to the service objects directly using the following Angular incantation:

var api = angular.element('body').injector().get('fooAPI')

You'll need to ensure that you call angular.element on an element that has the service object in scope.