CRM-12943 - Move Collection.fetchCreate() to CRM.Backbone.findCreate()

This may be a subtle point, but in the current use-cases, we don't really
have a "collection" that we're trying to maintain.  We're just using the
collection to facilitate the search.  If have this helper a method of the
collection, then there are design questions about how one uses the
collection (eg with repeated calls to fetchCreate), but that's all
extraneous.

----------------------------------------
* CRM-12943: Make HTML prototype of job UI functional
  http://issues.civicrm.org/jira/browse/CRM-12943

js/crm.backbone.js

@@ -144,41 +144,6 @@
       crmEntityName: CollectionClass.prototype.model.prototype.crmEntityName,
       toCrmCriteria: function() {
         return this.crmCriteria || {};
-      },
-
-      /**
-       * Find a single match, or create a (new) matching record. If a new record is created,
-       * it will be added to the collection but NOT saved.
-       *
-       * @param Object options:
-       *   - success: function(model)
-       *   - error: function(collection, error)
-       *   - defaults: Object values to put on newly created model (if needed)
-       */
-      fetchCreate: function(options) {
-        options || (options = {});
-        this.fetch({
-          success: function(collection) {
-            if (collection.length == 0) {
-              var attrs = _.extend({}, collection.crmCriteria, options.defaults || {});
-              var model = collection._prepareModel(attrs, options);
-              collection.add(model, 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);
-            }
-          }
-        });
       }
     });
     // Overrides - if specified in CollectionClass, replace
@@ -196,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

@@ -224,15 +224,14 @@ asyncTest("fetch by malformed ID (error)", function() {
   });
 });
 
-module('fetchCreate');
+module('findCreate');
 
-asyncTest("fetchCreate by ID (1 result)", function() {
-  var c = new ContactCollection([], {
+asyncTest("findCreate by ID (1 result)", function() {
+  CRM.Backbone.findCreate({
+    CollectionClass: ContactCollection,
     crmCriteria: {
       id: VALID_CONTACT_ID
-    }
-  });
-  c.fetchCreate({
+    },
     error: onUnexpectedError,
     success: function(model) {
       equal(model.get('id'), VALID_CONTACT_ID);
@@ -243,13 +242,12 @@ asyncTest("fetchCreate by ID (1 result)", function() {
   });
 });
 
-asyncTest("fetchCreate by crazy name (0 results) - autocreate", function() {
-  var c = new ContactCollection([], {
+asyncTest("findCreate by crazy name (0 results) - autocreate", function() {
+  CRM.Backbone.findCreate({
+    CollectionClass: ContactCollection,
     crmCriteria: {
       organization_name: 'asdf23vmlk2309lk2lkasdk-23ASDF32f'
-    }
-  });
-  c.fetchCreate({
+    },
     defaults: {
       contact_type: 'Organization'
     },
@@ -263,13 +261,12 @@ asyncTest("fetchCreate by crazy name (0 results) - autocreate", function() {
   });
 });
 
-asyncTest("fetchCreate by malformed ID (error)", function() {
-  var c = new ContactCollection([], {
+asyncTest("findCreate by malformed ID (error)", function() {
+  CRM.Backbone.findCreate({
+    CollectionClass: ContactCollection,
     crmCriteria: {
       id: MALFORMED_CONTACT_ID
-    }
-  });
-  c.fetch({
+    },
     success: onUnexpectedSuccess,
     error: function(collection, error) {
       assertApiError(error);