CiviCRM Developer Training

1. CiviCRM Developer Training Extend and customize CiviCRM

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

3. Tools for Local Development – LAMP Stack • AcquiaDev Desktop (Mac & Win) • http://network.acquia.com/downloads/6.x/ • MySQL Workbench – ERD Diagrams • http://www.mysql.com/downloads/workbench/ Development Environment

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

5. Topics • CiviCRM Architecture • Public APIs • Hooks Develop For CiviCRM

6. BAO DAO CiviCRM Architecture

7. Directory Structure

8. 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(); Example

9. Write a module (API, hooks) • Theme overrides (API, Smarty) • Custom report • Custom search • Custom payment gateway How to Customize CiviCRM

10. http://wiki.civicrm.org/confluence/display/CRMDOC33/CiviCRM+Public+APIshttp://wiki.civicrm.org/confluence/display/CRMDOC33/CiviCRM+Public+APIs • Current Version: V2 • Upcoming Version: V3 (CiviCRM 3.4/4.0) Public APIs

11. 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

12. Template level (smarty) • REST interface • AJAX (http://wiki.civicrm.org/confluence/display/CRMDOC33/AJAX+Interface) • PHP (most common) Invoking the API

13. {crmAPI entity="nameobject" action="namemethod" var="namevariable" extraparam1="aa" extraparam2="bb”} • entity (contact, contribution) • action (get, search) [retrieving method] • varsmarty template variable name • extraparamparameters from the API documentation • return fields to return. API Call (Template)

14. {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

15. https://www.example.org/path/to/civi/codebase/civicrm/extern/rest.php?q=civicrm/<function>https://www.example.org/path/to/civi/codebase/civicrm/extern/rest.php?q=civicrm/<function> • Has complete access to all public APIs API (REST Interface)

16. 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

17. Entity-action model • Should you use it? API V3

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

19. http://wiki.civicrm.org/confluence/display/CRMDOC33/CiviCRM+hook+specification#CiviCRMhookspecificationhttp://wiki.civicrm.org/confluence/display/CRMDOC33/CiviCRM+hook+specification#CiviCRMhookspecification • Fires before or after an action or at specific time • Have specific naming conventions. CiviCRM Hooks

20. 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

21. 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); } } } }

22. Hands on exercise

23. Single Value Query: $query = “Select Blah FROM Blah”CRM_Core_DAO::singleValueQuery( $query ); Other useful functions

24. 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_toolsdashlets’;$dashboard->is_active = 1;$dashboard->created_date = date('Y-m_dh:i:s');$dashboard->save(); Example (save a record)

25. Custom Reports

26. http://wiki.civicrm.org/confluence/display/CRMDOC33/Custom+Reports+(How+to)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 nameAreaDemoSummary.phpCRM_Report_Form_Contact_AreaDemoSummaryextendsCRM_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

27. Register the report template atcivicrm/admin/report/register&reset=1 • Make sureyouhavecustomtemplatedirectory set up atcivicrm/admin/setting/path&reset=1 Custom Reports

28. __construct() • select() • from() • where() Anatomy of a Report

29. __construct() Define display columns , filters http://pastebin.com/FsKELJbX Field Definition

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

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

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

33. groupBy() • orderBy() • postProcess()

34. Going through examples. Example

35. Custom Searches

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

37. http://wiki.civicrm.org/confluence/display/CRMDOC33/Custom+Search+Componentshttp://wiki.civicrm.org/confluence/display/CRMDOC33/Custom+Search+Components • /sites/all/modules/civicrm/CRM/contact/Form/Search/Custom Documentation

38. Template Override

39. Templates located in: /civicrm/templates/CRM • Organized by feature Template Structure

40. Copy the file from • /civicrm/templates/CRM • to the same folder structure in • /sites/all/civicrm_templates/CRM Overriding Templates

41. 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