Monday, December 3, 2012 - 16:21
Written by

Do you modify template files for your site?  If so, you ought to know the tedious process of updating all the overridden template files every time you upgrade.  (If you don't know that pain, either you've never upgraded or you should quit reading and go check your customized files.)

The method of using .extra.tpl files is helpful for tacking some jQuery on the end, but if you're altering parts of the page or adding to the middle, you've got to copy the whole template file and modify it.

At AGH Strategies, a number of clients have lots of customized templates, and when we run upgrades for them, we need a reliable and efficient way to separate the customizations from the rest of the file that's just copied from CiviCRM.  We'll then apply the changes to new versions of the template files.

One command will take care of generating a diff of everything, but it's tricky to get all the inputs right, so I saved it as a bash script and shared it on GitHub so it's easy to modify for different types of installations.  Here's the core of it:

diff -r -u yourcivicrmcodebase/templates yourcustomtemplatesdirectory | sed '/^Only in/d' > outputfile

It's basically a straightforward diff command, but the vast majority of template files won't have a corresponding custom template file.  Using sed will prevent the output from being overwhelmed by the list of files that are only in the regular templates directory.

Once you generate the patch of your changes, you can apply it to the templates that come with the new version of CiviCRM.

The script will copy your custom templates to a temporary directory and overwrite them there with the corresponding templates from a new version of CiviCRM that you point it to.  You can then try applying the patch of all your changes.  Once all the changes are made, you can simply replace the contents of your custom templates folder with those in the temporary directory.

Let me know what you think in the comments, and please share any improvements or alternate approaches.

Filed under


What we do is to use git:

copy first the standard template and commit it with something explicit ("unmodified version 4.2.1"), then do the changes.

Then we do the modif and commit them

When there is a new release, we create a new branch and do the initial check in.

We either generate the diff and apply it directy (I'm sure there are some magic commands in git to do it directy but my gitfu isn't at the level)  or more often than not end up modifying manually because the template has changed too much.

Finally, we still use a lot of .extra to generate the html, and a onliner of jquery we need into the right place in the template. That's becoming more and more our solution.



Hi Xavier,

I think I know what you are suggesting, but could you give an example of this technique?

(And thanks, Andrew, for starting this discussion!)


We use a great tool open source tool

It allows you to do a visual merge of 3 source directories and save the output to a fourth location.

By settting the three source directories to .../old/templates, .../old/custom_templates, and .../new/templates and setting the output to new/custom_templates it allows us to (fairly) painlessly upgrade.

I recommend giving it a try.


I also add a snippet at the top of each .tpl override:

What has changed:
- moved x below y
- foo
- bar

Also take pause before you override a tpl to see if you can't just make the change with CSS or a hook.  Both of those methods is more maintainable.



If you are just making a few adds/remove to the template.This is a lot more granular and hence can potentially work across major version changes

note that we have not annotated most of the templates, but we should do this incrementally as folks start using this functionality