From 54cb3deb06ef9391aa59b0cd68266459f4892c1e Mon Sep 17 00:00:00 2001
From: Tim Otten <totten@civicrm.org>
Date: Tue, 16 Jul 2013 16:26:03 -0700
Subject: [PATCH] CRM-12923 - Move $.fn.crmContactField to core

----------------------------------------
* CRM-12923: Create HTML prototype of "Job Position" UI
  http://issues.civicrm.org/jira/browse/CRM-12923
---
 js/rest.js | 91 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 91 insertions(+)

diff --git a/js/rest.js b/js/rest.js
index 0cdb94f71c..83b34a833d 100644
--- a/js/rest.js
+++ b/js/rest.js
@@ -160,6 +160,15 @@ var CRM = CRM || {};
     return CRM.api.call(this, entity, action, params, options);
   };
 
+  /**
+   * FIXME: This function is not documented, is not used anywhere in the codebase, and doesn't
+   * clearly differentiate field elements which store the "contact id" versus the "contact label".
+   * My guess is that it's designed more for "quick-search" and less for "CRUD forms".
+   *
+   * @param params
+   * @param options
+   * @return {*}
+   */
   $.fn.crmAutocomplete = function (params, options) {
     if (typeof params == 'undefined') params = {};
     if (typeof options == 'undefined') options = {};
@@ -225,4 +234,86 @@ var CRM = CRM || {};
      });
    }
 
+  /**
+   * Setup a contact widget for use in CRUD forms. The form element stores a contact ID
+   * but displays a name/label.
+   *
+   * Usage:
+   *   <INPUT type="text" name="my_contact_id" value="123" />
+   *   <SCRIPT type="text/javascript">
+   *     $('[name=my_contact_id]').crmContactField();
+   *     $('[name=my_contact_id]').on('change', function(){
+   *       console.log("the new contact id is ", $(this).val());
+   *     });
+   *   </SCRIPT>
+   *
+   * Note: The given form element is the canonical representation of the selected contact-ID.
+   * To display/enter the contact by name, the contact-ID field will be hidden, and a helper
+   * widget will be inserted. The values will be synced between the two.
+   *
+   * Cases to consider/test:
+   *  - When initializing, the read the contact-ID and set the contact-label
+   *  - When unsetting(blanking) the contact-label, also unset (blank) the contact-ID
+   *  - If third party code updates the hidden value, then one must trigger a 'change'
+   *    event to update the visible widget.
+   */
+  $.fn.crmContactField = function() {
+    return this.each(function(){
+      var contactUrl = CRM.url('civicrm/ajax/rest', 'className=CRM_Contact_Page_AJAX&fnName=getContactList&json=1');
+      var hiddenEl = this;
+      var widgetEl = $('<input type="text" />');
+
+      var activeContactId = null;
+      var setContactId = function(newContactId) {
+        if (newContactId != $(hiddenEl).val()) {
+          $(hiddenEl).val(newContactId);
+          $(hiddenEl).trigger('change');
+        }
+        if (activeContactId != newContactId) {
+          activeContactId = newContactId;
+
+          if (activeContactId) {
+            // lookup the name
+            $(widgetEl).css({visibility: 'hidden'}); // don't allow input during ajax
+            $.ajax({
+              url     : contactUrl + '&id=' + newContactId,
+              async   : false,
+              success : function(html){
+                var htmlText = html.split( '|' , 2);
+                $(widgetEl).val(htmlText[0]);
+                $(widgetEl).css({visibility: 'visible'});
+              }
+            });
+          } else {
+            // there is no name to lookup - just show a blank
+            $(widgetEl).val('');
+          }
+        }
+      };
+
+      $(hiddenEl).after(widgetEl);
+      $(hiddenEl).hide();
+      $(widgetEl).autocomplete(contactUrl, {
+        width: 200,
+        selectFirst: false,
+        minChars: 1,
+        matchContains: true,
+        delay: 400
+      }).result(function(event, data) {
+          activeContactId = data[1];
+          setContactId(activeContactId);
+        }).bind('change blur', function() {
+          if (! $(widgetEl).val()) {
+            activeContactId = '';
+            setContactId(activeContactId);
+          }
+        });
+
+      $(hiddenEl).bind('change', function(){
+        setContactId($(this).val());
+      });
+      setContactId($(hiddenEl).val());
+    });
+  };
+
 })(jQuery, CRM);
-- 
2.25.1