Writing custom reports

This chapter is a brief introduction to creating a new report in the CiviReport system. You can use the same programming techniques to extend an existing report template. These tasks call for a strong grasp of PHP. More details are available in the wiki page on customizing reports:
http://wiki.civicrm.org/confluence/display/CRMDOC/CiviReport+structure+and+customization.

Creating or changing a report template is the wrong choice when ...

If you want a batch action on an existing result set. CiviReport does not support most of the batch actions.  If your main purpose is to print or send an email to a list of contacts that meet specific criteria, write a custom search.

Report specification

Before starting on a custom report, fill out the form on the CiviCRM wiki for report specifications.  Add your specification there and ask for comments in the forum or on IRC.

Creating a custom template

This section creates a custom report listing all contacts' Display Name, First Name and Last Name.  Note that we'll be talking about both Smarty templates (.tpl files) and PHP report templates--be careful not to confuse the two.
Replacing an existing report with your own version is not recommended because you may need the original too, and because an upgrade of CiviCRM will overwrite your changes with the CiviCRM version. In this section, therefore, we'll create a new Smarty template and a new PHP template for the report. You can also copy a template and report to a new location and edit them to create your custom report.

All reports are located under CRM/Report/Form/ and grouped by component.

Create a new Smarty template and a new PHP template for the report. Because this example creates a report about contacts, we'll create a new report template named Contact.php and a Smarty template named Contact.tpl, both in a custom directory (the Contact.php in the custom directory for php scripts, the Contact.tpl in the custom directory for templates). The paths will look like:

PHP_CUSTOM_PATH/CRM/Report/Form/Contact/Contact.php

TPL_CUSTOM_PATH/CRM/Report/Form/Contact/Contact.tpl
 

Add a base class named CRM_Report_Form_Contact_Contact in Contact.php, Your class must inherit the form class used for the report framework. So Contact.php looks like:

<?php
require_once 'CRM/Report/Form.php';
class CRM_Report_Form_Contact_Contact extends CRM_Report_Form {
}

Your Smarty template file must include the report framework template. Thus, Contact.tpl is:

{include file="CRM/Report/Form.tpl"}

Register your report template in CiviCRM. Go to: Administer ->⁞ CiviReport -> Register Report. Enter the details shown in the following screenshot.

In a constructor, create an array to hold a contact, which in turn hold an array specifying two fields you want to display.

function __construct( ) {
    $this->_columns = array( 'civicrm_contact' =>
    array(
        'dao' => 'CRM_Contact_DAO_Contact',
        'fields' => array( 'first_name' => array( 'title' => ts( 'First Name' ) ), 'last_name' => array( 'title' => ts( 'Last Name' ) ),
    ) ) );
parent::__construct( );
}

Build the display by issuing a SELECT against the database. You can create column headers and fill in each field in the display with the results returned by the SELECT.

    function preProcess( ) {
        parent::preProcess( );
    }
// build select query based on display columns selected
    function select( ) {
        $select = $this->_columnHeaders = array( );
        foreach ( $this->_columns as $tableName => $table ) {
            if ( array_key_exists('fields', $table) ) {
                foreach ( $table['fields'] as $fieldName => $field ) {
                    if ( CRM_Utils_Array::value( 'required', $field ) ||
                    CRM_Utils_Array::value( $fieldName, $this->_params['fields'] )) {                       $select[] = "{$field['dbAlias']} as {$tableName}_{$fieldName}";           // initializing columns as well
           $this->_columnHeaders["{$tableName}_{$fieldName}"]['type']  =
               CRM_Utils_Array::value( 'type', $field );
           $this->_columnHeaders["{$tableName}_{$fieldName}"]['title'] = $field['title'];
                    }
                }
            }
        }
        $this->_select = "SELECT " . implode( ', ', $select ) . " ";
    }
    function from( ) {
        $this->_from = "FROM civicrm_contact {$this->_aliases['civicrm_contact']}";
    }

Your custom report template is ready. Press the Preview button to see the results.
After you've installed and tested your report, add it to the CiviCRM wiki as a patch to the project so that it can be used by others in the community.