This documentation relates to CiviCRM version 3.0. It's not maintained anymore.
Current version of documentation.


Customize Built-in, Profile, Contribution and Event Registration Screens

Skip to end of metadata
Go to start of metadata

This page refers to outdated version of CiviCRM. Check current version of documentation.

Documentation Search

CiviCRM 3.0 Documentation

Support and Participation

Developer Resources

As of 1.7, you can create customized versions of the standard CiviCRM forms and pages for your site. This gives you a lot of power to modify the CiviCRM user interfaces without requiring advanced programming skills - the templates use HTML plus a fairly simple scripting languge. It also means you won't lose your customizations when you upgrade (although it is possible that changes in the core code could affect your templates - and testing after upgrades is essential).

First Time Configuration

  • Create a new directory under your webroot where you will place your custom template files.
    • EX: /var/www/civicrm_custom
    • EX: /var/www/media/civicrm/customtpl/
  • Login to CiviCRM with administer CiviCRM permissions and navigate to Administer CiviCRM » Global Settings » Directories
  • Enter the full path to your custom templates directory in the Custom Templates field and save your changes.

Create a Custom Screen

These steps are for any "built-in" screen (e.g. the Contact Summary screen). Creating a custom Profile form or page are covered in the next section.

  • Navigate to the screen you want to customize and use your browser to View Source.
  • Search for ".tpl" in the source. You will find a comment line which gives you the path and name of the template used for the screen you are viewing.
  • Locate this file on your server under your ../civicrm/templates path.
  • Make a copy of file in the equivalent path under your new custom templates directory.

    If your civicrm install files are in:
    ...and your custom templates directory is:

  • Edit the file as needed and save.
  • Then clean-up the compiled templates directory, usually by deleting all the directories under your templates_c directory. You can also do the cleanup by enabling CiviCRM debugging and running the directory cleanup command. (NOTE: You do NOT need to delete the standard version of the template from your main CiviCRM codebase. CiviCRM will look for a customized version first, and use that one if found.)
  • You should see your modified version when you reload the CiviCRM screen.

Custom Profile / Contribution / Event Registration Screens

The process for customizing Profiles / Contribution / Event Registration is the same as above EXCEPT that you have the flexibility to create different screen "versions" for each of your configured Profile / Contribution / Event Registration Pages. The structure for contribution and event registration pages is similar to that of profile explained here. You do this by creating an extra directory layer in your custom directory tree that references the Profile's ID.

If you want a custom version of the Profile View screen for a Profile whose ID is 2...and your basic install and custom directory setup are the same as shown above - then your custom template copy should be saved to:

If you want a custom version of the Profile Create/Edit screen for a Profile whose ID is 2...and your basic install and custom directory setup are the same as shown above - then your custom template copy should be saved to:

Profile ID's are listed in the Administer CiviCRM » CiviCRM Profiles table (ID column).

If you want a custom version of the Register screen for an Event whose ID is 2...and your basic install and custom directory setup are the same as shown above - then your custom template copy should be saved to:

Referencing Individual Fields in Profile Pages

Profile view and edit pages consist of several template files working together. The View.tpl (detail view pages) and Edit.tpl (edit pages) each reference a corresponding Dynamic.tpl file, which cycles through the fields found in the profile and displays them in a table. The layout is very basic--- one column is used for the field label, the other column for the field value or form field. Often, when customizing profile pages, you may want to reference specific fields and layout them out in a customized display. To do so you would work with the View.tpl/Edit.tpl files and insert smarty tokens fors the profile fields array. The profile fields array is structured as follows:

  • $profileFields_ProfileID => Field Name => label/value

So you would insert the following token into the template file to reference the First Name label and field value in Profile 3:

  • {$profileFields_3.first_name.label}: {$profileFields_3.first_name.value}

Custom fields in your profile are referenced using the custom ID value, e.g. {$profileFields_3.custom_38.value}.

With debugging turned on, use the Smarty Debug url string to view the Smarty variables available for inclusion on any given page. Simply add "&smartyDebug=1" at the end of your page url.

Changing Show/Hide Default on Collapsible Fieldsets

In the words of Dave Greenberg "This is a bit tricky because the collapse vs. expand states are controlled via showBlocks and hideBlocks arrays that are passed into a jscript function by the PHP code." So I will show you how to do this using an example.

If you want to make a fieldset that is by default collapsible or hidden on a CiviCRM Contact View screen, you would need to follow all the above instructions to first get the correct custom template and put it in the proper location. Let's assume you want to edit the CRM/Contact/Page/View/Tabbed.tpl screen, which is the default contact view. You would copy that into your custom template location. Then you will need to determine the name of the fieldset that you want to change the default state of. Let's say I want to collapse the "Communications Preferences" fieldset by default. Look in the file for that section, so in this case I find the line that has the following:

We can see that there's a javascript onclick call which references 'commPrefs_show' and 'commPrefs'. So since this fieldset is by default showing up, we need to force the javascript to reverse it. So next you need to scroll to the bottom of this file and look for the following javascript call:

The way we will fix this is to reverse the hide/show states of Communication Preferences. We will add the following two lines after
on_load_init_blocks( showBlocks, hideBlocks );

And that will fix it. Our final javascript call will look like this:

So for any other fieldset, you can find the show/hide names by looking for the fieldset section in the code as I demonstrated here. Just look at the <a>
tag for the onclick function.

  • None