ng-fire-alarm

Distributed via

Firebase binding use $q in AngularJS

Project philosophy

Develop in LiveScript

LiveScript is a compile-to-js language, which provides us more robust way to write JavaScript.
It also has great readibility and lots of syntax sugar just like you're writting python/ruby.

Use new API from $q

We use newly introduced $q API to notify you about the value/order changes, we let you decide how you deal with your data with $scope.

Firebase Collection support

We know that you want to take advantage of collection in Firebase, but still want to preserve the right order, or order by any properties in each item. ng-fire-alarm allows to transform collection object into native js array for you.

Seperation of Concerns

We follow seperation of concerns by seperating control(reference) object and data source to Alarm object and Fire object(s). So a ng-change, ng-submit, ng-click can be directly bound to Alarm object, while your Fire object(s) are clean and just like what you see in Firebase dashboard.

Installation

Just use it

• Download and include ng-fire-alarm.js OR ng-fire-alarm.min.js.

Then include them through script tag in your HTML.

Rails projects (Only support 3.1+)

Add this line to your application's Gemfile:

gem 'ng-fire-alarm'

And then execute:

$ bundle

Then add these lines to the top of your app/assets/javascripts/application.js file:

//= require angular
//= require ng-fire-alarm

And include in your angular module definition:

var module = angular.module('my-awesome-project', ['ng-fire-alarm']).

Usage

We add a new method to Firebase.prototype:

$toAlarm

The key to transform your Firebase reference into a AngularJS powered alarm object, it take one parameter:

Options

collection: true/otherwise.

Pass true will transform collection object into native js array for you.

Alarm object

A wrapped object over Firbease reference that is returned by calling Firebase.prototype.$toAlarm.

Attributes:

• $promise: it will be notified everytime the value/order changes.

Convenience Method:

• $thenNotify: Same as $promise.then(void, void, callback).
  Register a callback that notify you each time the alarm rings.
  Unlike $promise.then, this method is self-chained and will return alarm object to allow chaining.
  See examples below.

Query Methods:

Ther're wrapper for Firebase.prototype.limit/startAt/endAt function, but it'll update internal Firebase reference and it'll populate new data through your callback registered via $thenNotify.

• $limit
• $startAt
• $endAt

Examples:

var ROOT = new Firebase('https://ng-fire-alarm.firebaseio.com/');

function UsersListCtrl ($scope) {
  $scope.users = [];

  $scope.usersAlarm = ROOT.child('users').$toAlarm({collection: true});

  $scope.usersAlarm.$thenNotify(function(users) {
    $scope.users = users;
  });
}

Fast prototyping!

<ul ng-controller="UsersListCtrl" infinite-scroll="usersAlarm.$limit(users.length + 25)">
  <li ng-repeat="user in users">
    {{ user.name }}
  </li>
</ul>

Write Methods:

They're wrapper for Firebase.prototype.remove/push/update/set/setPriority/setWithPriority function, but it'll return a promise object instead of passing in a callback function.

• $remove
• $push
• $update
• $set
• $setPriority
• $setWithPriority

Examples:

var ROOT = new Firebase('https://ng-fire-alarm.firebaseio.com/');

function UserEditCtrl ($scope) {
  $scope.userAlarm = ROOT
    .child('users/`')
    .$toAlarm()
    .$thenNotify(function(user) {  $scope.user = user;  });
}

Fast prototyping!

<form ng-controller="UserEditCtrl">
  <input type="text" ng-model="user.name" ng-change="userAlarm.$update(user)">
</form>

Fire object(s)

Object that is passed in to callbacks registered via $thenNotify, they can be primitive, object, or array:

primitive

Primitive is just js primitive. There's NO NO NO wrapper around primitive {$value: primitive}.

bell.$thenNotify(function (aStringOrANumber) { $scope.myVar = aStringOrANumber; });

object

we've add two properties on it:

1. $name
2. $priority

array

sorted by native Firebase ordering.

Each item in array, if they're object, will have these properties:

1. $name
2. $priority
3. $index: object index in array. Useful for reverse ordering

<div ng-repeat="item in array | orderBy:'$index':true"></div>

Contributing

1. Fork it ( https://github.com/tomchentw/ng-fire-alarm/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request