Aller directement à la fin des métadonnées
Aller au début des métadonnées
Pre-Requisites
  • Have basic knowledge of MySQL, PHP, Unix, and object-oriented programming
  • Understand the difference between a CiviReport "template" and "instance". This wiki page is about report-templates.
  • Configure an extensions directory. For instructions, see Extensions. This wiki page assumes the directory is "/var/www/extensions", but you should adapt as appropriate.
  • Install civix. For instructions, see https://github.com/totten/civix/ . This wiki page assumes that "civix" is installed and registered in the PATH.

Generate a skeletal extension

To generate a skeletal extension module, we will use "civix generate:report-ext" and pass in the name for our extension. All extension names follow the same convention as Java package names – they look like reversed domain names. (e.g. "com.example.myextension").

Using "civix generate:report-ext"

This creates three files:

  • The info.xml file is a manifest that describes your extension – the name, license, version number, etc. You should edit most information in this file.
  • The myextension.php file contains the form-builder and query-builder for the report.
  • The templates/myextension.tpl file contains the report's HTML template. (Note: This usually delegates responsibility to a core template and does not need to be edited.)
Copy an Existing Report

The reports included in CiviCRM are open-source, and (pursuant to the AGPL license) you have the right to derive new reports from existing reports. This can be useful if one of the existing reports is close to meeting your needs but requires further PHP/SQL customization. To make a new extension based on an existing report:

  • Navigate to the "civicrm/CRM/Report/Form/" within your CiviCRM source tree
  • Determine the class-name of the original report. (For example, the activity report is in the class "CRM_Report_Form_Activity".)
  • Return to your extensions directory and run the "generate:report-ext" command, e.g.
Using "generate:report --copy"

 

Update "info.xml"

The default info.xml file contains some examples and placeholders which should be fixed. Most of these fields can be edited intuitively. If you need detailed specifications, see Extension Reference.

Enable the extension

Now that you've created your extension, you can activate by navigating to "» Administer » System Settings » Manage Extensions." For more detailed instructions, see Extensions.

Modify the PHP file

The auto-generated PHP file is a working report which you can edit, hack, and customize based on your needs. For detailed instructions, see CiviReport Reference.

Deprecated alternative: Manually create a report


Deprecated

In early versions of CiviReport, the extension system was not available, and several CiviReport tutorials were based on an older approach involving a custom PHP path. This approach still works, but it's deprecated for new reports. Never-the-less, the practice was quite common, and some documentation should be preserved.

Pre-Requisites

To manually create and register a new report, follow these instructions.

  1. Find an existing report that is similar to what you want yours to look like.
    These can be found under:  C:\xampp\htdocs\drupal\sites\all\modules\civicrm\CRM\Report\Form\
    There are several folders here each containing different types of reports. In here you are looking for a PHP file.
    For example, you click on the Contact folder and grab the report Summary.php. Your full file path is:C:\xampp\htdocs\drupal\sites\all\modules\civicrm\CRM\Report\Form\Contact
  2. Set up your custom PHP file structure.
    In the custom_php directory (C:\xampp\htdocs\custom_php), create a file structure that matches the report file structure from step one: C:\xampp\htdocs\custom_php\CRM\Report\Form\Contact
  3. Copy the PHP file (Summary.php) from:
    C:\xampp\htdocs\drupal\sites\all\modules\civicrm\CRM\Report\Form\Contact
    And paste it to:
    C:\xampp\htdocs\custom_php\CRM\Report\Form\Contact\
    Rename the copied file appropriate to the report you are going to create. For instance, the file for a report that summarizes demographics by area file might be named AreaDemoSummary.php.
  4. Open your newly named file in the custom_php directory (ex. AreaDemoSummary.php) with a plain-text editor.
    At the top of the file there's a line that reads:
    class CRM_Report_Form_Contact_Summary extends CRM_Report_Form {
    Change your class name so that it matches your file as so:
    class CRM_Report_Form_Contact_AreaDemoSummary extends CRM_Report_Form
  5. Find the matching PHP template.
    All templates are stored in:
    C:\xampp\htdocs\drupal\sites\all\modules\civicrm\templates\CRM. Once here, it's easy to find where your template is stored because the file structure mirrors the file structure from steps 1 and 2.
    For the AreaDemoSummary report example, it's located at:    C:\xampp\htdocs\drupal\sites\all\modules\civicrm\templates\CRM\Report\Form\Contact  Copy the Summary.tpl file.
  6. Set up your custom templates directory. The base directory (C:\xampp\htdocs\civicrm_custom) already exists. Again, we need to recreate the file structure for where our custom template is to be saved.
    So create the file structure as:
    C:\xampp\htdocs\civicrm_custom\CRM\Report\Form\Contact
  7. Paste the .tpl file you copied in step 5 here. Rename it to match your PHP file. For the AreaDemoSummary example, the file is renamed to AreaDemoSummary.tpl.

    Note:There will only be one line in the .tpl  which looks like this:

  8. To add your template, go to the top navigation menu in the application:
    Administer >> CiviReport >> Manage Templates
    Click the button "Register New Report Template." Fill in the necessary values*.

    * Note: Just a side note about the URL field, this is what will be appended to /civicrm/report/ in the URL. In the example, this becomes contact/areademosummary, so the full URL when the example report is viewed is: http://<server>/drupal/civicrm/report/contact/areademosummary

* Note: When entering a value in the "class" field, it is very important you follow the format suggested for that field (e.g., CRM_Report_Form_Contribute_[yourClassName]). This gets translated into the actual path to your custom .tpl file (i.e., civicrm_custom/CRM/Report/Form/Contribute/yourClassName.tpl).

  1. To verify the report configuration, Navigate to Reports --> Create Reports from Templates.
    Once here, you should see your report. For the AreaDemoSummary example, it appeared under Contact Report Templates. If yours is here, you have done everything correctly.

 

Étiquette
  • Aucun