Merge pull request #1205 from totten/master-backbone-findcreate

CRM-12943 - Add findCreate() helper

js/crm.backbone.js

@@ -161,6 +161,45 @@
     });
   };
 
+  /**
+   * Find a single record, or create a new record.
+   *
+   * @param Object options:
+   *   - CollectionClass: class
+   *   - crmCriteria: Object values to search/default on
+   *   - defaults: Object values to put on newly created model (if needed)
+   *   - success: function(model)
+   *   - error: function(collection, error)
+   */
+   CRM.Backbone.findCreate = function(options) {
+     options || (options = {});
+     var collection = new options.CollectionClass([], {
+       crmCriteria: options.crmCriteria
+     });
+     collection.fetch({
+      success: function(collection) {
+        if (collection.length == 0) {
+          var attrs = _.extend({}, collection.crmCriteria, options.defaults || {});
+          var model = collection._prepareModel(attrs, options);
+          options.success(model);
+        } else if (collection.length == 1) {
+          options.success(collection.first());
+        } else {
+          options.error(collection, {
+            is_error: 1,
+            error_message: 'Too many matches'
+          });
+        }
+      },
+      error: function(collection, errorData) {
+        if (options.error) {
+          options.error(collection, errorData);
+        }
+      }
+    });
+  };
+
+
   CRM.Backbone.Model = Backbone.Model.extend({
     /**
      * Return JSON version of model -- but only include fields that are

tests/qunit/crm-backbone/test.js

 /* ------------ Fixtures/constants ------------ */
 
 var VALID_CONTACT_ID = 3;
-var INVALID_CONTACT_ID = 'z';
+var MALFORMED_CONTACT_ID = 'z';
 
 var ContactModel = Backbone.Model.extend({});
 CRM.Backbone.extendModel(ContactModel, 'Contact');
@@ -61,7 +61,7 @@ asyncTest("fetch (ok)", function() {
 });
 
 asyncTest("fetch (error)", function() {
-  var c = new ContactModel({id: INVALID_CONTACT_ID});
+  var c = new ContactModel({id: MALFORMED_CONTACT_ID});
   c.fetch({
     success: onUnexpectedSuccess,
     error: function(model, error) {
@@ -212,7 +212,7 @@ asyncTest("fetch by crazy name (0 results)", function() {
 asyncTest("fetch by malformed ID (error)", function() {
   var c = new ContactCollection([], {
     crmCriteria: {
-      id: INVALID_CONTACT_ID
+      id: MALFORMED_CONTACT_ID
     }
   });
   c.fetch({
@@ -224,3 +224,53 @@ asyncTest("fetch by malformed ID (error)", function() {
   });
 });
 
+module('findCreate');
+
+asyncTest("findCreate by ID (1 result)", function() {
+  CRM.Backbone.findCreate({
+    CollectionClass: ContactCollection,
+    crmCriteria: {
+      id: VALID_CONTACT_ID
+    },
+    error: onUnexpectedError,
+    success: function(model) {
+      equal(model.get('id'), VALID_CONTACT_ID);
+      ok(model.get('contact_type') != '', 'Expected contact with valid type')
+      ok(model.get('id'), 'Expected contact with valid ID')
+      start();
+    }
+  });
+});
+
+asyncTest("findCreate by crazy name (0 results) - autocreate", function() {
+  CRM.Backbone.findCreate({
+    CollectionClass: ContactCollection,
+    crmCriteria: {
+      organization_name: 'asdf23vmlk2309lk2lkasdk-23ASDF32f'
+    },
+    defaults: {
+      contact_type: 'Organization'
+    },
+    error: onUnexpectedError,
+    success: function(model) {
+      equal(model.get('organization_name'), 'asdf23vmlk2309lk2lkasdk-23ASDF32f', 'Expected default values from crmCriteria');
+      equal(model.get('contact_type'), 'Organization', 'Expected default values from parameters');
+      ok(!model.get('id'), 'Expected contact without valid ID')
+      start();
+    }
+  });
+});
+
+asyncTest("findCreate by malformed ID (error)", function() {
+  CRM.Backbone.findCreate({
+    CollectionClass: ContactCollection,
+    crmCriteria: {
+      id: MALFORMED_CONTACT_ID
+    },
+    success: onUnexpectedSuccess,
+    error: function(collection, error) {
+      assertApiError(error);
+      start();
+    }
+  });
+});