Early in this book, we presented CiviCRM's open source licensing as one of the chief selling points of the software. Open source means the source code is readily available and can be altered or added to without infringing on the license. In short, it means you can open up the hood and tinker with it to your heart's content.
Of course, "tinkering" isn't really what benefits you. It's the ability to truly customize, expand, add-on, restructure, or do whatever you need to, in order to make sure this software suits the needs of your organization. Then, you can share with the community so that you benefit from their efforts to improve, document, support, and extend the software. That is the true value of open source. Unlike proprietary closed-source software, you're not wholly dependent on the roadmap plans of the company who owns the software (crossing your fingers in the hope they build your desired functionality), nor are you required to work through their support desk to achieve software modifications. Open source means you can modify the code yourself, or hire a developer to help achieve your needs.
While it's beyond the scope of this book to delve fully into CiviCRM customization, we want to leave you with some best practices and general direction for effectively pursuing your own customization efforts.
Realize first of all that CiviCRM was built to be customized. If you were to have a conversation with the core team, they would tell you that they built the software with the express purpose of making it as easily extendable as possible. They don't want you to be hamstrung by the code. They want to help you achieve your customization needs quickly and efficiently. There are several ways in which this is realized.
The first way the software supports customization is through code management assistance. Hooks provide tools for injecting your code into existing processes and are the cleanest (and generally most upgrade-friendly) path to customization.
If you're familiar with Drupal's hook structure, you will find CiviCRM's structure to be patterned in a similar way. You insert your own code into the executed process when particular events occur, without having to modify anyone else's code. In Drupal, you implement hooks via modules; in Joomla!, they are handled through a single hook file that can be stored in your PHP override directory (as described in the following section). In either case, your hook implementation will consist of calling the hook function, limiting its scope (if appropriate), and altering or adding to the code behavior as needed. For example, you can use the buildForm hook to alter default values on a profile form displayed on your site.
For a list of available hooks and specific guidance on implementing them, visit http://wiki.civicrm.org/confluence/display/CRMDOC/CiviCRM+hook+specification.
Hooks are clean and are generally preferred because you are typically working with and impacting only the code that pertains to your specific needs. In the preceding example where you are altering a default form value, the hook allows you to zero in on the specific form and alter just the desired field, without touching or impacting any other field or process in the form class. Your customization "footprint" is kept to a minimum.
However, you will at times have more significant customizations that cannot be accomplished with a hook, or for which no hook is currently available. In those cases, CiviCRM provides the ability to define override directories for both PHP and template (.tpl) files. It's often easier to modify the layout of a page by overriding a .tpl file than it is to modify the PHP code that determines what will be displayed.
An override directory, as the name suggests, is a location distinct from the core code in which you place modified versions of files which will "override" the core files. Before using override directories, you must define them in your global settings. Visit Administer | Configure | Global Settings | Directories to set those locations, taking note of the recommended settings found in the help text (depending on your CMS). Once configured, you will place your modified copy of the original core file in the corresponding folder path inside the override directory.
For example, suppose your PHP override directory for a Drupal installation of CiviCRM is /var/www/domain.com/public_html/sites/domain.com/files/civicrm/custom_php/. To override the form file used to create a new case, you would place your modified file in /var/www/domain.com/public_html/sites/domain.com/files/civicrm/custom_php/CRM/Case/Form/Case.php.
In Joomla!, the standard location to place the override files will be in your media directory. For example: /var/www/domain.com/public_html/media/civicrm/custom_php/CRM/Case/Form/Case.php.
Tip
Files for specific profiles, contribution pages, and events can be overridden separately from those for other profiles, contribution pages, and events. Insert an extra directory level with the ID of the profile, contribution page, or event to override. For example, /var/www/domain.com/public_html/sites/domain.com/files/civicrm/custom_tpl/CRM/Contribute/Form/Contribution/11/Main.tpl will override the contribution page with an ID of 11.
There are several important things to note when using override files:
- PHP override folders must be built from the CRM directory, as exemplified previously. Template overrides will be built from the
/templates/CRM/directory. In other words, the structures are built from thecivicrm/package subfolder (in your core files). - The override file itself should be a modified form of the original file. Even if you are only altering a small portion of the file, the entire file will replace the corresponding core file and thus must include all necessary code. This is the key difference between hooks and override files—whereas hooks may alter code at the line level, override files alter at the file level.
- Be sure to work with the correct version of the core file and maintain updates in both your core and override files. For example, if your site is running v3.2.4, don't use the core file from v3.2.5 as the basis for an override customization. The newer revision may include additional changes that break your site functionality. When upgrading your site to a newer version or revision, you should plan to carefully compare code in your override files and re-implement your modifications using the new core version.
Both of these customization methods help you achieve an important principle in development: don't mess with the core files. Wherever possible, you should avoid altering core code files. Failing to do so will impede your ability to cleanly upgrade the code base and leave you vulnerable to overlooking (and losing) important modifications.
If your customizations take place within the CiviCRM environment, you can easily access and make use of the classes and methods throughout the code. However, if you are extending CiviCRM outside of that environment (such as a Joomla! extension or Drupal module), you may want to make use of CiviCRM's public API.
You can view a list of APIs online at http://wiki.civicrm.org/confluence/display/CRMDOC/CiviCRM+Public+APIs or through the (relatively) new API documentation at http://api.civicrm.org.
APIs can be invoked through the PHP code in your site, the CiviCRM REST interface, in JavaScript or AJAX, through Smarty templates, through the Drush module in Drupal, or even by creating standardized wrappers in other languages like Perl. Depending on your access method, you will adapt the function calls with associated parameters accordingly. For more details about implementing the API through these various methods, visit the API link provided above.
In the spirit of community, CiviCRM encourages developers to share code snippets and suggestions through the online wiki. Developer resources are largely collected at http://wiki.civicrm.org/confluence/display/CRMDOC/Develop, though there are other locations throughout the wiki where code resources may be found. From this page, you'll find access to documents detailing the code architecture, Entity Relationship Diagrams (ERD) of the database schema, hooks, API, sample code, and other tips and tricks to assist with development.
Donald Lobo, the lead CiviCRM developer, has been working on an implementation of CiviCRM for a small school (aptly titling the project CiviSchool). He has shared all his code customizations (largely in the form of Drupal modules) along the way. It provides a great prototype of best practices from which you can glean ideas and sample code for your own needs. You can access his code at http://svn.civicrm.org/sfschool/trunk/ and read about the customizations through the blog at http://civicrm.org/CiviSchool.
If you implement the customizations, you feel would be useful for the community at large, be sure to add them to these wiki pages for the benefit of others.
Inevitably, your customization efforts will quickly lead you to a host of questions. Where do I find a certain file? How does the form process work in a certain place? Is there a hook that will impact a certain process at the place I need it? How do I structure my arrays correctly?
The CiviCRM codebase is fairly large and somewhat complex. It uses many external libraries and packages and a variety of technologies. However, it's also very consistent, which means the learning curve to resolve customization needs for a specific component will generally translate quickly to the file and code structure in other components.
Nevertheless, you'll have questions and will want to know where to turn to have them answered. There are two primary places you should go—the forums (http://forum.civicrm.org) and the IRC channel (irc://freenode/civicrm or http://webchat.freenode.net/?channels=#civicrm).
There is quite a bit of existing troubleshooting and development-related content on the forums, so you may find answers to your questions by simply searching there. It is a very active environment and threads are regularly reviewed and responded to by the core development team and many experienced implementers and developers. You'll find the community very committed to supporting each other in that venue.
The core team and many active developers also regularly hang out on the IRC channel, providing a good place to ask questions and get knowledgeable answers. As with any real-time chat room, the IRC channel will vary throughout the day in terms of the number of active users and their availability to help with your issues. So if the conversation seems quiet, don't give up—just stop by later to see if anyone is around.
You may also want to become familiar with the public issue tracker (http://issues.civicrm.org). It is used by the development team and is open to the community for bug and feature tracking.
If you come across what appears like a bug in the software, don't immediately create a new issue ticket. It may be something that is specific to just your implementation of CiviCRM, or it may be a bug that has already been reported or even fixed in more recent versions. A good place to start is by searching the forums at http://forum.civicrm.org for relevant posts. If you don't find anything, try to reproduce the error on the latest stable version of CiviCRM running on the demo site at http://demo.civicrm.org. Then post your problem into the appropriate forum, including the text of error messages received, what you were doing when it happened, and whether you can reproduce it on the demo site. Within a few hours or a day you'll probably have a helpful response. It may be a suggested fix or work-around, a link to a relevant page in the wiki, or a request to create a new issue on the bug tracker.
If you are able to solve the problem you posted into the forum, it's a good idea to update the thread with what worked to help others who may face the problem, and to provide feedback to those assisting you. Remember that they're people too. Many who help out on the forums aren't paid for their time there. A "thanks" and a respectful tone go a long way towards getting people to help you, while an abusive, entitled tone is more likely to be met with a cold shoulder.
If you put in some time figuring out how to do something that wasn't documented, then it's a great idea to write up how you did it on the wiki. Not only will it help you remember how to do it when you need to do it again six months from now, but will also help others. Some of them might even provide additional improvements to your modifications..