Skip to content
Snippets Groups Projects
Commit 40d6cd5b authored by Sean Madsen's avatar Sean Madsen
Browse files

Clean up content

parent 83121d88
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
docs/framework/backbone.md
+ 203
− 409
View file @ 40d6cd5b
# Backbone Reference
<div class="panelMacro">
+--+
| |
+--+
</div>
<span id="BackboneReference-status"
class="confluence-anchor-link"></span>
<div class="panel"
style="background-color: #FFFFCE;border-color: #000;border-style: solid;border-width: 1px;">
<div class="panelHeader"
style="border-bottom-width: 1px;border-bottom-style: solid;border-bottom-color: #000;background-color: #F7D6C1;">
**Table of Contents**
</div>
<div class="panelContent" style="background-color: #FFFFCE;">
<div>
- [Background](#BackboneReference-Background)
- [Examples](#BackboneReference-Examples)
- [External Packages](#BackboneReference-ExternalPackages)
- [CiviCRM Additions](#BackboneReference-CiviCRMAdditions)
<!-- -->
- [CRM.Backbone.trackSaved](#BackboneReference-CRM.Backbone.trackSaved)
- [CRM.Backbone.trackSoftDelete](#BackboneReference-CRM.Backbone.trackSoftDelete)
- [CRM.Backbone.sync](#BackboneReference-CRM.Backbone.sync)
- [CRM.Backbone.extend(Model,Collection)](#BackboneReference-CRM.Backbone.extend(Model,Collection))
<!-- -->
- [Unit Tests](#BackboneReference-UnitTests)
</div>
</div>
</div>
!!! failure "Deprecated"
CiviCRM no longer recommends using Backbone. This page is here primarily for archival purposes.
## Background
......@@ -71,149 +25,71 @@ Backbone is currently used in the following parts of CiviCRM:
## External Packages
* [Underscore](http://documentcloud.github.io/underscore/)
* General utilities for working with objects, arrays, and client-side HTML templates
* Scope of usage:
* Profile Designer
* CiviVolunteer
* CiviHR
* [Backbone](http://documentcloud.github.io/backbone/)
* MV* framework. Defines three key base-classes:
* `Backbone.Model` - (for representing individual data records)
* `Backbone.Collection` - (for representing a collection of data records)
* `Backbone.View` - (for rendering markup and responding to events)
* Scope of usage:
* Profile Designer
* CiviVolunteer
* CiviHR
* [Backbone.Marionette](http://marionettejs.com/)
* An "opinionated" Backbone framework. It adds more base-classes which significantly reduce the boiler-plate and clutter required for defining & combining normal `Backbone.View` classes.
* See also:
* [A simple Backbone.Marionette tutorial](http://davidsulc.com/blog/2012/04/15/a-simple-backbone-marionette-tutorial/) (Blog, Apr 2012)
* [Tutorial: A full Backbone.Marionette application](http://davidsulc.com/blog/2012/05/06/tutorial-a-full-backbone-marionette-application-part-1/) (Blog, May 2012)
* [Backbone.Marionette.js: A Simple Introduction](https://leanpub.com/marionette-gentle-introduction) (eBook, July 2013)
* Scope of usage:
* Profile Designer
* CiviVolunteer
* CiviHR
* [Backbone.ModelBinder](https://github.com/theironcook/Backbone.ModelBinder)
* A two-way link between Backbone "models" and HTML "forms" – form fields can be initialized using data from models, and models can be updated using form fields.
* Scope of usage:
* CiviHR
* [Backbone.Forms](https://github.com/powmedia/backbone-forms)
* Like `Backbone.ModelBinder`, this can define a two-way link between Backbone "models" and HTML "forms" – however, it goes a step further by auto-generating the HTML form based on the "model schema".
* Scope of usage:
* Profile Designer
<div class="table-wrap">
+--------------------------+--------------------------+--------------------------+
| Package | Description | Scope of Usage |
+==========================+==========================+==========================+
| [Underscore](http://docu | General utilities for | Profile Designer |
| mentcloud.github.io/unde | working with objects, | |
| rscore/){.external-link} | arrays, and client-side | CiviVolunteer |
| | HTML templates | |
| | | CiviHR |
+--------------------------+--------------------------+--------------------------+
| [Backbone](http://docume | MV* framework. Defines | Profile Designer |
| ntcloud.github.io/backbo | three key base-classes: | |
| ne/){.external-link} | | CiviVolunteer |
| | - Backbone.Model (for | |
| | representing | CiviHR |
| | individual | |
| | data records) | |
| | - Backbone.Collection | |
| | (for representing a | |
| | collection of | |
| | data records) | |
| | - Backbone.View (for | |
| | rendering markup and | |
| | responding | |
| | to events) | |
+--------------------------+--------------------------+--------------------------+
| [Backbone.Marionette](ht | An "opinionated" | Profile Designer |
| tp://marionettejs.com/){ | Backbone framework. It | |
| .external-link} | adds more base-classes | CiviVolunteer |
| | which significantly | |
| | reduce the boiler-plate | CiviHR |
| | and clutter required for | |
| | defining & combining | |
| | normal Backbone.View | |
| | classes. | |
| | | |
| | See also: | |
| | | |
| | - [A simple | |
| | Backbone.Marionette | |
| | tutorial (Blog, | |
| | Apr 2012)](http://da | |
| | vidsulc.com/blog/2012/04 | |
| | /15/a-simple-backbone-ma | |
| | rionette-tutorial/){.ext | |
| | ernal-link} | |
| | - [Tutorial: A full | |
| | Backbone.Marionette | |
| | application (Blog, | |
| | May 2012)](http://da | |
| | vidsulc.com/blog/2012/05 | |
| | /06/tutorial-a-full-back | |
| | bone-marionette-applicat | |
| | ion-part-1/){.external-l | |
| | ink} | |
| | - [Backbone.Marionette | |
| | .js: | |
| | A Simple | |
| | Introduction (eBook, | |
| | July 2013)](https:// | |
| | leanpub.com/marionette-g | |
| | entle-introduction){.ext | |
| | ernal-link} | |
+--------------------------+--------------------------+--------------------------+
| [Backbone.ModelBinder](h | A two-way link between | CiviHR |
| ttps://github.com/theiro | Backbone "models" and | |
| ncook/Backbone.ModelBind | HTML "forms" – form | |
| er){.external-link} | fields can be | |
| | initialized using data | |
| | from models, and models | |
| | can be updated using | |
| | form fields. | |
+--------------------------+--------------------------+--------------------------+
| [Backbone.Forms](https:/ | Like | Profile Designer |
| /github.com/powmedia/bac | Backbone.ModelBinder, | |
| kbone-forms){.external-l | this can define a | |
| ink} | two-way link between | |
| | Backbone "models" and | |
| | HTML "forms" – however, | |
| | it goes a step further | |
| | by auto-generating the | |
| | HTML form based on the | |
| | "model schema". | |
+--------------------------+--------------------------+--------------------------+
</div>
## CiviCRM Additions
#### CRM.Backbone.trackSaved
<div class="code panel" style="border-width: 1px;">
<div class="codeHeader panelHeader" style="border-bottom-width: 1px;">
**Tracking saved/unsaved status**
</div>
<div class="codeContent panelContent">
// Setup model class
var MyModel = Backbone.Model.extend({...});
CRM.Backbone.trackSaved(MyModel);
// Use the class
var model = new MyModel({id: 123});
model.fetch();
// assert: model.isSaved() === true -- because our client matches server
model.set('property', 'value'):
// assert: model.isSaved() === false -- because our client deviates from server
// event: saved(model,is_saved)
model.save();
// assert: model.isSaved() === true -- because our client matches server
// event: saved(model,is_saved)
</div>
</div>
Note: The fetch() and save() methods each trigger an AJAX call –
***after completing*** the AJAX call, the save-status will be updated.
If you want to update a view based on the save-status, it's best to
define a callback for the model's "saved" event. However, you *can*
update the view using "success", "error", or "sync" callbacks – but you
***must*** use
[_.defer()](http://documentcloud.github.io/underscore/#defer){.external-link}
before checking isSaved():
<div class="code panel" style="border-width: 1px;">
<div class="codeHeader panelHeader" style="border-bottom-width: 1px;">
**Using isSaved() with success & error**
</div>
<div class="codeContent panelContent">
### `CRM.Backbone.trackSaved`
Tracking saved/unsaved status
```javascript
// Setup model class
var MyModel = Backbone.Model.extend({...});
CRM.Backbone.trackSaved(MyModel);
// Use the class
var model = new MyModel({id: 123});
model.fetch();
// assert: model.isSaved() === true -- because our client matches server
model.set('property', 'value'):
// assert: model.isSaved() === false -- because our client deviates from server
// event: saved(model,is_saved)
model.save();
// assert: model.isSaved() === true -- because our client matches server
// event: saved(model,is_saved)
```
!!! note
The `fetch()` and `save()` methods each trigger an AJAX call – ***after completing*** the AJAX call, the save-status will be updated. If you want to update a view based on the save-status, it's best to define a callback for the model's "saved" event. However, you *can* update the view using "success", "error", or "sync" callbacks – but you ***must*** use [`_.defer()`](http://documentcloud.github.io/underscore/#defer) before checking `isSaved()`. For example:
```javascript
var model = new MyModel({
property1: value1,
property2: value2,
......@@ -233,55 +109,37 @@ before checking isSaved():
});
}
});
```
</div>
</div>
#### CRM.Backbone.trackSoftDelete
<div class="code panel" style="border-width: 1px;">
<div class="codeHeader panelHeader" style="border-bottom-width: 1px;">
**Using soft deletion**
</div>
<div class="codeContent panelContent">
var MyModel = Backbone.Model.extend({...});
CRM.Backbone.trackSoftDelete(MyModel);
// Create an example model
var model = new MyModel({id: 123});
// assert: model.isSoftDeleted() === false
// Flag a model for deletion
model.setSoftDeleted(true);
// assert: model.isSoftDeleted() === true
// event: softDeleted(model, is_soft_deleted)
### `CRM.Backbone.trackSoftDelete`
Using soft deletion
// Remove a deletion flag
model.setSoftDeleted(false);
// assert: model.isSoftDeleted() === false
// event: softDeleted(model, is_soft_deleted)
```javascript
var MyModel = Backbone.Model.extend({...});
CRM.Backbone.trackSoftDelete(MyModel);
// Create an example model
var model = new MyModel({id: 123});
// assert: model.isSoftDeleted() === false
// Perform save or deletion (depending on whether isSoftDeleted())
model.save();
// If isSoftDeleted()==false, call normal save()
// If isSoftDeleted()==true, call destroy() instead
// Flag a model for deletion
model.setSoftDeleted(true);
// assert: model.isSoftDeleted() === true
// event: softDeleted(model, is_soft_deleted)
</div>
// Remove a deletion flag
model.setSoftDeleted(false);
// assert: model.isSoftDeleted() === false
// event: softDeleted(model, is_soft_deleted)
</div>
// Perform save or deletion (depending on whether isSoftDeleted())
model.save();
// If isSoftDeleted()==false, call normal save()
// If isSoftDeleted()==true, call destroy() instead
```
#### CRM.Backbone.sync
### `CRM.Backbone.sync`
The Backbone.sync framework is generally used for loading and saving
data through web-services. The default implementation of Backbone.sync
......@@ -300,125 +158,76 @@ them directly. Instead, use the CRM.Backbone.extendModel and
CRM.Backbone.extendCollection helpers to mix-in the necessary
properties.
#### CRM.Backbone.extend(Model,Collection)
### `CRM.Backbone.extend(Model,Collection)`
To define models & collections which APIv3 for persistence, use the
extendModel() and extendCollection() helpers.
<div class="code panel" style="border-width: 1px;">
<div class="codeHeader panelHeader" style="border-bottom-width: 1px;">
**Define model & collection classes**
</div>
<div class="codeContent panelContent">
var ContactModel = Backbone.Model.extend({
...
});
CRM.Backbone.extendModel(ContactModel, "Contact");
var ContactCollection = Backbone.Collection.extend({
model: ContactModel
});
CRM.Backbone.extendCollection(ContactCollection);
</div>
</div>
<div class="code panel" style="border-width: 1px;">
<div class="codeHeader panelHeader" style="border-bottom-width: 1px;">
**Create a new contact record**
</div>
<div class="codeContent panelContent">
var contact = new ContactModel({
contact_type: 'Individual',
first_name: 'Bat',
last_name: 'Man'
});
contact.save({}, {
success: function() { ... }
error: function() { ... }
});
</div>
</div>
<div class="code panel" style="border-width: 1px;">
<div class="codeHeader panelHeader" style="border-bottom-width: 1px;">
**Load a specific contact record**
</div>
<div class="codeContent panelContent">
var contact = new ContactModel({
id: 123
});
contact.fetch({
success: function() { ... }
error: function() { ... }
});
</div>
</div>
<div class="code panel" style="border-width: 1px;">
<div class="codeHeader panelHeader" style="border-bottom-width: 1px;">
**Load all organizations**
</div>
<div class="codeContent panelContent">
var contacts = new ContactCollection([], {
// crmCriteria defines query parameters per APIv3
crmCriteria: {contact_type: 'Organization'}
});
contacts.fetch({
success: function() {
console.log("Loaded " + contacts.length + " contact(s)");
},
error: function() {
console.log("Failed to load contacts");
}
});
</div>
</div>
<div class="code panel" style="border-width: 1px;">
<div class="codeHeader panelHeader" style="border-bottom-width: 1px;">
**Update list of emails for contact #123 (immediately)**
</div>
<div class="codeContent panelContent">
`extendModel()` and `extendCollection()` helpers.
```javascript
var ContactModel = Backbone.Model.extend({
...
});
CRM.Backbone.extendModel(ContactModel, "Contact");
var ContactCollection = Backbone.Collection.extend({
model: ContactModel
});
CRM.Backbone.extendCollection(ContactCollection);
```
Create a new contact record
```javascript
var contact = new ContactModel({
contact_type: 'Individual',
first_name: 'Bat',
last_name: 'Man'
});
contact.save({}, {
success: function() { ... }
error: function() { ... }
});
```
Load a specific contact record
```javascript
var contact = new ContactModel({
id: 123
});
contact.fetch({
success: function() { ... }
error: function() { ... }
});
```
Load all organizations
```javascript
var contacts = new ContactCollection([], {
// crmCriteria defines query parameters per APIv3
crmCriteria: {contact_type: 'Organization'}
});
contacts.fetch({
success: function() {
console.log("Loaded " + contacts.length + " contact(s)");
},
error: function() {
console.log("Failed to load contacts");
}
});
```
Update list of emails for contact #123 (immediately)
```javascript
// Update the list of email addresses for contact 123
var emails = new EmailCollection([], {
crmCriteria: {contact_id: 123}
});
emails.fetch(...);
...
//...
// Add an email on client and server (with an immediate AJAX request)
var email = emails.create({
......@@ -426,87 +235,72 @@ extendModel() and extendCollection() helpers.
email: 'new-email@example.com'
}, ...);
...
//...
// Modify an email on client and server (with an immediate AJAX request)
emails.get(456).set('on_hold', 1);
emails.get(456).save(...);
...
//...
// Remove an email on client and server (with an immediate AJAX request)
emails.get(789).destroy(...);
</div>
</div>
<div class="code panel" style="border-width: 1px;">
<div class="codeHeader panelHeader" style="border-bottom-width: 1px;">
**Update list of emails for contact #123 (delayed-save)**
</div>
<div class="codeContent panelContent">
// Update the list of email addresses for contact 123
var emails = new EmailCollection([], {
crmCriteria: {contact_id: 123}
});
emails.fetch(...);
...
// Add a new email on client (but don't send to server yet)
var email = new EmailModel({
contact_id: 123,
email: 'another-email@example.com'
});
emails.add(model);
// Update an email on client (but don't send to server yet)
emails.get(456).set('on_hold', 1);
// Remove an email on client (but don't send to server yet)
emails.get(789).setSoftDeleted(true);
...
// Send all changes to all emails to server (with one AJAX call)
emails.save(...);
// NOTE: Use this carefully. This will perform INSERTs, UPDATEs, and/or DELETEs
// to make the email list match on the client and server. The server will use
// an algorithm like this:
//
// 1. Accept list of records from client.
// 2. Query list of pre-existing emails on server (matching crmCriteria).
// 3. Identify records in BOTH client and server. UPDATE them.
// 4. Identify records in CLIENT but not server. INSERT them.
// 5. Identify records in SERVER but not client. DELETE them.
//
// This is generally appropriate when you know the client has the full,
// proper collection -- e.g. it's appropriate with the collection of "Email",
// "Phone", or "Address" records of one contact. However, it's not appropriate
// for a collection of "Activities" (because concurrent processes may add new
// activities that are unknown the client -- and those records shouldn't be
// deleted). If you have a use-case that needs a different / more nuanced
// reconciliation strategy, post to the forum to discuss.
</div>
</div>
```
Update list of emails for contact #123 (delayed-save)
```javascript
// Update the list of email addresses for contact 123
var emails = new EmailCollection([], {
crmCriteria: {contact_id: 123}
});
emails.fetch(...);
...
// Add a new email on client (but don't send to server yet)
var email = new EmailModel({
contact_id: 123,
email: 'another-email@example.com'
});
emails.add(model);
// Update an email on client (but don't send to server yet)
emails.get(456).set('on_hold', 1);
// Remove an email on client (but don't send to server yet)
emails.get(789).setSoftDeleted(true);
...
// Send all changes to all emails to server (with one AJAX call)
emails.save(...);
// NOTE: Use this carefully. This will perform INSERTs, UPDATEs, and/or DELETEs
// to make the email list match on the client and server. The server will use
// an algorithm like this:
//
// 1. Accept list of records from client.
// 2. Query list of pre-existing emails on server (matching crmCriteria).
// 3. Identify records in BOTH client and server. UPDATE them.
// 4. Identify records in CLIENT but not server. INSERT them.
// 5. Identify records in SERVER but not client. DELETE them.
//
// This is generally appropriate when you know the client has the full,
// proper collection -- e.g. it's appropriate with the collection of "Email",
// "Phone", or "Address" records of one contact. However, it's not appropriate
// for a collection of "Activities" (because concurrent processes may add new
// activities that are unknown the client -- and those records shouldn't be
// deleted). If you have a use-case that needs a different / more nuanced
// reconciliation strategy, post to the forum to discuss.
```
## Unit Tests
The CiviCRM Backbone plugins are tested with qUnit. To run the
unit-tests, use a web-browser to connect to a CiviCRM installation
("http://local.example.com") and request
"*http://local.example.com*/**civicrm/tests/qunit/crm-backbone**"
(`http://local.example.com`) and request the following:
`http://local.example.com/civicrm/tests/qunit/crm-backbone`
The source for the unit-tests are stored in "tests/qunit/crm-backbone"
(e.g.
<https://github.com/civicrm/civicrm-core/tree/master/tests/qunit/crm-backbone>).
The source for the unit-tests are stored in ["tests/qunit/crm-backbone"](https://github.com/civicrm/civicrm-core/tree/master/tests/qunit/crm-backbone).
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment