JarCastingangular-oboe
A service to stream JSON data in to your controller.
This repo is for distribution on bower.
Many thanks to Jim Higson for the oboe.js library. See http://oboejs.com
What it does
The Oboe service collects a datastream and tries to parse the data as JSON objects. You can pass a URL and a pattern to the service, which will return a promise. By processing the notification immediately in your scope, the user will experience your application as very fast, especially on mobile.
The module takes advantage of the defer and promise implementation of Angular and the Oboe.js library. The Oboe library parses the JSON stream and recognizes the nodes which meets the criteria in the supplied pattern. The module then collects the JSON objects and notifies the promise of the new node.
Install
To try the example:
Make sure you have the following installed:
- node with npm (for building the example and running the local server)
- bower (for dependency management)
- grunt (for running the node tasks)
git clone https://github.com/RonB/angular-oboe.git
cd angular-oboe
npm install
bower install
grunt
Now go to a browser and visit http://localhost:9000
Add module to your project using bower
Go to your project folder and run
bower install angular-oboe --save
Add a <script> to your index.html:
<script src="/bower_components/oboe/dist/oboe-browser.min.js"></script>
<script src="/bower_components/angular-oboe/dist/angular-oboe.min.js"></script>
And add ngOboe module to your app:
angular.module('myApp', ['ngOboe']);
Usage
In your controller you add data to your scope by calling the Oboe service. This returns a promise. The service is called with an object that contains the parameters for the Oboe service. They are the same as the oboe.js API [http://oboejs.com/api].
url:string
specify the url from which the json data should be read
pattern:string
The pattern is to select JSON objects that meet that pattern. http://oboejs.com/api#pattern-matching
start:function
Callback function which is called when the stream starts with a handle to the stream as a parameter. The stream has several functions and events. i.e: If you want to abort the stream while loading you can call the abort() method (http://oboejs.com/api#-abort-).
done:function
Callback function which is called when the stream ends or, if your datastream is not closed but streams multiple JSON objects, then this function is called every time a JSON object is parsed, with the parsed JSON as a parameter.
Returned promise
To use the data in your controller you call the 'then' function of the returned promise.
You can pass three functions:
- The first function is called after the Oboe stream finishes. In some cases however, if the stream has multiple JSON objects, you use the 'done' callback. The promise will only be resolved once.
- The second function is called when an error occurs,
- The third function is called when a JSON object meeting the pattern is received. Use this function to add the received object to your scope.
angular.module('MyApp')
.controller(['$scope', 'Oboe', function($scope, Oboe) {
$scope.myData = [];
Oboe({
url: '/api/myData',
pattern: '{index}',
start: function(stream) {
// handle to the stream
$scope.stream = stream;
$scope.status = 'started';
},
done: function(parsedJSON) {
$scope.status = 'done';
}
}).then(function() {
// promise is resolved
}, function(error) {
// handle errors
}, function(node) {
// node received
$scope.myData.push(node);
if($scope.myData.length === 1000) {
$scope.stream.abort();
alert('The maximum of one thousand records reached');
}
});
}]);
The entire parameter object will be passed to the Oboe funtion [http://oboejs.com/api]. Use this to accomplish authentication with the backend:
angular.module('MyApp')
.controller(['$scope', 'Oboe', function($scope, Oboe) {
$scope.myData = [];
Oboe({
url: '/api/myData',
pattern: '{index}',
withCredentials: true,
headers: {
Authentication: 'Basic ' + btoa('yourusername:yourpassword')
}
}).then(function() {
// promise is resolved
}, function(error) {
// handle errors
}, function(node) {
// node received
$scope.myData.push(node);
});
}]);
Caveats
Parsing the entire datastream might take longer if the JSON is served in one chunk because parsing the data in JS is slower than the standard native parsing in the browser. It might use more CPU than desired in that case.
TODO:
- error handling
- test code
- documentation
Contributers to the project are very welcome!
License
The MIT License
Copyright (c) 2010-2012 Google, Inc. http://angularjs.org
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.