Two Mice and a Strawberry

CiviCRM: “Individual Prefix” field as auto-complete text input

Allen Shaw — Tue, 20 Apr 2010 01:45:00 +0000

Note: CiviCRM is a fantastic open-source software package for managing an organization’s contacts, targeted specifically at non-profit organizations. You can learn more about it at CiviCRM.org.

I recently had to modify CiviCRM to support a specific use case for a client. In this project I needed to allow the user to enter anything in the Individual Prefix field, rather than choosing from a list of options. The client in this case was very sensitive about presenting the individual’s honorific precisely as the individual wants, so that “Dr.,” “Rev. Dr.,” and “Most Rt. Rev. Dr.” should all be possible, along with anything else the user might want to enter.

To illustrate the scope of issue: out of the aprox. 20K records in the client’s existing database, there were over 400 distinct values for this field. A select list that long is unwieldy in numerous ways, so we knew we’d have to come up with a solution before importing all those records to CiviCRM.

What I really wanted — and what the client needed — was to present the “Individual Prefix” field as a text input that offers type-ahead auto-complete for a short list of preferred options, but still allows the user to enter whatever they want.

My solution was to implement a custom module which would use two CiviCRM hooks, hook_civicrm_buildForm and hook_civicrm_postProcess, to modify the field display and processing, and add a little custom JavaScript to provide the type-ahead effect.

A quick check on the incredibly helpful, active, and responsive CiviCRM Forums confirmed that my intended solution was probably a good one, so I created the module below. Skip ahead if you just want the code. In the mean time, a little explanation on why it does what it does:

In CiviCRM, the individual prefix is stored as an integer, not as text. This number is value matching the unique ID of an item in CiviCRM’s list of individual prefixes, which are normally configured manually at Administer CiviCRM > Option Lists > Individual Prefixes. Naturally CiviCRM already has a simple way of translating between this stored numeric value and the text that a user sees or enters; in the form for editing an individual contact, that translation happens with an HTML element. That text field must be displayed in the right place in the form, and it must display the correct value when the form is first opened if the user is editing an existing contact. When the form is submitted, the module has to accept whatever text the user has entered and match it to one of the items in CiviCRM’s list of individual prefixes — or, if no match exists, it has to add an item to the list and then use that value — and store the correct numeric value as the contact’s prefix.

Finally, at the client’s request, this text field needs to offer some kind of type-ahead auto-complete functionality to steer the user toward a short list of common prefixes. This is accomplished with a simple JavaScript function triggered by the onKeyUp event.

The module

Here, then is the module. I’ve included some lengthy notes in the code comments, explaining some of the unexpected turns I had to take to get the effect I was after. Jump below to see the JavaScript.


/**
 * Project:     TwoMice CiviCRM modifications 
 * File: tmcivicrm.module
 */
 
 
/**
 * Implementation of hook_civicrm_buildForm()
 */
function tmcivicrm_civicrm_buildForm($formName, &$form) {
 
    if (
        $formName == 'CRM_Contact_Form_Contact' &&
        $form->getElementType('prefix_id') == 'select'
    ) {
        /* For this form, we'll remove the existing ); we have no need of it.
        $form->removeElement('prefix_id');
 
        /* Add a couple of new fields for the template.  Be sure to assign an
         * "ID" attribute, so they can be more easily accessed via JQuery in the
         * template.
         */
 
        // Add a new prefix_id field, this time a text input.
        $form->addElement(
            'text', 'prefix_id', 'Title', array('id'=>'prefix_id')
        );
        /* Set the value to any existing NUMERIC prefix value.  When the form is
        submitted, CiviCRM will be expecting this value as an integer and will
        use it to record the Individual Prefix.  See
        tmcivicrm_civicrm_postProcess() for how this works and how it is
        reconciled with what the user may type in. */
        $form->getElement('prefix_id')->setValue($value);        
 
        /* Add a hidden field, also containing any existing prefix_id text; We
        will use this in postProcess to check for changed values. */
        $form->addElement(
            'hidden', 'hidden_prefix_id_text', NULL,
            array('id'=>'hidden_prefix_id_text')
        );
        $form->getElement('hidden_prefix_id_text')->setValue($textVal);
 
        /* The ony form element we're NOT adding here is the one the user will
         * actually see.  Instead of adding it here, we use JQuery within the
         * template to append it in the correct location in the form.  This is
         * the only way we can do it without changing the template itself, since
         * the template is hard-coded to put in only specific form elements at
         * specific spots. Any new form elements we add here -- other than
         * hidden inputs -- will not make it into the template's HTML output.
         * See the template JavaScript for the code that inserts this element.
         */
         // Insert the JavaScript file that will do the above-described magic.
        drupal_add_js(
            drupal_get_path('module', 'tmcivicrm') .'/modules/tmcivicrm/js/Contact_Form_Contact.js'
        );
    }
}
 
