CiviCRM has an extensions framework that allows you share your custom searches, reports and payment processors with the community. Before you being work on writing an extension make sure someone else hasn't already contributed something similar by checking the list of extensions on http://directory.civicrm.org/.
Before you start, make sure your extensions are enabled! You need to configure a directory, where your extensions will be stored. To do that, you need to go to: "Administer -> Configure -> Global Settings -> Directories", fill in "CiviCRM Extensions Directory" field and click "Save" at the bottom of the page. It's best to choose a directory outside of $civicrm_root, to avoid potential problems during upgrade. Then follow the seven steps below.
Every extension has a unique name called the extension key. It's built using Java-like reverse domain naming to make it easier with identifying unique extensions and giving developers more flexibility on providing different extensions. So for example, if your website is civiconsulting.com and you're developing custom search showing only event payments, you can choose: com.civiconsulting.search.eventregistration as the key.
Go to your extensions directory and create the directory named after your key. This will be the place where you'll put all the extension related files. When you're done, it will also be put into the zip archive for further distribution.
Now you need to create a file which will describe your extension so we know what a given extension does, who wrote it, who supports it and quite a few other things. It needs to be called info.xml. It's in XML format and it's relatively simple. Here's an example:
<?xml version="1.0" encoding="UTF-8" ?> <extension key="org.civicrm.activity" type="search"> <callback>ActivitySearch</callback> <name>Activity Search</name> <description> This custom search allows to search through activities and returns activities as results (not contacts as regular search). </description> <url>http://civicrm.org</url> <license>AGPL</license> <maintainer>CiviCRM Core Team <firstname.lastname@example.org></maintainer> <releaseDate>2010-09-01</releaseDate> <version>1.0</version> <compatibility> <ver>3.3</ver> <ver>3.4</ver> </compatibility> <develStage>beta</develStage> <comments>For support, please contact project team on the forums. (http://forum.civicrm.org)</comments> </extension>
Here's a quick description of the XML elements:
Since we love things to be localised, we've added that too and you can provide the extension description in other languages - the optional localisedInfo section of the info file does that:
<extension ...> ...regular stuff <localisedInfo> <pl_PL> <description>Opis po polsku.</description> <maintainer>Zespół CiviCRM <email@example.com></maintainer> <comments>Wsparcie dla tego rozszerzenia dostępne na forum CiviCRM (http://forum.civicrm.org).</comments> </pl_PL> <pt_BR> ... </pt_BR> </localisedInfo> </extension>
Please note though, this only supports name, description, maintainer and comments sections - all other extension information defined here will be ignored.
Depending on the type of extension that you're building, you will need to follow different instructions. Please refer to separate chapters for:
Make sure your extension works as planned! Once you have the info.xml file, you will be able to turn the extension on and off in the Manage CiviCRM Extensions screen - use that to see what errors you're getting and react accordingly.
Once you're done with developing and testing, you need to put all the contents of your extensions directory into a zip file.We'll start by creating a directory named exactly the same as the unique key that we're choosing for our extension. You need to prepare the info file as described above. Then once you have the info file, you can add the other required files and subdirectories to the extension package. This will be different for Custom Searches, Reports or Payment Processors - see each specific chapter for concrete examples.
We are working on the extension submission system, but in the meantime, just get in touch with us via firstname.lastname@example.org with your extension or on the extensions board of the developer forum. We'll then do some testing and if everything works fine, we'll put your extension into the public distribution. Once there, everyone will be able to install it once they get to "Manage CiviCRM Extensions" screen.