CiviCRM Developer TrainingExtend and customize CiviCRM

Introduction

• Matthew Briney (matthew@emotivellc.com)• Chang Xiao (chang@emotivellc.com)• IRC: changx• Forum changx (xcf33)

Development Environment

• Tools for Local Development – LAMP Stack• Acquia Dev Desktop (Mac & Win)• http://network.acquia.com/downloads/6.x/

• MySQL Workbench – ERD Diagrams• http://www.mysql.com/downloads/workbench/

Cron Jobs

http://www.example.org/sites/all/modules/civicrm/bin/civimail.cronjob.php?name=user&pass=pass&key=key

Develop For CiviCRM

• Topics• CiviCRM Architecture• Public APIs• Hooks

CiviCRM Architecture

DAO BAO

Directory Structure

Example

• CRM/Mailing/BAO/Job.phpcorresponds to:

• CRM_Mailing_BAO_Job• Snippet:

civicrm_initialize();require_once(‘CRM/Mailing/BAO/Job.php’);$mailing_job = new CRM_Mailing_BAO_Job();

• $mailing_job->id = 45$mailing_job->getMailingSize();

How to Customize CiviCRM

• Write a module (API, hooks)• Theme overrides (API, Smarty)• Custom report• Custom search• Custom payment gateway

Public APIs

• http://wiki.civicrm.org/confluence/display/CRMDOC33/CiviCRM+Public+APIs

• Current Version: V2• Upcoming Version: V3 (CiviCRM 3.4/4.0)

Public API

• For 3.4/4.0• Look for civicrm.settings.php and change the API• Define(‘CIVICRM_API_VERSION’, ‘3’);• OR explicitly specify in the $param of the API cal

$param = array(‘version’ => ‘2’,

);

Invoking the API

• Template level (smarty)• REST interface• AJAX

(http://wiki.civicrm.org/confluence/display/CRMDOC33/AJAX+Interface)

• PHP (most common)

API Call (Template)

• {crmAPI entity="nameobject" action="namemethod" var="namevariable" extraparam1="aa" extraparam2="bb”}

• entity (contact, contribution)• action (get, search) [retrieving method]• var smarty template variable name• extraparam parameters from the API documentation• return fields to return.

API Call (Template)Example

• {crmAPI entity='contact' action="search" var="contacts”}<ul>

{foreach from=$contacts item=contact}<li id="contact_{$contact.contact_id}">

{$contact.sort_name}</li>

{/foreach} </ul>

{crmAPI entity='contact' action="search" var="contacts" country="France" contact_type="Individual" return ="sort_name,email"}

API (REST Interface)

• https://www.example.org/path/to/civi/codebase/civicrm/extern/rest.php?q=civicrm/<function>

• Has complete access to all public APIs

API PHP

• Default API• Most reliable• Called by modules• Snippet:

$params = array( 'contact_id' => 10, 'return_custom_N' => 1 );$retrieved = civicrm_contact_get( $params );if ( civicrm_error( $retrieved ) ) {

return $retrieved['error_message'];} else {

print_r($retrieved);}

API V3

• Entity-action model• Should you use it?

Live DEMO

• API Explorer• Access it at: /civicrm/ajax/doc#explorer• For version 3.4/4.0

CiviCRM Hooks

• http://wiki.civicrm.org/confluence/display/CRMDOC33/CiviCRM+hook+specification#CiviCRMhookspecification

• Fires before or after an action or at specific time• Have specific naming conventions.

Example 1

• Snippet: (send an email when the contact is created)

my_module_civicrm_post( $op, $objectName, $objectId, &$objectRef ) {

if($op == ‘create’) {if($objectName == ‘Individual’) {

// send the new contact an email

mail($objectRef->email, ‘hi, welcome’, ‘Welcome to the site’);

}}

}

function my_module_civicrm_alterMailParams(&$params) {

$token_params = array('subject' => $params['subject'],'from' => $params['from'],);

// do token replacement here$tracking = array('utm_source' => token_replace(variable_get('civitracker_mailing_pattern_source',

'[sitename]'), 'civitracker_mail', NULL, '[', ']', $token_params),'utm_campaign' =>

token_replace(variable_get('civitracker_mailing_pattern_campaign', '[date]'), 'civitracker_mail', NULL, '[', ']', $token_params),

'utm_medium' => 'email',);

if(variable_get('civitracker_mailing_toggle', 1) == 1) {if(isset($params['html']) && $params['html'] != '') {$params['html'] = civitracker::url_append($params['html'], $tracking);}if(isset($params['text']) && $params['text'] != '') {$params['text'] = civitracker::url_append($params['text'], $tracking);}}

}}

Hands on exercise

Other useful functions

• Single Value Query: $query = “Select Blah FROM Blah”CRM_Core_DAO::singleValueQuery( $query );

Example (save a record)

• Create a new dashlet

• Snippet:civicrm_initiate();require_once(‘CRM/Core/DAO/Dashboard.php’);$dashboard = new CRM_Core_DAO_Dashboard();$dashboard->domain_id = 1;$dashboard->label = $title;$dashboard->url = ‘path/to/dashlet’;$dashboard->permission = 'view civicrm_tools dashlets’;$dashboard->is_active = 1;$dashboard->created_date = date('Y-m_d h:i:s');$dashboard->save();

Custom Reports

Custom Reports

• http://wiki.civicrm.org/confluence/display/CRMDOC33/Custom+Reports+(How+to)

• Grab a report that you wish to copy• /var/www/htdocs/sites/all/modules/civicrm/CRM/Report/Form/Contact• Create a custom report template and copy the file into

/var/www/htdocs/custom_templates/CRM/Report/Form/Contact• Rename the file name and class name

AreaDemoSummary.phpCRM_Report_Form_Contact_AreaDemoSummary extends CRM_Report_Form

• Copy template .tpl file from civicrm/templates/CRM/Report/Form/Contact/Summary.tplto /var/www/htdocs/custom_templates/CRM/Report/Form/Contact/AreaDemoSummary.tpl

Custom Reports

• Register the report template atcivicrm/admin/report/register&reset=1

• Make sure you have custom template directory set up atcivicrm/admin/setting/path&reset=1

Anatomy of a Report

• __construct()• select()• from()• where()

Field Definition

• __construct()

Define display columns , filters

http://pastebin.com/FsKELJbX

• select()• http://pastebin.com/0ssZQ9QR

• from()• http://pastebin.com/hPPyGy8w

• where()http://pastebin.com/2W0ucZnB

• groupBy()• orderBy()• postProcess()

Example

• Going through examples.

Custom Searches

Process

• Build search file• Place file in custom search folder• Register report with CiviCRM• /sites/all/modules/civicrm/CRM/Contact/Form/Search/

Custom

Documentation

• http://wiki.civicrm.org/confluence/display/CRMDOC33/Custom+Search+Components

• /sites/all/modules/civicrm/CRM/contact/Form/Search/Custom

Template Override

Template Structure

• Templates located in: /civicrm/templates/CRM• Organized by feature

Overriding Templates

• Copy the file from • /civicrm/templates/CRM

• to the same folder structure in • /sites/all/civicrm_templates/CRM

• Identify the page you want to edit (template)• Find the correct template file• Copy the template directory outside of

/sites/all/modules/civicrm• Set the configuration settings at adminster->global-

>directories• Make the changes