CiviCRM/Joomla development/customization Brian Shaughnessy Lighthouse Consulting & Design

CiviCRM/Joomla
development/customization
Brian Shaughnessy
Lighthouse Consulting & Design
www.lcdservices.biz
why customize?
 not-for-profits…
o range widely in the services they provide
o 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
PEAR
BAO
Smarty
Web
jQuery
User
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
o
o
o
o
DAO: data access objects
BAO: business access objects
Form
Page
[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
o
o
o
reports
search
payment gateway
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 country
o add relationship end date
o 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
subfolders
o 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);
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
api:php
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 directory
o 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 civi module
 custom birthday search via module
 provide advanced tools to search contacts by
birthday, including searching by month, year
range, age range, day range
joomla extensions
 various states of development/version
compatibility
 http://wiki.civicrm.org/confluence/display/CR
MDOC/Joomla%21+Extensions+for+CiviCRM+
%283rd+party%29
 http://civicrm.org/extensions
 http://extensions.joomla.org/extensions/exte
nsion-specific/civicrm
 https://github.com/lcdservices
extensions








CiviSearch plugin
CiviCRM Group Sync component
CiviAuthenticate plugin
CiviEvent module
CiviUser component
CiviLinker plugin
Gloriant CiviCRM component
CiviLead
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