2 var CRM
= (window
.CRM
) ? (window
.CRM
) : (window
.CRM
= {});
3 if (!CRM
.Backbone
) CRM
.Backbone
= {};
6 * Backbone.sync provider which uses CRM.api() for I/O.
7 * To support CRUD operations, model classes must be defined with a "crmEntityName" property.
8 * To load collections using API queries, set the "crmCriteria" property or override the
9 * method "toCrmCriteria".
11 * @param method Accepts normal Backbone.sync methods; also accepts "crm-replace"
14 * @see tests/qunit/crm-backbone
16 CRM
.Backbone
.sync = function(method
, model
, options
) {
17 var isCollection
= _
.isArray(model
.models
);
21 success: function(data
) {
23 options
.success(_
.toArray(data
.values
));
25 error: function(data
) {
26 // CRM.api displays errors by default, but Backbone.sync
27 // protocol requires us to override "error". This restores
28 // the default behavior.
29 $().crmError(data
.error_message
, ts('Error'));
35 CRM
.api(model
.crmEntityName
, model
.toCrmAction('get'), model
.toCrmCriteria(), apiOptions
);
37 // replace all entities matching "x.crmCriteria" with new entities in "x.models"
39 var params
= this.toCrmCriteria();
41 params
.values
= this.toJSON();
42 CRM
.api(model
.crmEntityName
, model
.toCrmAction('replace'), params
, apiOptions
);
45 apiOptions
.error({is_error
: 1, error_message
: "CRM.Backbone.sync(" + method
+ ") not implemented for collections"});
49 // callback options to pass to CRM.api
51 success: function(data
) {
53 var values
= _
.toArray(data
['values']);
54 if (data
.count
== 1) {
55 options
.success(values
[0]);
58 data
.error_message
= ts("Expected exactly one response");
59 apiOptions
.error(data
);
62 error: function(data
) {
63 // CRM.api displays errors by default, but Backbone.sync
64 // protocol requires us to override "error". This restores
65 // the default behavior.
66 $().crmError(data
.error_message
, ts('Error'));
71 case 'create': // pass-through
73 var params
= model
.toJSON();
74 params
.options
|| (params
.options
= {});
75 params
.options
.reload
= 1;
76 if (!model
._isDuplicate
) {
77 CRM
.api(model
.crmEntityName
, model
.toCrmAction('create'), params
, apiOptions
);
79 CRM
.api(model
.crmEntityName
, model
.toCrmAction('duplicate'), params
, apiOptions
);
84 var apiAction
= (method
== 'delete') ? 'delete' : 'get';
85 var params
= model
.toCrmCriteria();
87 apiOptions
.error({is_error
: 1, error_message
: 'Missing ID for ' + model
.crmEntityName
});
90 CRM
.api(model
.crmEntityName
, model
.toCrmAction(apiAction
), params
, apiOptions
);
93 apiOptions
.error({is_error
: 1, error_message
: "CRM.Backbone.sync(" + method
+ ") not implemented for models"});
99 * Connect a "model" class to CiviCRM's APIv3
103 * var ContactModel = Backbone.Model.extend({});
104 * CRM.Backbone.extendModel(ContactModel, "Contact");
107 * c = new ContactModel({id: 3});
111 * @param Class ModelClass
112 * @param string crmEntityName APIv3 entity name, such as "Contact" or "CustomField"
113 * @see tests/qunit/crm-backbone
115 CRM
.Backbone
.extendModel = function(ModelClass
, crmEntityName
) {
116 // Defaults - if specified in ModelClass, preserve
117 _
.defaults(ModelClass
.prototype, {
118 crmEntityName
: crmEntityName
,
119 crmActions
: {}, // map: string backboneActionName => string serverSideActionName
120 toCrmAction: function(action
) {
121 return this.crmActions
[action
] ? this.crmActions
[action
] : action
;
123 toCrmCriteria: function() {
124 return (this.get('id')) ? {id
: this.get('id')} : {};
126 duplicate: function() {
127 var newModel
= new ModelClass(this.toJSON());
128 newModel
._isDuplicate
= true;
129 if (newModel
.setModified
) newModel
.setModified();
130 newModel
.listenTo(newModel
, 'sync', function(){
131 // may get called on subsequent resaves -- don't care!
132 delete newModel
._isDuplicate
;
137 // Overrides - if specified in ModelClass, replace
138 _
.extend(ModelClass
.prototype, {
139 sync
: CRM
.Backbone
.sync
144 * Configure a model class to track whether a model has unsaved changes.
147 * - setModified() - flag the model as modified/dirty
148 * - isSaved() - return true if there have been no changes to the data since the last fetch or save
150 * - saved(object model, bool is_saved) - triggered whenever isSaved() value would change
152 * Note: You should not directly call isSaved() within the context of the success/error/sync callback;
153 * I haven't found a way to make isSaved() behave correctly within these callbacks without patching
154 * Backbone. Instead, attach an event listener to the 'saved' event.
158 CRM
.Backbone
.trackSaved = function(ModelClass
) {
159 // Retain references to some of the original class's functions
160 var Parent
= _
.pick(ModelClass
.prototype, 'initialize', 'save', 'fetch');
163 var onSyncSuccess = function() {
164 this._modified
= false;
165 if (this._oldModified
.length
> 0) {
166 this._oldModified
.pop();
168 this.trigger('saved', this, this.isSaved());
170 var onSaveError = function() {
171 if (this._oldModified
.length
> 0) {
172 this._modified
= this._oldModified
.pop();
173 this.trigger('saved', this, this.isSaved());
177 // Defaults - if specified in ModelClass, preserve
178 _
.defaults(ModelClass
.prototype, {
179 isSaved: function() {
180 var result
= !this.isNew() && !this.isModified();
183 isModified: function() {
184 return this._modified
;
186 _saved_onchange: function(model
, options
) {
187 if (options
.parse
) return;
188 // console.log('change', model.changedAttributes(), model.previousAttributes());
191 setModified: function() {
192 var oldModified
= this._modified
;
193 this._modified
= true;
195 this.trigger('saved', this, this.isSaved());
200 // Overrides - if specified in ModelClass, replace
201 _
.extend(ModelClass
.prototype, {
202 initialize: function(options
) {
203 this._modified
= false;
204 this._oldModified
= [];
205 this.listenTo(this, 'change', this._saved_onchange
);
206 this.listenTo(this, 'error', onSaveError
);
207 this.listenTo(this, 'sync', onSyncSuccess
);
208 if (Parent
.initialize
) {
209 return Parent
.initialize
.apply(this, arguments
);
213 // we'll assume success
214 this._oldModified
.push(this._modified
);
215 return Parent
.save
.apply(this, arguments
);
218 this._oldModified
.push(this._modified
);
219 return Parent
.fetch
.apply(this, arguments
);
225 * Configure a model class to support client-side soft deletion.
226 * One can call "model.setDeleted(BOOLEAN)" to flag an entity for
227 * deletion (or not) -- however, deletion will be deferred until save()
231 * setSoftDeleted(boolean) - flag the model as deleted (or not-deleted)
232 * isSoftDeleted() - determine whether model has been soft-deleted
234 * softDelete(model, is_deleted) -- change value of is_deleted
238 CRM
.Backbone
.trackSoftDelete = function(ModelClass
) {
239 // Retain references to some of the original class's functions
240 var Parent
= _
.pick(ModelClass
.prototype, 'save');
242 // Defaults - if specified in ModelClass, preserve
243 _
.defaults(ModelClass
.prototype, {
244 is_soft_deleted
: false,
245 setSoftDeleted: function(is_deleted
) {
246 if (this.is_soft_deleted
!= is_deleted
) {
247 this.is_soft_deleted
= is_deleted
;
248 this.trigger('softDelete', this, is_deleted
);
249 if (this.setModified
) this.setModified(); // FIXME: ugly interaction, trackSoftDelete-trackSaved
252 isSoftDeleted: function() {
253 return this.is_soft_deleted
;
257 // Overrides - if specified in ModelClass, replace
258 _
.extend(ModelClass
.prototype, {
259 save: function(attributes
, options
) {
260 if (this.isSoftDeleted()) {
261 return this.destroy(options
);
263 return Parent
.save
.apply(this, arguments
);
270 * Connect a "collection" class to CiviCRM's APIv3
272 * Note: the collection supports a special property, crmCriteria, which is an array of
273 * query options to send to the API.
277 * var ContactModel = Backbone.Model.extend({});
278 * CRM.Backbone.extendModel(ContactModel, "Contact");
279 * var ContactCollection = Backbone.Collection.extend({
280 * model: ContactModel
282 * CRM.Backbone.extendCollection(ContactCollection);
284 * // Use class (with passive criteria)
285 * var c = new ContactCollection([], {
286 * crmCriteria: {contact_type: 'Organization'}
289 * c.get(123).set('property', 'value');
290 * c.get(456).setDeleted(true);
293 * // Use class (with active criteria)
294 * var criteriaModel = new SomeModel({
295 * contact_type: 'Organization'
297 * var c = new ContactCollection([], {
298 * crmCriteriaModel: criteriaModel
301 * c.get(123).set('property', 'value');
302 * c.get(456).setDeleted(true);
307 * @param Class CollectionClass
308 * @see tests/qunit/crm-backbone
310 CRM
.Backbone
.extendCollection = function(CollectionClass
) {
311 var origInit
= CollectionClass
.prototype.initialize
;
312 // Defaults - if specified in CollectionClass, preserve
313 _
.defaults(CollectionClass
.prototype, {
314 crmEntityName
: CollectionClass
.prototype.model
.prototype.crmEntityName
,
315 crmActions
: {}, // map: string backboneActionName => string serverSideActionName
316 toCrmAction: function(action
) {
317 return this.crmActions
[action
] ? this.crmActions
[action
] : action
;
319 toCrmCriteria: function() {
320 return (this.crmCriteria
) ? _
.extend({}, this.crmCriteria
) : {};
324 * Get an object which represents this collection's criteria
325 * as a live model. Any changes to the model will be applied
326 * to the collection, and the collection will be refreshed.
328 * @param criteriaModelClass
330 setCriteriaModel: function(criteriaModel
) {
331 var collection
= this;
332 this.crmCriteria
= criteriaModel
.toJSON();
333 this.listenTo(criteriaModel
, 'change', function() {
334 collection
.crmCriteria
= criteriaModel
.toJSON();
335 collection
.debouncedFetch();
339 debouncedFetch
: _
.debounce(function() {
340 this.fetch({reset
: true});
344 * Reconcile the server's collection with the client's collection.
345 * New/modified items from the client will be saved/updated on the
346 * server. Deleted items from the client will be deleted on the
349 * @param Object options - accepts "success" and "error" callbacks
351 save: function(options
) {
352 options
|| (options
= {});
353 var collection
= this;
354 var success
= options
.success
;
355 options
.success = function(resp
) {
356 // Ensure attributes are restored during synchronous saves.
357 collection
.reset(resp
, options
);
358 if (success
) success(collection
, resp
, options
);
359 // collection.trigger('sync', collection, resp, options);
361 wrapError(collection
, options
);
363 return this.sync('crm-replace', this, options
)
366 // Overrides - if specified in CollectionClass, replace
367 _
.extend(CollectionClass
.prototype, {
368 sync
: CRM
.Backbone
.sync
,
369 initialize: function(models
, options
) {
370 options
|| (options
= {});
371 if (options
.crmCriteriaModel
) {
372 this.setCriteriaModel(options
.crmCriteriaModel
);
373 } else if (options
.crmCriteria
) {
374 this.crmCriteria
= options
.crmCriteria
;
376 if (options
.crmActions
) {
377 this.crmActions
= _
.extend(this.crmActions
, options
.crmActions
);
380 return origInit
.apply(this, arguments
);
385 // filter models list, excluding any soft-deleted items
386 this.each(function(model
) {
387 // if model doesn't track soft-deletes
388 // or if model tracks soft-deletes and wasn't soft-deleted
389 if (!model
.isSoftDeleted
|| !model
.isSoftDeleted()) {
390 result
.push(model
.toJSON());
399 * Find a single record, or create a new record.
401 * @param Object options:
402 * - CollectionClass: class
403 * - crmCriteria: Object values to search/default on
404 * - defaults: Object values to put on newly created model (if needed)
405 * - success: function(model)
406 * - error: function(collection, error)
408 CRM
.Backbone
.findCreate = function(options
) {
409 options
|| (options
= {});
410 var collection
= new options
.CollectionClass([], {
411 crmCriteria
: options
.crmCriteria
414 success: function(collection
) {
415 if (collection
.length
== 0) {
416 var attrs
= _
.extend({}, collection
.crmCriteria
, options
.defaults
|| {});
417 var model
= collection
._prepareModel(attrs
, options
);
418 options
.success(model
);
419 } else if (collection
.length
== 1) {
420 options
.success(collection
.first());
422 options
.error(collection
, {
424 error_message
: 'Too many matches'
428 error: function(collection
, errorData
) {
430 options
.error(collection
, errorData
);
437 CRM
.Backbone
.Model
= Backbone
.Model
.extend({
439 * Return JSON version of model -- but only include fields that are
440 * listed in the 'schema'.
444 toStrictJSON: function() {
445 var schema
= this.schema
;
446 var result
= this.toJSON();
447 _
.each(result
, function(value
, key
) {
454 setRel: function(key
, value
, options
) {
455 this.rels
= this.rels
|| {};
456 if (this.rels
[key
] != value
) {
457 this.rels
[key
] = value
;
458 this.trigger("rel:" + key
, value
);
461 getRel: function(key
) {
462 return this.rels
? this.rels
[key
] : null;
466 CRM
.Backbone
.Collection
= Backbone
.Collection
.extend({
468 * Store 'key' on this.rel and automatically copy it to
473 * @param initialModels
475 initializeCopyToChildrenRelation: function(key
, value
, initialModels
) {
476 this.setRel(key
, value
, {silent
: true});
477 this.on('reset', this._copyToChildren
, this);
478 this.on('add', this._copyToChild
, this);
480 _copyToChildren: function() {
481 var collection
= this;
482 collection
.each(function(model
) {
483 collection
._copyToChild(model
);
486 _copyToChild: function(model
) {
487 _
.each(this.rels
, function(relValue
, relKey
) {
488 model
.setRel(relKey
, relValue
, {silent
: true});
491 setRel: function(key
, value
, options
) {
492 this.rels
= this.rels
|| {};
493 if (this.rels
[key
] != value
) {
494 this.rels
[key
] = value
;
495 this.trigger("rel:" + key
, value
);
498 getRel: function(key
) {
499 return this.rels
? this.rels
[key
] : null;
504 CRM.Backbone.Form = Backbone.Form.extend({
505 validate: function() {
506 // Add support for form-level validators
507 var errors = Backbone.Form.prototype.validate.apply(this, []) || {};
509 if (this.validators) {
510 _.each(this.validators, function(validator) {
511 var modelErrors = validator(this.getValue());
513 // The following if() has been copied-pasted from the parent's
514 // handling of model-validators. They are similar in that the errors are
515 // probably keyed by field names... but not necessarily, so we use _others
518 var isDictionary = _.isObject(modelErrors) && !_.isArray(modelErrors);
520 //If errors are not in object form then just store on the error object
522 errors._others = errors._others || [];
523 errors._others.push(modelErrors);
526 //Merge programmatic errors (requires model.validate() to return an object e.g. { fieldKey: 'error' })
528 _.each(modelErrors, function(val, key) {
529 //Set error on field if there isn't one already
530 if (self.fields[key] && !errors[key]) {
531 self.fields[key].setError(val);
536 //Otherwise add to '_others' key
537 errors._others = errors._others || [];
540 errors._others.push(tmpErr);
548 return _.isEmpty(errors) ? null : errors;
553 // Wrap an optional error callback with a fallback error event.
554 var wrapError = function (model
, options
) {
555 var error
= options
.error
;
556 options
.error = function(resp
) {
557 if (error
) error(model
, resp
, options
);
558 model
.trigger('error', model
, resp
, options
);