Documentation

Creating report widgets

Every report in AbleOrganizer contains one or more widgets used to present data or visualize the information being presented. You can create new widgets and add them to reports using the tools described for customizing reports in AbleOrganizer.

If you want to create a new widget to use in your reports, it can be done in two ways: through views or through a panels plugin.

Adding a new widget through views

If you want to create a new widget using views, the process is relatively simple. Create a view and add a new display of type 'Content pane.' This will create a new widget that can be displayed within your reports. When it is saved, it will be immediately available for use within your site.

It's very easy to create a ton of new widgets this way. This comes with a downside: it's easy to get disorganized and clutter up the interface for adding new widgets to reports. In order to avoid this situation and ensure your widgets are easy to manage, pay special attention to the PANE SETTINGS header in views.

  • Give your pane a descriptive administrative title and description that allows other users to easily identify it.
  • Give your pane a category. For example, if you are creating a widget that displays information about donations, categorize it under CRM Core Donation.
  • Assign appropriate permissions to your widget. For example, it's usually appropriate to assign permissions for the report where the widget will be used. If you expect to use the widget in a lot of reports, it's more approrpriate to assign permissions for the feature itself.

Adding a new widget through a panels plugin 

Heads up! Panels plugins are created within custom modules. There is no web-based administrative interface for creating them, you have to write some code to do things this way. There are plenty of examples for how to do this contained in the features that ship with CRM Core.

Creating a panels plugin may seem complex, but AbleOrganizer provides a lot of examples you can use to simplify the process.

Step One: Create a custom module

The first thing to realize is that you are going to need to create a custom module for Drupal. Your module will need to include a callback to hook_ctools_plugin_directory, which will tell the platform where to locate your plugin. Your code should look something like the following.

/** * Implements hook_ctools_plugin_directory(). */
function MYMODULE_ctools_plugin_directory($owner, $plugin_type) {
  if ($owner == 'ctools' && $plugin_type == 'content_types') {
    return 'plugins/' . $plugin_type;
  }
}

Step Two: Create a directory for plugins

From here, within the module directory, you will need to create subfolders that store your plugin code. All of the features that ship with AbleOrganizer store plugins within plugins/content_types. It's fine if you want to use this structure or one of your own.

Once you have added folders within the custom module directory, your next step is to create the file for storing the code for the widget. You will want to store each widget in it's own file. Give the file a descriptive name, followed by the .inc extention. For example: my_widget.inc. 

Step Three: Define your widget

Within the file for the widget, you will want to define the widget itself. Defining the widget is where you register the widget with panels so the platform knows how to work with it. You will create an array similar to the one described below.

$plugin = array(
  'single' => TRUE,
  'title' => t('Donations by Source: Summary Chart'),
  'description' => t('Displays a bar chart containing donation totals for each source.'),
  'category' => t('CRM Core Donations'),
  'edit form' => 'crm_core_donation_sbc_form',
  'render callback' => 'crm_core_donation_sbc',
  'admin info' => 'crm_core_donation_sbc_info',
  'defaults' => array(
    'height' => '',
    'color_series' => '',
    'chart_color' => '',
    'column_width' => '',
    'include_legend' => 0,
  ),
'all contexts' => TRUE,
);

In this example, we are telling the platform some things about our widget through the definition array.

  • The title is 'Donations by source: Summary Chart'
  • The description is 'Displays a bar chart containing donation totals for each source'
  • The widget should be categorized with other 'CRM Core Donations' widgets
  • The function that displays the settings form for the widget is crm_core_donation_sbc_form
  • The function that renders the widget itself is called crm_core_donation_sbc
  • The function that provides information for admnistrators is called crm_core_donation_sbc_info
  • The widget includes some default values that are used on the settings screen. They all happen to be blank.

Step Four: Create the functions

Each of the functions described in the definition array should now be created. Instead of simply repeating each one, look at the code in the CRM Core Donations module to see how each one is defined. You can find the code that is used to define this widget in plugins/content_types/donations_by_source_bar_chart.inc.

Once you have created your widget, it is available for use within your site within any report that uses panels to display information.