ngDatabase
ngDatabase is a light, very easy to use and powerful storage solution for your Ionic apps. Take advantage of unlimited storage size, data binding, very flexible data management and more.
Quick links
- Get started
- Repositories
- Data operation
- Data selection
- Data binding
- Low level usage
Get started
Quick guide
Get started in 4 steps by following this guideline.
The very first thing you have to do is install ngDatabase : ngDatabase installation
At this point you must launch ngDatabase inside your app and tell him what kind of 'repository' you will used. In ngDatabase a repository is a place where your data will be stored. For exemple if you have to store some user and customer data you will have two repositories severally called 'users' and 'customers'. Check how to create repositories : Create Repositories
Now you've got some repositories ready to work. Each time you make operations on your repositories you have to use the getRepository() method to be able to do anything. -> Get Repositories
The previous method give you an new instance of a working repository. Now you can make what you want thanks to the 4 methods : Data operation
As you can observe we can't do a lot only with these 4 methods. It's the combination between them and 3 others which make the magic. These 3 others are setBy(), setOrder() and setLimit() which define by what criterion the data will be get, add, delete, ... Check it : Data selection
Installation
ngCordova and cordovaSQLite
First, install ndCordova to your project (http://ngcordova.com/docs/install/) :
bower install ngCordova
Don't forget to include the ng-cordova.js file and add ngCordova in your app dependencies :
<script src="path/to/your/lib/ngCordova/dist/ng-cordova.js"></script>
angular.module('myApp', ['ngCordova']);
Then, add the cordovaSQLite plugin :
cordova plugin add https://github.com/litehelpers/Cordova-sqlite-storage.git
ngDatabase
bower install ng-database #bower
npm install ng-database #NPM
Include the ng-database js file in your project :
<script src="path/to/your/lib/ng-database/dist/ngdb.min.js"></script>
Then include ngDatabase dependency :
angular.module('myApp', ['ngCordova', 'ngDatabase']);
API
Important note : all of ngDatabase method must be used when the deviceready event fired.
Repositories
Create
Prototype
ngdbProvider setRepository(string repositoryName, object repositorySchema)
Description
A repository is a kind of bag which define your data schema. It's typically an object where each key-value pair correspond respectively to the name of your data and his type (see bellow). This operation is done in the config step of your app. For exemple, if you have to manage users and pictures in your app your repositories could look like that :
app.config(function(ngdbProvider) {
var usersRepository = {
id: 'ID',
pictures_id:'NUMBER'
name: 'STRING',
born: 'DATE'
};
var pictures = {
id: 'ID',
pictures: 'OBJECT'
};
ngdbProvider
.setRepository('users', usersRepository)
.setRepository('pictures', picturesRepository);
});
- ID : special integer type which is incremented at each insertion
- STRING : can store string such as text
- NUMBER : an integer or floating number
- BOOLEAN : true or false values
- OBJECT : a javascript object
- ARRAY : a javascript array
- DATE : a date (must be an instance of Date())
Get
Prototype
ngdb getRepository(string repositoryName)
Description
This method allow you to make operations in the specified repositoryName. Use it to add, delete, update...
myApp.controller('myCtrl', function(ngdb) {
var usersRepository = ngdb.getRepository('users');
var picturesRepository = ngdb.getRepository('pictures');
//Make all your operations.
});
Data operation
Add
Prototype
promise add(object data)
Description
This method add some data in a repository. Only the keys that correspond to the mapping defined in the config step will be added. Note that you do not have to convert your data. Just let objects as objects, numbers as numbers, strings as strings, ...
Return a promise containing an object with the insertion informations (the ID particularly).
myApp.controller('myCtrl', function(ngdb) {
var usersRepository = ngdb.getRepository('users');
var picturesRepository = ngdb.getRepository('pictures');
var userToAdd = {
pictures_id: 5,
name: 'Jack',
born: new Date()
};
var pictureToAdd = {
pictures: {'path1', 'path2'}
};
var user = usersRepository.add(userToAdd);
var picture = picturesRepository.add(pictureToAdd);
user.then(function(result) {
//The insered id
console.log(result.insertId);
});
});
Get
Prototypes
promise get()
promise getOne()
Description
Get data from repository. All your data are gived back to the correct type (objects as objects, numbers as numbers, ...)
Return promise containing an object with the requested data.
myApp.controller('myCtrl', function(ngdb) {
var usersRepository = ngdb.getRepository('users');
var picturesRepository = ngdb.getRepository('pictures');
//Get all users and pictures data
var usersData = usersRepository.get();
var picturesData = picturesRepository.get();
//Get the first user and picture data
var firstUserData = usersRepository.getOne();
var firstPictureData = pictureRepository.getOne();
usersData.then(function(result) {
//Your data is here !
console.log(result);
});
});
Update
Prototype
promise update(object data)
Description
Update the specified data.
Return promise containing an object with informations about the update.
myApp.controller('myCtrl', function(ngdb) {
var usersRepository = ngdb.getRepository('users');
var picturesRepository = ngdb.getRepository('pictures');
var usersToUpdate = {
name: 'John Doe',
};
var picturesToUpdate = {
pictures: {'newPath'}
};
//Update all users and pictures data
usersRepository.update(usersToUpdate);
picturesRepository.update(picturesToUpdate);
});
Delete
Prototype
promise delete()
Description
Delete entries in the repository.
Return promise containing an object with the informations about the deletion.
myApp.controller('myCtrl', function(ngdb) {
var usersRepository = ngdb.getRepository('users');
var picturesRepository = ngdb.getRepository('pictures');
//Delete all users and pictures data
usersRepository.delete();
picturesRepository.delete();
});
Data selection
These methods can be chained and must be called before the data operation methods (get, update, ...). These methods have an influence on the way the data are going to be treated. All of them take an object where the key correspond to the data name previously defined (in the app config step).
Order
Prototype
ngdb setOrder(object order)
Description
Order your data by something in ascendent ('ASC' keyword) or descendent ('DESC' keyword) order.
Return promise containing an object with the requested data.
myApp.controller('myCtrl', function(ngdb) {
var usersRepository = ngdb.getRepository('users');
//Get all users sorted by name in ascendent order
usersRepository.setOrder({'name': 'ASC'}).get();
//Get all users sorted by id in descendent order
usersRepository.setOrder({'id': 'DESC'}).get();
});
Standards
Prototype
ngdb setBy(object conditions)
Description
Get, update or delete data according to the equality of the key-value object.
Return promise containing an object with the requested data.
myApp.controller('myCtrl', function(ngdb) {
var usersRepository = ngdb.getRepository('users');
//Get all users named 'John'
usersRepository.setBy({'name': 'John'}).get();
//Get the user with id equal to 1
usersRepository.setOrder({'id': 1}).getOne();
//Get the user named John with id equal to 1
usersRepository.setBy({'id': 1, 'name': 'John'}).getOne();
});
Limit
Prototype
ngdb setLimit(int from, int to)
Take two integer which represent the interval.
Return promise containing an object with the requested data.
myApp.controller('myCtrl', function(ngdb) {
var usersRepository = ngdb.getRepository('users');
//Get 0 to 10 first results
usersRepository.setLimit(0, 10).get();
//Get 10 to 20 first results
usersRepository.setLimit(10, 20).get();
});
Data binding
CURRENT WRITING, VERY SOON AVAILABLE
Low level usage
Native SQLite syntax
Prototypes
promise query(string query, array bindings)
object fetchAll(object SQLiteResult)
object fetch(object SQLiteResult)
Description
NGDatabase also allow you to use SQLite as native syntax.
- make() : make an SQL Query
- fetchAll() : fetch all SQLite Query result
- fetch() : fetch one SQLite Query result
Exemple
myApp.controller('myCtrl', function(ngdb) {
var qm = ngdb.getQueryMaker();
var result = qm.make("SELECT * FROM users WEHRE name = ?", ['John Doe']);
result.then(function(result) {
result = qm.fetchAll(result);
});
});