Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mismith/angularfire-helper
Simplifies common AngularFire interactions by enhancing the flexibility and portability of the `firebase` module.
https://github.com/mismith/angularfire-helper
Last synced: 22 days ago
JSON representation
Simplifies common AngularFire interactions by enhancing the flexibility and portability of the `firebase` module.
- Host: GitHub
- URL: https://github.com/mismith/angularfire-helper
- Owner: mismith
- Created: 2015-01-13T22:01:24.000Z (about 10 years ago)
- Default Branch: master
- Last Pushed: 2015-11-19T21:13:11.000Z (about 9 years ago)
- Last Synced: 2024-04-09T14:59:43.400Z (10 months ago)
- Language: HTML
- Homepage:
- Size: 37.1 KB
- Stars: 7
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# AngularFire Helper
[](http://badge.fury.io/gh/mismith%2Fangularfire-helper)
Simplifies common [AngularFire](https://github.com/firebase/angularfire) interactions by enhancing the flexibility and portability of the `firebase` module. Primary advantages:
- **cleaner code**; no need to maintain a `BASE_URL` or repeat `new Firebase(BASE_URL + path)`
- **simpler dependencies**; inject only one service instead of three (`$firebaseObject`+`$firebaseArray`+`$firebaseAuth` → `$firebaseHelper`)
- **improved performance**; caches all three Firebase data types (reference, object, array)
- **augmented 'joins'**; access normalized data via key-object-association
- **added convenience**; add the missing `$update` method to `$firebaseObject`
# Setup
1. Include [AngularJS](http://angularjs.org/) (1.3.4+), [Firebase](http://www.firebase.com/?utm_medium=web&utm_source=angularfire-helper) (2.2.3+), and [AngularFire](https://www.firebase.com/docs/web/libraries/angular/?utm_medium=web&utm_source=angularfire-heler) (1.0.0+) dependencies, then this library (replace `X.X.X` with latest version)
2. Include this library as a module dependency in your angular app (instead of `firebase`)
angular.module('my-app', ['firebaseHelper'])
3. Set your Firebase namespace
.config(function ($firebaseHelperProvider) {
$firebaseHelperProvider.namespace('my-app');
})
4. Include the `$firebaseHelper` service (in place of `$firebaseObject`, `$firebaseArray`, and `$firebaseAuth`)
.controller('AppCtrl', function ($scope, $firebaseHelper) {
$scope.myObject = $firebaseHelper.object('myObject');
})
# API
## $firebaseHelperProvider
* `namespace(name)`
Gets or sets the name of your Firebase app, i.e. the subdomain part of a URL like: `https://.firebaseio.com/`. You must configure this before calling any `$firebaseHelper` methods.
**Example**:
.config(function ($firebaseHelperProvider) {
$firebaseHelperProvider.namespace('my-app');
})
* `demo(enable)`
Use a `firebaseio-demo.com` URL by passing boolean `true`. (Uses the default `firebaseio.com` otherwise.)
**Example**:
.config(function ($firebaseHelperProvider) {
$firebaseHelperProvider.demo(true);
})
* `root(path)`
Optional. Gets or sets the root path of your Firebase app's data. All `$firebaseHelper` calls will append this path to the base URL. Defaults to `''` (empty).
**Example**:
// if all your data lives under `https://my-app.firebaseio.com/data/…`, then call:
.config(function ($firebaseHelperProvider) {
$firebaseHelperProvider.root('data');
})
## $firebaseObject
* `$update(newData)`
**Returns**: the promise from `$firebaseObject.$save()`
**Replaces**: having to manually handle promise wrapping
**Example**:
// old (pseudo)
var child1 = $firebaseObject(new Firebase(BASE_URL + 'parent/child1'));
child1.$value = newValue;
child1.$save().then(function (child1) {});
// new
$firebaseHelper.object('parent/child1').$update(dataObj).then(function (child1) {});
## $firebaseHelper
If the first parameter in any functions below is one of the following:
* a `Firebase` reference,
* a `$firebaseObject`, or
* a `$firebaseArray`
Then it will be detected as so, and the subsequent arguments will be treated as strings to be joined as a child path. The resulting node will therefore be a child of the first node.
**Example**:
var ref = $firebaseHelper.ref('parent'),
obj1 = $firebaseHelper.object(ref, 'child1/child2', 'child3'),
obj2 = $firebaseHelper.object('parent/child1/child2/child3');
// obj1 === obj2
### Authentication
* auth([[arguments…](#arguments)])
**Returns**: an Angular-augmented authentication object.
**Replaces**: `$firebaseAuth(ref)`.
**Example**:
var old = $firebaseAuth(new Firebase(BASE_URL + 'parent/child1'));
var new = $firebaseHelper.auth('parent/child1');
// old === new
### Data Types
* ref([[arguments…](#arguments)])
**Returns**: a `Firebase` reference at the API level, _i.e._ with no angular enhancements.
**Replaces**: `new Firebase(BASE_URL + path)`.
**Example**:
var old = new Firebase(BASE_URL + 'parent/child1');
var new = $firebaseHelper.ref('parent/child1');
// old === new
* object([[arguments…](#arguments)][, asArray])
**Returns**: a `$firebaseObject`, or, if the last parameter === `true`, then a `$firebaseArray`.
**Replaces**: `$firebaseObject()` and `$firebaseArray()`, respectively.
**Example**:
var old = $firebaseObject(new Firebase(BASE_URL + 'parent/child1'));
var new = $firebaseHelper.object('parent/child1');
// old === new
and
var old = $firebaseArray(new Firebase(BASE_URL + 'parent/child1'));
var new = $firebaseHelper.object('parent/child1', true);
// old === new
* array([[arguments…](#arguments)])
**Returns**: a `$firebaseArray`.
**Replaces**: shortcut for $firebaseHelper.object([[arguments…](#arguments)], true).
**Example**:
var old = $firebaseArray(new Firebase(BASE_URL + 'parent/child1'));
var new = $firebaseHelper.array('parent/child1');
// old === new
### Utility
* load([[arguments…](#arguments)][, asArray])
**Returns**: a promise that resolves when the required resource is ready. The first param of the callback will be that loaded resource.
**Replaces**: shortcut for $firebaseHelper.object([[arguments…](#arguments)][, asArray]).$loaded().
**Example**:
var old, new;
$firebaseArray(new Firebase(BASE_URL + 'parent/child1')).$loaded().then(function (child1) {
old = child1;
});
$firebaseHelper.load('parent/child1', true).then(function (child1) {
new = child1;
});
// once both loaded: old === new
* join([keys…](#arguments), [values…](#arguments))
**Returns**: a `$firebaseJoin` array of key-value-associated objects. Both `keys…` and `values…` params work like [arguments…](#arguments) in that they can be strings, special Firebase data types, or arrays thereof.
**Replaces**: wrapper for custom `$firebaseJoin` service ([see below](#firebasejoin)).
**Example**:
var keys = $firebaseHelper.ref('keys'),
myObject = $firebaseHelper.object('parent'),
joined = $firebaseHelper.join(keys, [myObject, 'child1']);
`joined` contains all children of `/parent/child1` whose `$id`s are present in `/keys`
* $firebaseJoin([keysRef, ]valuesRef)
**Returns**: an augmented `$firebaseArray` of `$firebaseObjects`, including only the `$firebaseObjects` from `valuesRef` whose keys appear in the `$firebaseArray` at `keysRef`. _i.e._ Given a Firebase data structure like this:
{
keys: {
value1: 'value1',
value3: 'value3'
},
parent: {
child1: {
value1: 1,
value2: 2,
value3: 3,
value4: 4
}
}
}
$firebaseJoin($firebaseHelper.ref('keys'), $firebaseHelper.ref('parent/child1')).$loaded(function (data) {
// data == [{$id: 'value1', $value: 1}, {$id: value3, $value: 3}];
});
Can also be used with only one argument to get a `$firebaseArray` of `$firebaseObjects` for any path. _e.g._
$firebaseJoin($firebaseHelper.ref('parent/child1')).$loaded(function (data) {
// data == [{$id: 'value1', $value: 1}, {$id: 'value2', $value: 2}, {$id: 'value3', $value: 3}, {$id: value4, $value: 4}];
});
### Manipulation
All `$firebaseArray`-like methods are provided, including new and augmented functionality:
* `$add(data)`
Create a new object in `values` then create a key in `keys` to link it.
**Example**:
$firebaseJoin('keys', 'parent/child1').$add({name: 'Name'})
{
keys: {
value1: 'value1',
value3: 'value3'
},
parent: {
child1: {
value1: 1,
value2: 2,
value3: 3,
value4: 4
}
}
}
→
{
keys: {
value1: 'value1',
value3: 'value3',
'-JABCDE12345fghi0000': '-JABCDE12345fghi0000'
},
parent: {
child1: {
value1: 1,
value2: 2,
value3: 3,
value4: 4,
'-JABCDE12345fghi0000': {
name: 'Name'
}
}
}
}
* `$save(indexOrItem)`
Update an existing value object in `values` (without affecting `keys`).
**Example**:
var joined = $firebaseJoin('keys', 'parent/child1'),
value3 = joined.$getRecord('value3');
value3.$value += 2;
joined.$save('value3');
// can also do this instead:
value3.$value += 2;
value3.$save();
{
keys: {
value1: 'value1',
value3: 'value3'
},
parent: {
child1: {
value1: 1,
value2: 2,
value3: 3,
value4: 4
}
}
}
→
{
keys: {
value1: 'value1',
value3: 'value3'
},
parent: {
child1: {
value1: 1,
value2: 2,
value3: 5,
value4: 4
}
}
}
* `$remove(indexOrItem)`
Delete an existing value object from `values` then delete its key from `keys`.
**Example**:
$firebaseJoin('keys', 'parent/child1').$remove('value3')
{
keys: {
value1: 'value1',
value3: 'value3'
},
parent: {
child1: {
value1: 1,
value2: 2,
value3: 3,
value4: 4
}
}
}
→
{
keys: {
value1: 'value1'
},
parent: {
child1: {
value1: 1,
value2: 2,
value4: 4
}
}
}
* `$link(key)`
Add an existing value object based on its `key`.
**Example**:
$firebaseJoin('keys', 'parent/child1').$link('value3')
{
keys: {
value1: 'value1'
},
parent: {
child1: {
value1: 1,
value2: 2,
value3: 3,
value4: 4
}
}
}
→
{
keys: {
value1: 'value1',
value3: 'value3'
},
parent: {
child1: {
value1: 1,
value2: 2,
value3: 3,
value4: 4
}
}
}
* `$unlink(indexOrItem)`
Delete an existing key from `keys` but leave its value object intact in `values`.
**Example**:
$firebaseJoin('keys', 'parent/child1').$unlink('value3')
{
keys: {
value1: 'value1',
value3: 'value3'
},
parent: {
child1: {
value1: 1,
value2: 2,
value3: 3,
value4: 4
}
}
}
→
{
keys: {
value1: 'value1'
},
parent: {
child1: {
value1: 1,
value2: 2,
value3: 3,
value4: 4
}
}
}
### Utility
* `$loaded([resolve[, reject]])`
Wait for all filtered value objects to load.