/**
 * Implementation of hook_civicrm_postProcess()
 *
 * This function performs additional handling of form inputs after CiviCRM has
processed the form.
 */
function tmcivicrm_civicrm_postProcess($formName, &$form) {
 
    if ($formName == 'CRM_Contact_Form_Contact') {
 
        /* Get the submitted prefix text and any existing prefix text, and
        compare to see if the prefix has changed. */
        $prefix = CRM_Utils_Request::retrieve(
            'prefix_id_text', 'String', $form, false, null, 'REQUEST'
        );
        $originalPrefix = CRM_Utils_Request::retrieve(
            'hidden_prefix_id_text', 'String', $form, false, null,
            'REQUEST'
        );
 
        /* If the prefix has changed, we'll need to do some work to update it.
         * If it hasn't changed, it's been saved correctly already, because
         * the form contained our the numeric value of the existing prefix in
         * the element prefix_id (added in tmcivicrm_civicrm_buildForm()).
         */
        if ($prefix <> $originalPrefix) {
            /* Prefix has been changed. Get the correct numeric value for the
             * new prefix (creating a new Individual Prefix option list item if
             * necessary), and save the value in the contact record.
             */
 
            // We'll need this path below for including some files
            global $civicrm_root;
 
            /* Search for the numeric value in case the option list item already
            exists, and store that as the new prefix numeric value. */
            $prefixValue = array_search(
                $prefix ,
                CRM_Core_PseudoConstant::individualPrefix()
            );
 
            /* If no matching option list item was found, we need to add the new
             * prefix to the Individual Prefix option list.
             */
            if (!$prefixValue) {
                /* We'll use CiviCRM BAO functions to add the new option.  To be
                sure we're adding to the correct option list (Individual
                Prefixes and not some other option list), fetch the option group
                ID from the database. */
                $group = new CRM_Core_BAO_OptionGroup;
                $group->name = 'individual_prefix';
                $group->find(true);
 
                // Record the correct option group ID
                $optionGroupId = $group->id;
 
                // Prep the correct parameters for the new option list item
                $optionParams = array(
                    'label'=>$prefix, 'name'=>$prefix, 'is_active'=>true
                );
                /* We'll also need these parameters to create the item in the
                correct option list: */
                $groupParams  =array('id'=>$optionGroupId);
 
                /* Now use all those parameters and the Option Value functions
                to add the item to the list. */
                $action = CRM_Core_Action::ADD;
                $option = CRM_Core_OptionValue::addOptionValue(
                    $optionParams, $groupParams, $action, $optionValueID
                );
                /* $option now contains the newly added item, with its numeric
                value in $option->value.  Store that as the correct prefix
                value. */
                $prefixValue = $option->value;
 
                /* Now that we've added a new value to the Individual Prefix
                 * option list, we need to refresh CiviCRM's cache of possible
                 * Individual Prefix values.  This cache is built once per page,
                 * and it's already been built by the time this hook is fired.
                 * We need to refresh it so that the newly created prefix can be
                 * found and used in the contact's Display Name when we update
                 * the contact record below.
                 */
                require_once($civicrm_root .
                    DIR_SEP . 'CRM' .
                    DIR_SEP . 'Core' .
                    DIR_SEP . 'PseudoConstant.php'
                );
                CRM_Core_PseudoConstant::flush('individualPrefix');
            }
 
            /* By now, one way or another, we have a numeric value in
             * $prefixValue. Update the individual record using that value.
             */
            $params = array(
                'contact_id'    => $form->_contactId,
                'contact_type'  => 'Individual',
                'prefix_id'     => $prefixValue
            );
 
            require_once(
                $civicrm_root .
                DIR_SEP . 'api' .
                DIR_SEP . 'v2' .
                DIR_SEP . 'Contact.php'
            );
            $ret = civicrm_contact_add($params);
            if ($ret['is_error']) {
                drupal_set_message(t('Could not save changed Individual Prefix.
                    Error: '. $ret['error_message']), 'error');
            }
        } else {
            /* Prefix is unchanged. Nothing to do, as the value will have been
            passed in from the form in prefix_id field. */
        }
    }
}

The JavaScript

The module above makes use of Drupal’s drupal_add_js() function to add the following JavaScript file. Thanks to hershel’s comment for pointing out this method as a way to insert JavaScript code without relying on custom templates techniques. As far as possible I’ve tried to avoid using custom templates in order to preserve forward compatibility for future CiviCRM releases.

This JavaScript code provides both the type-ahead effect this field requires and some small but important data processing when the form is submitted. See the comments for detailed explanation of some points.

<script type="text/javascript">
    /* Since we need our custom text element to be in exactly the right
     * place in the form, namely in the same place as the existing prefix
     * element, we add it here using JQuery's .append() method, by appending
     * it to the parent of the prefix element.  We give it the same value
     * as the value of the hidden_prefix_id element (see
     * tmcivicrm_civicrm_buildForm() in tmcivicrm.module).
     */
    $("#prefix_id").parent().append(
        ' +
        'id="prefix_id_text" autocomplete="off" value="' +
        $('#hidden_prefix_id_text').val() +'">'
    );
 
    // Add an onKeyUp event handler to the new field.
    $("#prefix_id_text").keyup(function(event){
            prefix_auto_complete(this,event)
    });
 
    /* Finally, hide (but don't remove) the prefix field, which
     is actually a text field containing the numeric value of any existing
     prefix (see tmcivicrm_civicrm_buildForm() in tmcivicrm.module).
     CiviCRM will process this value when the form is submitted, as
     explained in tmcivicrm_civicrm_postProcess() in tmcivicrm.module)  */
    $("#prefix_id").css('display', 'none');
 
    /* I had this function lying around from previous projects.  How it works
    is not especially relevant to this article, but I leave it here for your 
    reference. */
    function prefix_auto_complete(element, event) {
        titles = new Array(
            "Rev.", "Dr.", "Prof.", "Father", "Mr.", "Mrs.", "Ms.", "Hon.",
            "Ven.", "H.E.", "Bishop", "Sheikh", "Imam"
        );
        if (element.value == "") return 0;
 
        /* if it's a backspace (keycode=8), just return (we do nothing on a
        backspace)*/
        if (event.keyCode == 8 ){
            return 0;
        }
 
        /* Find out if element has the function createTextRange (otherwise we
        should use setSelectionRange()) */
        if (element.createTextRange) {
            useTextRange = true;
        } else {
            useTextRange = false;
        }
 
        /* set up some temp variables
         */
        origValue = element.value;
 
        // if the box is empty, just return.
        if (origValue == "")return 0;
 
        // cycle through each element of Array titles() until we get a match:
        for (n=0; n < titles.length; n++){
            title = titles[n];
            count = 0;
            for (i = 0; i < origValue.length; i++){
                if (
                    title.toLowerCase().charAt(i) ==
                    origValue.toLowerCase().charAt(i)
                ){
                    count++
                }
            }
 
            /* if count == origValue.length, we know all the characters matched,
            so we have a match! */
            if (count == origValue.length){
 
                /* find out how many characters remain to be filled in by
                auto-completion */
                diff = title.length - origValue.length;
                if (diff <= 0) break;
 
                /* remainingChars is going to be a string of the remaining
                characters to be filled in */
                remainingChars = "";
                for (i=0; i < title.length; i++){
                    if (i >= origValue.length) {
                        remainingChars += title.charAt(i);
                    }
                }
                element.backspace = true;
 
                if (useTextRange) {
                // If useTextRange (Internet Explorer, et al)
                    var textRange = element.createTextRange();
 
                    /* truncate the matching array item to the length of what
                    was typed */
                    textRange.text=title.substr(0,textRange.text.length);
 
                    // then we add remainingChars, select it, and we're done!
                    textRange.text += remainingChars;
                    textRange.findText(remainingChars,diff*-2);
                    textRange.select();
                    return 0;
                } else {
                // (Mozilla, et al)
                    element.value =
                        title.substr(0,origValue.length) +
                        remainingChars
                    element.setSelectionRange(
                        origValue.length,
                        remainingChars.length + origValue.length
                    );
                    return 0;
                }
            }
        }
        element.backspace = false;
        return 0;
    }
script>

Conclusion

This solution is working well for me now. I’m sure there are ways to improve it. Since I’m very new to CiviCRM, I look forward to any suggestions for improvements in the code above or in the general approach.

Twitter for Wordpress patch

Allen Shaw — Tue, 21 Jul 2009 15:48:16 +0000

I recently found a bug in the very cool Twitter for Wordpress plugin (v.1.9.5), published by Rick over at Rick’s Hideout. Here’s a fix for it, which Rick has already incorporated into the plugin.

The problem is that, in this version, the “Discover Hyperlinks” feature does not find all the hyperlinks in a tweet like this one:

http://example.com/example has great examples (also more here: http://example.com/more)

The problem is with the regex pattern in the hyperlinks() function, which looks for a space character (\s) at the beginning and at the end a space character, comma, period, etc. ([\s|\.|\,]). The tweet above has two links, but the first one doesn’t match since it starts from the first character of the tweet and so has no leading space character; and the second one doesn’t match since it is followed by a close-parentheses.

A better way to do it would be to use the \b meta-character to look for a word boundary. Below is the hyperlinks() function re-written that way.

function hyperlinks($text) { // match protocol://address/path/file.extension?some=variable&another=asf% $text = preg_replace("/\b([a-zA-Z]+:\/\/[a-z][a-z0-9\_\.\-]*[a-z]{2,6}[a-zA-Z0-9\/\*\-\?\&\%]*)\b/i","$1", $text); // match www.something.domain/path/file.extension?some=variable&another=asf% $text = preg_replace("/\b(www\.[a-z][a-z0-9\_\.\-]*[a-z]{2,6}[a-zA-Z0-9\/\*\-\?\&\%]*)\b/i","$1", $text); // match name@address $text = preg_replace("/\b([a-zA-Z][a-zA-Z0-9\_\.\-]*[a-zA-Z]*\@[a-zA-Z][a-zA-Z0-9\_\.\-]*[a-zA-Z]{2,6})\b/i","$1", $text); return $text; }

Thanks to Rick for incorporating this fix into the next version (1.9.6) of the plugin.

Phone Toggler for Google Voice

Allen Shaw — Thu, 16 Jul 2009 19:37:33 +0000

Here’s a PHP/curl hack that lets me manage my Google Voice phones easily.

Google Voice is great. One number for all my contacts, and I can answer an incoming call on my cell when I’m out and about, or penny-pinch my minutes by taking it on the office phone when I’m in. But having an incoming call ring on all phones is not enough for me.

I don’t want it to ring at my home office unless I’m there, because who knows who’ll answer it before I do, and then I’ve lost the call. I want it to ring on only one phone at a time, and it has to be the right phone, so I can save minutes where possible, but never risk the call landing somewhere I’m not.

The problem is that enabling and disabling phones in the GV web interface is so tedious, I don’t want to do that every time I enter or leave the office.

To solve this tedium, I hacked up a quick PHP script using CURL to sign in to GV, enable the phone I want, and disable all others. One quick line at the command prompt, and I’m ready to go:

$ togglePhones 1

enables my cell phone and disables my home phone, while

$ togglePhones 2

does the reverse.

Download the script here for your own use. This is a command-line script. Call it without arguments to get a list of options. Edit the file directly to configure your GV username and password.

Thanks to tylerhall, Michal Migurski, and vladimir_wof_nikolaich_dot_ru for writing the bulk of the code in this script (see the code comments for credits).

GoDaddy rejecting tons of false positive spam/virii

Allen Shaw — Wed, 29 Apr 2009 12:25:44 +0000

Since I started using GoDaddy to host email for this site, I’ve had several users report several times that mail they send me is being bounced with this message: “554 The message was rejected because it contains prohibited virus or spam content”. I struggled to understand it until I found several articles (here, here, and here, for starters) pointing out that GoDaddy is wrongly blocking mail if it contains links to perfectly legitimate sites. Obviously this is completely braindead.

As far as I know, I’m the first GoDaddy customer to complain publicly about this. This is probably because professionals in the world of hosting and web apps will usually not touch GoDaddy with a ten foot pole. I thought I’d give them a shot. It’s not looing good.

Let’s see if complaints from their own customers will make a difference. If you’re a GoDaddy customer, read the articles above, then write GoDaddy now to tell them how ridiculous their policy is. Other options for mail hosting are just a few clicks away.

Vodez-better component for Joomla! 1.5 Legacy

Allen Shaw — Tue, 21 Apr 2009 20:09:31 +0000

Emir Sakic’s “Vodes” component for Joomla! was just what I needed — almost. My client needs configurable options without editing code files. I’ve extended Emir’s work into Vodez-better, which adds configurable options for currencies, price packages, and gift credits. GPL 3.0 [Download]