This documentation relates to CiviCRM version 3.2. It's not maintained anymore.
Current version of documentation.

CiviReport structure and customization

Aller directement à la fin des métadonnées
Aller au début des métadonnées

This page refers to outdated version of CiviCRM. Check current version of documentation.


Documentation Search


CiviCRM 3.2 Documentation

Support and Participation

Developer Resources


CiviCRM book!

Make sure to check out Understanding CiviCRM as well! You can also support this project by ordering a hard copy.

This is user-contributed information determined by looking through the samples and code files. Documentation and code for third-party reports can be added as "child pages" below this page.

Steps to add your own report.

  1. Find an existing one under CRM/Report/Form/ that is similar to one you want.
  2. Set up custom php and template folders as described at http://wiki.civicrm.org/confluence/display/CRMDOC/Customize Built-in, Profile, Contribution and Event Registration Screens
  3. Copy the .php file to <custom_php_path>/CRM/Report/Form/XXX where XXX depends on what type of report it is and where you want it to live. For example if it's a basic report about contacts you might want to put it under Contact.
  4. Change the class name in the file to correspond to the path where you put it.
  5. Either copy the corresponding .tpl from templates/CRM/Report/Form/... into <custom_template_path>/CRM/Report/Form/XXX, or create a .tpl file with just the following line to get the standard template:
    {include file="CRM/Report/Form.tpl"}
  6. Under Administer CiviCRM >> CiviReport >> Manage Templates add your own template. This is straightforward except for URL you can put whatever you want, and then that is appended to /civicrm/report in the actual url to reach it. For example if you put contact/mine, your report will be at http://<server>/civicrm/report/contact/mine

Customizing php form:

Consider the following "civicrm_contact" table for example:

Contact ID

First Name

Last Name

Display Name

1

Sheila

Reynolds

Ms Sheila W Reynolds Sr

2

Bruce

Roberts

Mr Bruce A Roberts Sr

3

Melinda

Jones

Mrs Melinda R Jones Jr

4

Chetan

Jameson

Mrs Chetan O Jameson Sr

5

Bill

Jones

Ms Bill G Jones Sr

Case I: Use shortcut method to build a Report to just display the content of the above table

1. Assuming we don't have any input criteria initialize $this->_columns as

2. Define postProcess() method:

3. Make sure the tpl has {include file="CRM/Report/Form.tpl"} as content.

And you done.

Case II: Use standard method and make report work based on display columns selected.
1. Now since we want user to decide which columns to display:

2. Build select clause based on columns selected: Please note: below method may need not be written for v3.3 or later, as select clause is built by parent class.

3. Build from clause:

4. You are done. But if postProcess() was supposed to be implemented, this is how it would be:

Done.

Information about the structure and parameters in the .php file

This is not a comprehensive list.

function __construct()

This is where you put the field and filter definitions. Assign $this->_columns to an array of table definitions. The key is any name you want, but it makes sense to use the table name unless you need to use the same table twice in the query.

|| Parameter || Value || Description ||

alias

<text>

To give the table another name. (It's not clear why this exists because you can achieve the same thing by using a different key?)

dao

Class name

The DAO for the table

bao

Class name

The BAO for the table, if you need something fancier. If both dao and bao are specified the BAO wins.

fields

<array>

See below.

filters

<array>

See below.

group_bys

<array>

See below.

order_bys

<array>

See below.

fields

fields is the list of fields that the user can select to display or not.

Parameter

Value

Description

required

true/false

The user has no choice

default

true/false

Selected by default

no_repeat

true/false

repeated fileds/value in the column are not allowed

no_display

true/false

Doesn't appear in the output, but can be used in the query

name

<text>

To give the field another name. This defaults to the key for this field array. See note below.

alias

<text>

To give the table another name, just for this field. This defaults to alias for the table array, or if not set, the key for the table array. See note below.

dbAlias

<text>

To give the field another name. See note below.

statistics

array

To make query compute stats like sum, count, avg on a numeric field. Applies to both "display columns" and "filters".

The way name, alias, and dbAlias work together is that if you set dbAlias directly, then it's whatever you set it to. Otherwise dbAlias gets computed as alias.name

.

Then beyond that it seems that as long as you make what you use in select() and other functions match what you did here, it will work. Basically you use whatever combination of the array key, name, alias, and dbAlias so that you have enough uniqueness and that it generates valid SQL.

filters

filters is a list of filters related to the table that the user can use to filter the results.

Parameter

Value

Description

title

<text>

The caption/label

default

<text>

The default value of the filter

operatorType

CRM_Report_Form::OP_XXX

The widget type. Look in CRM_Report_Form for the possible values. Note that some like DATE have some built-in functionality for you. Also note that some filters have built-in functionality even without a type, like the sort_name in the example above gives the user a choice of "contains", "starts with", etc...

options

<array>

For widgets that have a selection of values. Pass in an array with value as the key and label as the value, e.g. array('1'=>'Low', '2'=>'Medium', '3'=>'High')

group

true/false

Used for group related form fields for e.g group_id. A true value for this flag, makes the query include the condition inside the main WHERE clause like a normal query. If false, condition is excluded from main clause.

no_display

true/false

When set for a filter makes the filter hidden but can still be used in the query. Required for cases when filter is expected from url and not be present on the form

group_bys

group_bys is a list of fields from the table that the user can select to group the results.

Using grouping will likely require you to customize most of the functions like select(). Also be on the lookout for table joins you might be making that might have multiple rows on the right side of the join, such as activities to targets. It may also require you to set rules to prevent users from making selections that don't make sense. The user may choose to unselect grouping too.

Contribute/Summary.php seems to be a good example of using group_bys.

|| Parameter || Value || Description ||

title

<text>

The caption/label

default

true/false

Select By default

frequency

true/false

if true, more options for group by field are available e.g. receive_date can be grouped by month, week, quarter, year.( only for date related field )

order_bys

order_bys is a list of fields from the table the user can select to affect the ordering of the results.

Parameter

Value

Description

adding custom fields

As of 3.1 (earlier?) you can add custom fields to a report by adding / modifying the 'extends' line

If this line is in the php file then all searchable custom data fields that relate to Contact, Individual, Household, or Organisation will be available in the report. Note that 'Contact' ONLY refers to the custom data groups that extend all contacts and does not also include those that extend Individual. This functionality is not limited to 'contact' related fields and activity, relationship etc fields can be added.

All searchable fields of that type will be added. There is not currently a simple option to only select some.

functions select() and where()

Most of the time you can probably copy these as is. But see note about group_bys.

function from()

This is where you define the tables and joins by setting $this->_from to an SQL string.

function groupBy()

This is where you define the grouping clauses by setting $this->_groupBy to an SQL string.

function alter_display()

This is where you can reformat column values to be links and such.

It also seems to be where you replace values with labels, as opposed to doing it in the SQL? (Can someone confirm if this is the "right" way?)

function statistics()

This is where you set and execute the query to compute aggregates. As noted above you may need to customize if using grouping.

function formRule()

Return an array of strings listing any errors you wish to display to the user based on their selections.

Étiquette
  • Aucun

Creative Commons License
Except where otherwise noted, content on this site is licensed under a Creative Commons Attribution-Share Alike 3.0 United States Licence.