How to Customize CiviCRM Pages with jQuery

There are three ways one can customize the look of CiviCRM pages:

1. Customizing CiviCRM templates
2. Custom CSS in a Joomla! template or Drupal theme
3. Custom jQuery code

In this post we will review them and provide a few examples of the most complicated method, jQuery manipulation.

Customizing CiviCRM templates

This method is described in depth on our wiki under Theming CiviCRM and the subpages therein.

The advantage of this method is that it is fairly easy to make simple changes. The disadvantage is that upgrades may significantly change the core templates and thus require one to redo the customizations “from scratch."

Custom CSS in a Joomla! template or Drupal theme

If your site uses a custom template or theme, then using normal CSS rules, one can fairly simply override the core CiviCRM CSS rules and replace them with your own custom ones.

The advantage of this method is that it is fairly easy to make simple changes. I am not aware of any particular disadvantages of this method and in fact whenever it's feasible, this is the method I would recommend.

Custom jQuery code

There are some customizations which can not be done via CSS, or which can be done via a custom CiviCRM template, but are quite difficult and there are others which are simply impossible to do purely via a CiviCRM template change. In many instances, however, such customizations can be safely implemented via jQuery.

The first step is to put a jQuery file onto your site. For Joomla! sites see Adding Javascript and for Drupal sites see Adding JavaScript to your theme or module and Working with JavaScript and jQuery. There may be other ways to add a JS file to a Joomla! site and it may be possible to achieve the functionality described below with Mootools (which ships with Joomla!). I will leave it up to any Joomla! or Mootools gurus to add their replies regarding such below.

Once the file is added to the site, now we just put in it whatever DOM manipulation we want. We will examine a few examples here and the concept will hopefully be clear.

Let's start with a simple example. If one has an event page with a long text and map etc. the “Register Now" button may only be found after scrolling down a bit. If a user comes to the page already intending to register, it would be easier for him to have that button right at the top of the page. To move this button we simply use Firebug in Firefox to find the ids or classes of the relevant items, in this case, the button itself and the event description section at the top. Then we move the button like this:


if (Drupal.jsEnabled) {
$(document).ready(function () {
$('div.event_description-section').prepend($('div.register_link-section'));
});
}


In actuality only the middle line interests us, because the rest is just a wrapper to have the code executed in the correct environment. We will focus now on just that code, which is what does the work. This one line is not actually correct, however, because while it did put a button at the top, it removed the button from the bottom and really is the equivalent of this line, i.e. with the remove function:


$('div.event_description-section').prepend($('div.register_link-section').remove());


What we want is to clone the button so that it's at both locations. Luckily jQuery has precisely such a function and so with this:


$('div.event_description-section').prepend($('div.register_link-section').clone());


We now have exactly what we want—two Register Now buttons, one at the top and one at the bottom of the page.

For a second, more complicated, examle, let's imagine an NPO which works with addiction therapy. We have a custom tab for Contacts with a checkboxes called “Alcohol" and “Crack" etc. which are meant to indicate whether or not the Contact has these addictions. After each is a date field to store when he began that addiction. With no customization, here is how the fields look:

If this were a real site, however, the list of substances would be much longer. It would be easier to read and use if the date fields could be to the right of the checkboxes. It would be even clearer if we could hide those date fields which are not relevant, i.e. where the checkbox is not checked. This type of customization is well-suited for jQuery.

The first step here is to find how to target the DOM elements and then move them. Using Firebug, we can find that the classes assigned to the “Crack" row are “custom_field-row custom_256_155-row" It is tempting to therefore use the class “custom_256_155-row" as our selector. If we load up a few other contacts, however, we will eventually find that whereas the 256 number remains the same (as that is the ID of the custom field) the 155 number changes with each contact. So our actual selector is “custom_256_*" where the * is a wildcard. The way to target a class with a wildcard such as that is with this:


$("tr[class^=custom_field-row custom_256_]")


which means any TR with a full class definition starting with “custom_field-row custom_256_". Now that we have targeted our first row, we can add a TABLE tag onto the second TD tag, which sets up a container to use to relocate our date row. Now we remove our date row, which is id 257 in this case, from the main table and append it to our new table. This is half the job (for this one substance anyhow) and is the first two lines in the code below.

The second half of the job is to add an onclick handler to hide or show the date field depending on the state of the addiction checkbox. To do this, we use the same row target method to target our input and then add a fairly simple click handler. Here is the full code:


$("tr[class^=custom_field-row custom_256] .html-adjust").append('

');
$("tr[class^=custom_field-row custom_256_] table").append($('tr[class^=custom_field-row custom_257_]').remove());
$("tr[class^=custom_field-row custom_256_] input").click(function(){
if ($(this).attr('checked')) {
$(this).parent().parent().find('table').show();
}
else {
$(this).parent().parent().find('table').hide();
}
})


Here is how the fields look afterward, with the Crack date hidden after we clicked it to be not checked:

The truth is that this is not a complete solution, because when the page loads, the code needs to check the status of the checkbox and hide the date field if necessary. Furthermore, this solution is specific to only one substance and needs to be generalized for a list of them. One could also use the toggle function instead of hide and show. The basic ideas required, however, are above and the savvy developer can expound upon them for a full solution. :)

$("#some-id").find("tr[class^=custom_field-row custom_256_]").each(function(){ 

$("#some-id tr[class^=custom_field-row custom_256_]").each(function(){ 
is more readable

Unfortunately in this case, don't think we have an id set by civi above, so we depend on the theme.
$("form tr[class^=custom_field-row custom_256_]").each(function(){ 

Is probably going to work and be as fast as a #some-id 

Anyway, on any sane browser, that's probably going to save a few ms when you load the registration form. 


X+

 
$("#YOUR_CIVICRM_QFID_999_9").hide();
$("label[for='YOUR_CIVICRM_QFID_999_9']").next('br').remove();
$("label[for='YOUR_CIVICRM_QFID_999_9']").hide();