Extending CiviCRM

This section contains developer documentation for CiviCRM. It should be useful for developers wishing to extend CiviCRM and also for organizations who want to ensure that their developers are using best practices to extend CiviCRM.

There are many different ways you can extend and customize CiviCRM, and this section takes you through them in order of simplest to most difficult. If you find that you cannot do something you're trying to do using the tools and techniques outlined in this section, please get in touch with the CiviCRM developers in the forums (http://forum.civicrm.org/) or on the IRC channel (#civicrm on irc.freenode.net) and let them know.  Hacking on the core code should always be a last resort and done in consultation with the core team who will always be happy to help you find the best way to cover your use case.

When do you need to code?

There are a lot of different options to customize CiviCRM to fit your specific needs. They are listed roughly in order of complexity:

1. Change the configuration: (ok, this isn't coding but it is worth repeating) you can use custom fields, profiles, components and many existing Drupal modules and Joomla! extensions to customize CiviCRM without writing a line of code. This book covers many of these options in other sections, so make sure you've exhausted all of those possibilities before you dive into extending the code.
   
2. Edit CSS: You can create a new Cascading Style Sheet (CSS) file and use it, for example, to adapt the style to your site or hide elements that don't make sense in your environment.  Administer -> Configuration -> Global settings -> Resource URLs field "Custom CiviCRM CSS URL".
   
3. Edit the templates: Useful to change the layout of forms, and to add more data or features via AJAX. Read about templating and APIs to know more.
4. Implement hooks: Hooks are called at specific points in the code as users interact with CiviCRM and are useful, for example, when you want to change the default behavior when you create, update or delete an entity, create a new custom mail merge token, or to populate a custom field automatically based on your own business logic.
   
5. Add custom searches or reports: Use these to fetch information and display it in a unique way.
6. Extend your CMS: Create a Drupal module or Joomla! extension that integrates with CiviCRM.
7. Override PHP files: In the same way that you can override templates, you can override any file in CiviCRM. If you have to modify core, it's much better to override files than to edit them.
   
8. Write a new CiviCRM component or patch CiviCRM: Regardless of which path you take to extending and customizing CiviCRM, chances are that someone else would be interested in what you did. Share it with the community! If others start using your contribution, you're likely to get bug fixes, improvements, and documentation as a bonus. Let us know what you did in the forums or IRC channel (see above).
   

Where possible use the documented APIs in your extensions, this will make them less likely to break when you upgrade CiviCRM.

Before venturing into any development, we strongly suggest that you discuss what you want to do, and how you want to do it, with the community.  We will help you find the simplest way to reach your goal and may be able to point you to others doing similar work.

Please consider using the Academic Free License to open more opportunities to share your work. This also makes contributing your work back to the CiviCRM project very simple.