CiviCRM Developer Training Extend and customize CiviCRM

CiviCRM Developer Training
Extend and customize CiviCRM
•
•
•
•
Matthew Briney ([email protected])
Chang Xiao ([email protected])
IRC: changx
Forum changx (xcf33)
Introduction
• 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/
Development
Environment
http://www.example.org/sites/all/modules/civicrm/bin/civimail.cronjob.php?name
=user&pass=pass&key=key
Cron Jobs
• Topics
• CiviCRM Architecture
• Public APIs
• Hooks
Develop For CiviCRM
DAO
BAO
CiviCRM Architecture
Directory Structure
• CRM/Mailing/BAO/Job.php
corresponds 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();
Example
•
•
•
•
•
Write a module (API, hooks)
Theme overrides (API, Smarty)
Custom report
Custom search
Custom payment gateway
How to Customize
CiviCRM
• http://wiki.civicrm.org/confluence/display/CRMDOC33/
CiviCRM+Public+APIs
• Current Version: V2
• Upcoming Version: V3 (CiviCRM 3.4/4.0)
Public APIs
•
•
•
•
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’,
);
Public API
• Template level (smarty)
• REST interface
• AJAX
(http://wiki.civicrm.org/confluence/display/CRMDOC33/
AJAX+Interface)
• PHP (most common)
Invoking the API
• {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)
•
{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 Call (Template)
Example
• https://www.example.org/path/to/civi/codebase/civicrm/e
xtern/rest.php?q=civicrm/<function>
• Has complete access to all public APIs
API (REST Interface)
•
•
•
•
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 PHP
• Entity-action model
• Should you use it?
API V3
• API Explorer
• Access it at: /civicrm/ajax/doc#explorer
• For version 3.4/4.0
Live DEMO
• http://wiki.civicrm.org/confluence/display/CRMDOC33/
CiviCRM+hook+specification#CiviCRMhookspecificatio
n
• Fires before or after an action or at specific time
• Have specific naming conventions.
CiviCRM Hooks
• 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’);
}
}
}
Example 1
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
• Single Value Query:
$query = “Select Blah FROM Blah”
CRM_Core_DAO::singleValueQuery( $query );
Other useful functions
• 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();
Example (save a record)
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.php
CRM_Report_Form_Contact_AreaDemoSummary extends CRM_Report_Form
Copy template .tpl file from civicrm/templates/CRM/Report/Form/Contact/Summary.tpl
to /var/www/htdocs/custom_templates/CRM/Report/Form/Contact/AreaDemoSummary.tpl
Custom Reports
• Register the report template at
civicrm/admin/report/register&reset=1
• Make sure you have custom template directory set up at
civicrm/admin/setting/path&reset=1
Custom Reports
•
•
•
•
__construct()
select()
from()
where()
Anatomy of a Report
• __construct()
Define display columns , filters
http://pastebin.com/FsKELJbX
Field Definition
• select()
• http://pastebin.com/0ssZQ9QR
• from()
• http://pastebin.com/hPPyGy8w
• where()
http://pastebin.com/2W0ucZnB
• groupBy()
• orderBy()
• postProcess()
• Going through examples.
Example
Custom Searches
• Build search file
• Place file in custom search folder
• Register report with CiviCRM
• /sites/all/modules/civicrm/CRM/Contact/Form/Search/Cust
om
Process
• http://wiki.civicrm.org/confluence/display/CRMDOC33/
Custom+Search+Components
• /sites/all/modules/civicrm/CRM/contact/Form/Search/Cus
tom
Documentation
Template Override
• Templates located in: /civicrm/templates/CRM
• Organized by feature
Template Structure
• Copy the file from
• /civicrm/templates/CRM
• to the same folder structure in
• /sites/all/civicrm_templates/CRM
Overriding Templates
• 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