Creating custom components

This is the seed information that will be transformed into component creation documentation. Please note that at this stage it's initial and incomplete.

The main element of external component is Info.php file. It contains PHP class which defines all the information about the component and implements a couple of methods needed by the system. Required elements in CRM_ComponentName_Info class are:

CRM_ComponentName_Info

Class properties:

protected $keyword <= defines the unique keyword for the component, used in different places

Class methods:

function getInfo() <= provides information about the component to the system.

Needs to return an array defining values for the following keys:

'name' (string) <= unique name of the component, will be used
'translatedName' (string) <= the name of the component, enclosed in ts for translation purposes
'title' (string) <= short description of the component, enclosed in ts for translation purposes
'search' (1|0) <= whether this component uses search
'showActivitiesInCore' (1|0) <= whether this component uses built in activities functionality

function getPermissions() <= needs to return the array of permissions used by this component

function getUserDashboardElement() <= registers a user dashboard (/civicrm/user) element, can return empty array if user dashboard not used.

Needs to return an array defining values for the following keys:

'name' (string) <= translatable name of the user dashboard element
'title' (string) <= translatable title of the user dashboard element
'perm' <= one of previously defined permissions needed to access dashboard element
'weight' (number) <= weight to define the position of the element on the dashboard

function registerTab() <= registers contact view (/civicrm/contact/view) tab, can return empty array if contact tab not used

Needs to return an array defining values for the following keys:

'title' (string) <= translatable title of the tab
'url' <= the last part of the url, can be the same as keyword (we should actually get rid of this one)
'weight' (number) <= weight to define position of the tab on contact view page

function registerAdvancedSearchPane() <= registers advanced search pane (/civicrm/contact/search/advanced) for this component, can return empty array if advanced search not used

Needs to return an array defining values for the following keys:

'title' (string) <= translatable title of the pane
'weight' (number) <= weight to define position of the pane on advanced search screen

function getActivityTypes() <= does nothing at the moment, but needs to be implemented

Entry in civicrm_component table

Once you have you Info.php file, you need to add the entry to civicrm_component table. This tables has only three columns:

id => just let it be the next one in row
name => should be the same as 'name' property returned by getInfo() method
namespace => should state the namespace of your component's classes, file paths will be derived from it.

Example: if you're writing a component called YourComponent and put all the component files in $civicrm_root/CRM/YourComponentPath directory, you need to do the following:

Create a table entry:

Create an Info class in file $civicrm_root/CRM/YourComponentPath.php, the class name should be CRM_YourComponentPath_Info

XML paths definitions

After you have db entry and Info class, you need to create an xml file which will define all the URL paths that you're going to use in your component. This file needs to be placed in $civicrm_root/CRM/YourComponentPath/xml/Menu/AnyName.xml
To get the idea of how the file should be structured, take a look at the below example from civicontribute

Properties of each <item> mean:

path <= the path part of each URL, after base url, so for example: if your install is at http://localhost.localnetwork/drupal
title <= title of the page that will be displayed under this address
page_callback <= php class that should be invoked once the URL is hit
access_arguments <= name of the permission that should be checked once the URL is hit
page_type <= 1 for elements that should be displayed in the menu, 0 for those which shouldn't
weight <= as everywhere, used for ordering
component <= name of the component this menu item belongs to (will be deprecated in one of following versions)

Do a menu rebuild

If you modify/add to the XML menu file, you need to rebuild the CiviCRM menu tables. You can do this from the web browser via:

q=civicrm/menu/rebuild&reset=1 (for drupal/standalone)
option=com_civicrm&task=civicrm/menu/rebuild&reset=1 (for joomla)

Next Steps

The following notes were collected from Michal Mach during a Birds of a Feather DupalCon SF session April 19, 2010. They outline some of the initial setup required before actual coding of the functionality of the module begins.

/CRM/Touchstone - present in svn repository but nto tarballs: is a template developed circa 2008 for new component but is now a bit outdated in terms of how things are / should be done

setup /CRM/ComponentName/Config.php to hold configuration settings, eg color = 'GREEN'; see CRM/Mailing/Config.php for a good example

/CRM/ComponentName/PseudoConstant.php - if needed for performance

/CRM/Core/Component/* defines the minimum abstract classes that need to be implemented for any component

/CRM/Core/Component.php - has base stuff for other components

/CRM/ComponentName/xml/Menu/ComponentName.xml - has the menu

/xml/schema/ComponentName/TableName.xml - define each table needed by component here

/CRM/ComponentName/DAO/TableName.php - autogenerated by /xml/GenCode.php from /xml/schema/ComponentName/TableName.xml using templates

/CRM/ComponentName/BAO/TableName.php contains all business layer logic for data storage, validation, retrieval

sometimes there is a /CRM/ComponentName/BAO/ComponentName/Utils.php for helper classes