CiviCRMdevelopment/customization

Brian ShaughnessyLighthouse Consulting & Design

www.lcdservices.biz

built to be customized!why?

inevitability of audience not-for-profits…

o range widely in the services they provideo range widely in the business processes they

implement impossible to have one-size-fits-all overkill to move everything to configuration

options

goals code review/architecture customization methods best practices examples

architecture

DB DAO BAO Smarty Web

PEAR UserjQuery

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

directory structure: CRM component/feature area

o DAO: data access objectso BAO: business access objectso Formo Pageo [Controller/Selector/xml/StateMachine]

example

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

Event/Form/Registration/Register.tpl

standard form flow ::preProcess ::setDefaultValues ::buildQuickForm ::formRule ::postProcess

customization methods PHP overrides Smarty overrides

o file.extra.tpl addendum Joomla plugin CiviCRM extensions

o reportso searcho payment gatewayo modules*

don’t hack core! just don’t do it…

unless you have no other choice…

debugging tips print variables

o CRM_Core_Error::debug(‘varname’, $varObj); [log to screen]

o CRM_Core_Error::debug_var(‘varname’,$varObj); [log to file]

o CRM_Core_Error::debug_log_message($msg, TRUE/FALSE);[log to screen or file]

o CRM_Core_Error::backtrace(); tail log file

o /media/civicrm/ConfigAndLog/FILE.log

debugging tips enable debugging display smarty variables

o append: &smartyDebug=1 search “.tpl” in page source to trace file log queries to file

o define( 'CIVICRM_DAO_DEBUG', 1 ); log mail to file

o define('CIVICRM_MAIL_LOG', '/path/to/mail.log');

php/tpl overrides define location

o Administer > System Settings > Directories follow folder pattern for core files pros:

o complete control over code flow/layout without hacking core

cons:o must be maintained through upgrades

be sure to comment thoroughly!

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:

o remove countryo add relationship end dateo add relationship enabled/disabled

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

subfolderso CRM/Event/Form/Registration/1/Register.tpl

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

Joomla plugins use plugins to implement hooks (events) wiki.civicrm.org/confluence/display/CRMDOC

/Hook+Reference

within your plugin class, implement:o civicrm_hookName(…) { }

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

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

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

api:php standard format to work with objects

$params = array( 'version' => 3, 'last_name' => 'Doe', 'contact_type' => 'Individual',);$contact = civicrm_api('contact', 'get', $params);

api:phpArray( [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 )

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*

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

o php files reside in base directoryo tpl files reside in

install/enable/run/test

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

sample module extension custom birthday search via module provide advanced tools for search contacts by

birthday, including searching by month, year range, age range, day range

resources www.civicrm.org book.civicrm.org/

[user admin and developer guides] wiki.civicrm.org/confluence/display/CRMDOC

/CiviCRM+Documentation [online documentation]

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