This plugin is an extension for Backbone.js framework and it's based on Backendless JS SDK which provide you to get an easy way to use Backendless with Backbone.js.
You can use any features and services of Backendless JS SDK, the plugin just helps you to use Backendless Data Service in your project
- Getting started
- Initialize your Backendless Application
- Model usages
- Define Backendless Model Class
- Create an instance of Backendless Model
- Create and Save Backendless Model
- Update Backendless Model
- Destroy Backendless Model
- Retrieving Schema Definition
- Fetch Backendless Model
- Find Backendless Model by Id
- Find the first Backendless Model
- Find the last Backendless Model
- Advanced Search
- Collection usages
- Define Backendless Collection Class
- Create an instance of Backendless Collection
- Fetch Backendless Collection
- Fetch Backendless Collection with query params
- Relations and nested Models/Collections
- Nested items
- Update nested items
- Retrieve nested items
- Events
Add Backbone.js and Backbone's dependencies into you project.
Add Backendless JS SDK into you project.
Add the plugin into you project, four quick start options are available:
- Download the latest release.
- Clone the repository:
git clone https://github.com/Backendless/Backendless-Backbone.git
. - Install with NPM:
npm install backendless-backbone
. - Install with Bower:
bower install backendless-backbone
.
Include files:
<script src="/path/to/backbone.js"></script><!-- Backbone is required -->
<script src="/path/to/backendless-js.js"></script><!-- Backendless JS SDK is required -->
<script src="/path/to/backendless-backbone.js"></script>
var APPLICATION_ID = 'YOUR-APPLICATION-ID';
var JS_SECRET_KEY = 'YOUR-JS_SECRET_KEY';
var APPLICATION_VERSION = 'v1'; // it's default
Backendless.initApp(APPLICATION_ID, JS_SECRET_KEY, APPLICATION_VERSION);
- Define Backendless Model Class
- Create an instance of Backendless Model
- Create and Save Backendless Model
- Update Backendless Model
- Destroy Backendless Model
- Retrieving Schema Definition
- Fetch Backendless Model
- Find Backendless Model by Id
- Find the first Backendless Model
- Find the last Backendless Model
- Advanced Search
var Contact = Backbone.Model.extend({schemaName: 'Contact'});
var contact = new Contact({name: 'Bob', age: 32});
or
var contact = new Backbone.Model({name: 'Bob', age: 32}, {schemaName: 'Contact'});
or
var contact = new Backbone.Model({___class: 'Contact', name: 'Bob', age: 32});
var Contact = Backbone.Model.extend({schemaName: 'Contact'});
var contact = new Contact({name: 'Bob', age: 32});
contact.save();
// after save the model:
contact.toJSON() ==> {___class: 'Contact', objectId: 'CONTACT-OBJECT-ID', name: 'Bob', age: 32}
or
var Contacts = Backbone.Collection.extend({schemaName: 'Contact'});
var contact = Contacts.create({name: 'Bob', age: 32});
// after save the model:
contact.toJSON() ==> {___class: 'Contact', objectId: 'CONTACT-OBJECT-ID', name: 'Bob', age: 32}
var Contact = Backbone.Model.extend({schemaName: 'Contact'});
var contact = new Contact({objectId: 'CONTACT-OBJECT-ID'});
contact.fetch().done(function(){
contact.set({name: 'Nick '});
contact.save();
//or
contact.save({name: 'Nick '});
});
var Contact = Backbone.Model.extend({schemaName: 'Contact'});
var contact = new Contact({objectId: 'CONTACT-OBJECT-ID'});
contact.destroy();
var Contact = Backbone.Model.extend({schemaName: 'Contact'});
var contact = new Contact();
contact.describe({
success:function(){
console.log(contact.schema);
}
});
var Contact = Backbone.Model.extend({schemaName: 'Contact'});
var contact = new Contact({objectId: 'CONTACT-OBJECT-ID'});
contact.fetch();
// after fetch the model:
contact.toJSON() ==> {___class: 'Contact', objectId: 'CONTACT-OBJECT-ID', name: 'Bob', age: 32}
var contact = new Contact();
contact.fetch({id: 'CONTACT-OBJECT-ID'});
var contact = new Contact();
contact.fetch();
var contact = new Contact();
contact.fetch({isLast: true});
Query params:
- properties: [Array | String] - is an array or string containing property names. If the array has any data, find operations return data object(s) with the requested property names.
- relations: [Array | String] - references object properties which are relations and should be initialized and returned with the parent object. By default relations are not returned with the parent object and require a separate API call to load. Using the loadRelations query parameter Backendless pre-initializes the specified relations and returns them with the parent object..
- relationsDepth: [Number] - hierarchy depth of the relations to include into the response.
- condition: [String] - this is a query in the SQL-92 syntax (the "where" clause part) to search for data with
- sortingBy: [Array | String] - is an array or string of properties by which should be sorted by,
The first three params you can use every time, but __condition__ and __sortingBy__ uses when the model has no `id` and you want to find the first/last model of founded and sorted items
Example: find the first contact `where name=Nick` `and sorted by age`
```js
var contact = new Contacts();
contact.fetch({
condition: 'name=Nick',
sortingBy: 'age desc'
});
```
You can define the query params as model props (value or function) or pass it to fetch as options
```js
var Contact = Backbone.Model.extend({
schemaName: 'Contact',
properties:function(){
return ['name', 'age', 'myProp'];
},
relations: ['address'],
relationsDepth: 2,
condition: 'age > 21'
sortingBy: 'age desc, name asc'
});
var contact = new Contact();
contact.fetch();
```
or
```js
var Contact = Backbone.Model.extend({ schemaName: 'Contact' });
var contact = new Contact();
contact.fetch({
properties:function(){
return ['name', 'age', 'myProp'];
},
relations: ['address'],
relationsDepth: 2,
condition: 'age > 21'
sortingBy: 'age desc, name asc'
})
```
- Define Backendless Collection Class
- Create an instance of Backendless Collection
- Fetch Backendless Collection
- Fetch Backendless Collection with query params
var Contacts = Backbone.Collection.extend({schemaName: 'Contact'});
or
var Contact = Backbone.Model.extend({schemaName: 'Contact'});
var Contacts = Backbone.Collection.extend({model: Contact});
var contacts = new Contacts([{name: 'Bob', age: 32}]);
or
var contacts = new Backbone.Collection([{name: 'Bob', age: 32}], {schemaName: 'Contact'});
or
var contacts = new Backbone.Model([{___class: 'Contact', name: 'Bob', age: 32}]);
var Contacts = Backbone.Collection.extend({schemaName: 'Contact'});
var contact = new Contacts();
contact.fetch();
// after fetch the collection:
contact.toJSON() ==> [{___class: 'Contact', objectId: 'CONTACT-OBJECT-ID', name: 'Bob', age: 32}]
And also Backendless return from server paged information, for Ex. after fetch you can get current page offset and total items:
var Contacts = Backbone.Collection.extend({schemaName: 'Contact'});
var contact = new Contacts();
contact.fetch();
// after fetch the model:
contact.offsetItems ==> 0;
contact.totalItems ==> 123456;
The same params as for Models:
- properties: [Array | String] - is an array or string containing property names. If the array has any data, find operations return data object(s) with the requested property names.
- relations: [Array | String] - references object properties which are relations and should be initialized and returned with the parent object. By default relations are not returned with the parent object and require a separate API call to load. Using the loadRelations query parameter Backendless pre-initializes the specified relations and returns them with the parent object..
- relationsDepth: [Number] - hierarchy depth of the relations to include into the response.
- condition: [String] - this is a query in the SQL-92 syntax (the "where" clause part) to search for data with
- sortingBy: [Array | String] - is an array or string of properties by which should be sorted by,
Paged params:
- pageSize: [Number] - sets the size of the "page", i.e. the size of the collection of results to be returned by the find operation.
- offset: [Number] - sets the offset in the data store from where to search for data.
The same behavior as for Models, you can define the props in CollectionClass or pass it to fetch as options
A data object stored in a Backendless backend may reference other objects. These references are called relations. There are two types of relations: one-to-one and one-to-many. Relations may be declared manually in a table schema using the Backendless Console or derived (and added to schema) from the objects which are being saved. Additionally, Backendless supports bidirectional relations between the objects stored in the Data Service and other entities in a Backendless backend. For example, a data object may have a relation with a User object and/or Geo Point objects.
Read more about relations here
You can create a nested items in your Models easy:
var PhoneBook = Backbone.Model.extend({schemaName: 'PhoneBook'});
var Contact = Backbone.Model.extend({schemaName: 'Contact'});
var Contacts = Backbone.Collection.extend({model: Contact});
var Address = Backbone.Model.extend({schemaName: 'Address'});
var john = new Contact({
name : "John",
age : 27,
address: new Address({city: "Denver"})
});
var mom = new Contact({
name : "Mom",
age : 45,
address: new Address({city: "Denver"})
});
var bob = new Contact({
name : "Bob",
age : 22,
address: new Address({city: "Denver"})
});
var nick = new Contact({
name : "Nick",
age : 25,
address: new Address({city: "New York"})
});
var phoneBook = new PhoneBook({owner: john, contacts: new Contacts([mom, bob])});
You can save parent model the first time and then save only data what you need for save traffic
phoneBook.save(); // save parent and all nested items in the server
phoneBook.get('owner').save({age:30}, {patch: true}); // sent to server only {age:30}
phoneBook.get('contacts').create(nick); // save nick on the server and added into contacts collection
if you use get
method for getting nested items you get Backbone.Model/Collection instance
but when you use toJSON
it return to you a cloned object with all nested items
phoneBook.toJSON() ===> {
___class: 'PhoneBook',
owner : {
___class:'Contact',
name : "John",
age : 27,
address : {
___class:'Address',
city: "Denver"
}
},
contacts: [
{
___class:'Contact',
name : "Mom",
age : 45,
address : {
___class:'Address',
city: "Denver"
}
},
....
{
___class:'Contact',
name : "Bob",
age : 22,
address : {
___class:'Address',
city: "Denver"
}
}
]
}
Subscribe on events for nested items is really easy, just use .
dot between nested items keys.
You can use all Backbone events
phoneBook.on('owner.change:name', this.onOwnerNameChange, this);
phoneBook.on('owner.address.change', this.onOwnerAddressChange, this);
phoneBook.on('contacts.add', this.onContactsAdd, this);
phoneBook.on('contacts.reset', this.onContactsReset, this);
phoneBook.on('contacts.change:name', this.onContactsNameChange, this);
phoneBook.on('contacts.address.change', this.onContactsAddressChange, this);