CiviCRM/Joomla

1. CiviCRM/Joomla development/customization Brian Shaughnessy Lighthouse Consulting & Design www.lcdservices.biz

2. why customize? • not-for-profits… • range widely in the services they provide • range widely in the business processes they implement • impossible to have one-size-fits-all • overkill to move everything to configuration options

3. goals • code review/architecture • customization methods • best practices • examples

4. architecture PEAR jQuery User

5. directory structure • CRM: application • templates: Smarty .tpl files • packages: included libraries • extern: externally triggered files (IPN) • css • Joomla

6. directory structure: CRM • component/feature area • DAO: data access objects • BAO: business access objects • Form • Page • [Controller/Selector/xml/StateMachine]

7. example

8. class/tpl correlation • CRM/Event/Form/Registration/Register.php • CRM_Event_Form_Registration_Register • templates/CRM/Event/Form/Registration/Register.tpl

9. standard form flow • ::preProcess • ::setDefaultValues • ::buildQuickForm • ::formRule • ::postProcess

10. customization methods • PHP overrides • Smarty overrides • file.extra.tpl addendum • Joomlaplugin • CiviCRM extensions • reports • search • payment gateway • modules*

11. don’t hack core! • just don’t do it… unless you have no other choice…

12. debugging tips • print variables • CRM_Core_Error::debug(‘varname’, $varObj); [log to screen] • CRM_Core_Error::debug_var(‘varname’,$varObj); [log to file] • CRM_Core_Error::debug_log_message($msg, TRUE/FALSE);[log to screen or file] • CRM_Core_Error::backtrace(); • tail log file • /media/civicrm/ConfigAndLog/FILE.log

13. debugging tips • enable debugging • display smarty variables • append: &smartyDebug=1 • search “.tpl” in page source to trace file • log queries to file • define( 'CIVICRM_DAO_DEBUG', 1 ); • log mail to file • define('CIVICRM_MAIL_LOG', '/path/to/mail.log');

14. php/tpl overrides • define location • Administer > System Settings > Directories • follow folder pattern for core files • pros: • complete control over code flow/layout without hacking core • cons: • must be maintained through upgrades • be sure to comment thoroughly!

15. php override example • report templates are a common area where clients want customizations. • the template defines the fields, filters, sort options, calculations, action options, and display • most of those options are defined in a large array during class construction • current employer report: • remove country • add relationship end date • add relationship enabled/disabled

16. smarty override example • any page rendered by CiviCRM is pushed through the Smarty templating engine • the Smarty file contains the html and passed variables to be rendered • events and profiles may have ID-specific subfolders • CRM/Event/Form/Registration/1/Register.tpl

17. file.extra.tpl files • instead of overriding Smarty files, you can create a new file named filename.extra.tpl • benefit: avoid modifying and maintaining the entire .tpl file – only need to interact with the elements you are modifying • relies on js/jquery for most implementations • limitations: template files included via another template file is not captured by the .extra insertion code

18. Joomlaplugins • use plugins to implement hooks (events) • wiki.civicrm.org/confluence/display/CRMDOC/Hook+Reference • within your plugin class, implement: • civicrm_hookName(…) { }

19. hooks • modify forms process • impact objects before/after saving • extension lifecycle • ACL • impact GUI (links, page, nav, etc.) • other…

20. plugin example • CiviCRM has a user dashboard page that summarizes the contact’s involvement with your organization • Let’s create a plugin to retrieve the contact’s product purchases from RedShop and include the list in the dashboard

21. api v3 • wiki.civicrm.org/confluence/display/CRMDOC/API+Reference • drupal.demo.civicrm.org/civicrm/ajax/doc/api#explorer • Bindings: PHP/AJAX/REST/Smarty • Actions: Create/Delete/Get/GetCount/ GetSingle/GetFields/GetValue/Replace/ Update • Chainable

22. api:php • standard format to work with objects $params = array( 'version' => 3, 'last_name' => 'Doe', 'contact_type' => 'Individual', ); $contact = civicrm_api('contact', 'get', $params);

23. api:php Array ( [is_error] => 0 [version] => 3 [count] => 2 [values] => Array ( [4] => Array ( [contact_id] => 4 [contact_type] => Individual [contact_sub_type] => [sort_name] => Doe, John [display_name] => Mr. John Doe [do_not_email] => 0 [do_not_phone] => 0 [do_not_mail] => 0 [do_not_sms] => 1 [do_not_trade] => 0 [is_opt_out] => 0 [legal_identifier] => [external_identifier] => [nick_name] => J.D. [legal_name] => [image_URL] => [preferred_mail_format] => Both [first_name] => John [middle_name] => P. [last_name] => Doe [job_title] => Executive Director [birth_date] => [is_deceased] => 0 [deceased_date] => [household_name] => [organization_name] => [sic_code] => [contact_is_deleted] => 0 [gender_id] => 2 [gender] => Male [prefix_id] => 3 [prefix] => Mr. [suffix_id] => [suffix] => [current_employer] => Worldwide United for Food [address_id] => 4 [street_address] => 123 Main Street [supplemental_address_1] => [supplemental_address_2] => [city] => Albany [postal_code_suffix] => [postal_code] => 12208 [geo_code_1] => [geo_code_2] => [state_province_id] => 1031 [state_province_name] => New York [state_province] => NY [country_id] => 1228 [country] => United States [phone_id] => 2 [phone_type_id] => 1 [phone] => 800-123-4567 [email_id] => 4 [email] => john@wuff.org [on_hold] => 0 [im_id] => [provider_id] => [im] => [worldregion_id] => 2 [world_region] => America South, Central, North and Caribbean [id] => 4 )

24. civicrm extensions • CMS-agnostic • can be submitted to the CiviCRM extension directory • installed through:Administer » System Settings » Manage Extensions • payment processors, custom search, custom report, module*

25. extension • create folder in custom extension directory: domain.type.name • create info.xml to define the extension parameters • refer to documentation for xml options and naming conventions • create php and tpl files • php files reside in base directory • tpl files reside in • install/enable/run/test

26. extension • wiki.civicrm.org/confluence/display/CRMDOC/Extensions • wiki.civicrm.org/confluence/display/CRMDOC/Extension+Reference • wiki.civicrm.org/confluence/display/CRMDOC/Create+a+Module+Extension • github.com/totten/civix/ • civicrm.org/extensions

27. sample civi module • custom birthday search via module • provide advanced tools tosearch contacts by birthday, including searching by month, year range, age range, day range

28. joomla extensions • various states of development/version compatibility • http://wiki.civicrm.org/confluence/display/CRMDOC/Joomla%21+Extensions+for+CiviCRM+%283rd+party%29 • http://civicrm.org/extensions • http://extensions.joomla.org/extensions/extension-specific/civicrm • https://github.com/lcdservices

29. extensions • CiviSearchplugin • CiviCRM Group Sync component • CiviAuthenticateplugin • CiviEvent module • CiviUser component • CiviLinkerplugin • Gloriant CiviCRM component • CiviLead

30. resources • www.civicrm.org • book.civicrm.org/[user admin and developer guides] • wiki.civicrm.org/confluence/display/CRMDOC/CiviCRM+Documentation[online documentation]

31. community • wiki: http://wiki.civicrm.org • forum: http://forum.civicrm.org/ • IRC: #civicrm on irc.freenode.net • blogs: http://civicrm.org/blog/ • bug: http://issues.civicrm.org