civicrm developer training extend and customize civicrm
TRANSCRIPT
CiviCRM Developer TrainingExtend and customize CiviCRM
Introduction
• Matthew Briney ([email protected])• Chang Xiao ([email protected])• 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