Commit 4baf94be authored by Mathieu Lutfy's avatar Mathieu Lutfy Committed by Aegir user

Upgrade sumfields to 4.0.1

parent 906e6f44
# Changelog
All notable changes for the Summary Fields extension will be noted here.
## [Unreleased]
### Changed
## [4.0.0] - 2019-02-05
### Added
- This changelog.
- If you are extending Summary Fields, you can now use trigger tables
that don't have the contact_id field. You can specify a tables array
containing the information needed for summary fields to properly
process changes to these tables. See custom.php and civicrm_line_item
table for an example.
### Changed
- All contribution summary fields are now calculated according to the
CiviCRM line item table instead of the contribution table. That means
contributions split between different financial types due to clever
use of price fields will now be calculated properly
- Improved documentation.
- Don't count test participation records.
<?php
use CRM_Sumfields_ExtensionUtil as E;
require_once 'CRM/Core/Form.php';
class CRM_Sumfields_Form_SumFields extends CRM_Core_Form {
......@@ -7,7 +9,7 @@ class CRM_Sumfields_Form_SumFields extends CRM_Core_Form {
$custom = sumfields_get_custom_field_definitions();
if (empty($custom['fields'])) {
// This means neither CiviEvent or CiviContribute are enabled.
CRM_Core_Session::setStatus(ts("Summary Fields is not particularly useful if CiviContribute and CiviEvent are both disabled. Try enabling at least one.", array('domain' => 'net.ourpowerbase.sumfields')));
CRM_Core_Session::setStatus(E::ts("Summary Fields is not particularly useful if CiviContribute and CiviEvent are both disabled. Try enabling at least one."));
return;
}
$trigger_tables = $fieldsets = $field_options = array();
......@@ -23,7 +25,7 @@ class CRM_Sumfields_Form_SumFields extends CRM_Core_Form {
$status_icon = 'fa-times';
if (empty($apply_settings_status)) {
$display_status = ts('The settings have never been saved (newly enabled)', array('domain' => 'net.ourpowerbase.sumfields'));
$display_status = E::ts('The settings have never been saved (newly enabled)');
$status_icon = 'fa-minus-circle';
}
else {
......@@ -43,26 +45,26 @@ class CRM_Sumfields_Form_SumFields extends CRM_Core_Form {
switch($matches[1]) {
case 'scheduled-triggers':
$display_status = ts("Setting changes were saved on %1, but not yet applied; they should be applied shortly.", array(1 => $date, 'domain' => 'net.ourpowerbase.sumfields'));
$display_status = E::ts("Setting changes were saved on %1, but not yet applied; they should be applied shortly.", array(1 => $date));
$status_icon = 'fa-hourglass-start';
break;
case 'scheduled-cron':
$display_status = ts("Setting changes were saved on %1, data calculation will be performed on every cron run.", array(1 => $date, 'domain' => 'net.ourpowerbase.sumfields'));
$display_status = E::ts("Setting changes were saved on %1, data calculation will be performed on every cron run.", array(1 => $date));
$status_icon = 'fa-hourglass-start';
break;
case 'running':
$display_status = ts("Setting changes are in the process of being applied; the process started on %1.", array(1 => $date, 'domain' => 'net.ourpowerbase.sumfields'));
$display_status = E::ts("Setting changes are in the process of being applied; the process started on %1.", array(1 => $date));
$status_icon = 'fa-hourglass-end';
break;
case 'success':
$display_status = ts("Setting changes were successfully applied on %1.", array(1 => $date, 'domain' => 'net.ourpowerbase.sumfields'));
$display_status = E::ts("Setting changes were successfully applied on %1.", array(1 => $date));
$status_icon = 'fa-check';
break;
case 'failed':
$display_status = ts("Setting changes failed to apply; the failed attempt happend on %1.", array(1 => $date, 'domain' => 'net.ourpowerbase.sumfields'));
$display_status = E::ts("Setting changes failed to apply; the failed attempt happend on %1.", array(1 => $date));
break;
default:
$display_status = ts("Unable to determine status (%1).", array(1 => $apply_settings_status, 'domain' => 'net.ourpowerbase.sumfields'));
$display_status = E::ts("Unable to determine status (%1).", array(1 => $apply_settings_status));
}
}
......@@ -89,25 +91,25 @@ class CRM_Sumfields_Form_SumFields extends CRM_Core_Form {
// Add extra settings to fieldsets
if (sumfields_component_enabled('CiviContribute')) {
$label = ts('Financial Types', array('domain' => 'net.ourpowerbase.sumfields'));
$label = E::ts('Financial Types');
$this->add('select', 'financial_type_ids', $label, sumfields_get_all_financial_types(), TRUE, array('multiple' => TRUE, 'class' => 'crm-select2 huge'));
$fieldsets[$custom['optgroups']['fundraising']['fieldset']]['financial_type_ids'] = ts("Financial types to include when calculating contribution related summary fields.", array('domain' => 'net.ourpowerbase.sumfields'));
$fieldsets[$custom['optgroups']['fundraising']['fieldset']]['financial_type_ids'] = E::ts("Financial types to include when calculating contribution related summary fields.");
}
if (sumfields_component_enabled('CiviMember')) {
$label = ts('Financial Types', array('domain' => 'net.ourpowerbase.sumfields'));
$label = E::ts('Financial Types');
$this->add('select', 'membership_financial_type_ids', $label, sumfields_get_all_financial_types(), TRUE, array('multiple' => TRUE, 'class' => 'crm-select2 huge'));
$fieldsets[$custom['optgroups']['membership']['fieldset']]['membership_financial_type_ids'] = ts("Financial types to include when calculating membership related summary fields.", array('domain' => 'net.ourpowerbase.sumfields'));
$fieldsets[$custom['optgroups']['membership']['fieldset']]['membership_financial_type_ids'] = E::ts("Financial types to include when calculating membership related summary fields.");
}
if (sumfields_component_enabled('CiviEvent')) {
$label = ts('Event Types', array('domain' => 'net.ourpowerbase.sumfields'));
$label = E::ts('Event Types');
$this->add('select', 'event_type_ids', $label, sumfields_get_all_event_types(), TRUE, array('multiple' => TRUE, 'class' => 'crm-select2 huge'));
$label = ts('Participant Status (attended)', array('domain' => 'net.ourpowerbase.sumfields'));
$label = E::ts('Participant Status (attended)');
$this->add('select', 'participant_status_ids', $label, sumfields_get_all_participant_status_types(), TRUE, array('multiple' => TRUE, 'class' => 'crm-select2 huge'));
$label = ts('Participant Status (did not attend)', array('domain' => 'net.ourpowerbase.sumfields'));
$label = E::ts('Participant Status (did not attend)');
$this->add('select', 'participant_noshow_status_ids', $label, sumfields_get_all_participant_status_types(), TRUE, array('multiple' => TRUE, 'class' => 'crm-select2 huge'));
$fieldsets[$custom['optgroups']['event_standard']['fieldset']] += array(
......@@ -119,30 +121,30 @@ class CRM_Sumfields_Form_SumFields extends CRM_Core_Form {
$this->assign('fieldsets', $fieldsets);
$bd_label = ts('How often should summary data be updated?', array('domain' => 'net.ourpowerbase.sumfields'));
$bd_label = E::ts('How often should summary data be updated?');
$bd_options = array(
'via_triggers' => ts("Instantly", array('domain' => 'net.ourpowerbase.sumfields')),
'via_cron' => ts("When ever the cron job is run (increases performance on large installation)", array('domain' => 'net.ourpowerbase.sumfields'))
'via_triggers' => E::ts("Instantly"),
'via_cron' => E::ts("When ever the cron job is run (increases performance on large installation)")
);
$this->addRadio('data_update_method', $bd_label, $bd_options);
$label = ts('When should these changes be applied?', array('domain' => 'net.ourpowerbase.sumfields'));
$label = E::ts('When should these changes be applied?');
$options = array(
'via_cron' => ts("On the next scheduled job (cron)", array('domain' => 'net.ourpowerbase.sumfields')),
'on_submit' => ts("When I submit this form", array('domain' => 'net.ourpowerbase.sumfields'))
'via_cron' => E::ts("On the next scheduled job (cron)"),
'on_submit' => E::ts("When I submit this form")
);
$this->addRadio('when_to_apply_change', $label, $options);
$this->addButtons(array(
array(
'type' => 'next',
'name' => ts('Save'),
'name' => E::ts('Save'),
'spacing' => '&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;',
'isDefault' => TRUE,
),
array(
'type' => 'cancel',
'name' => ts('Cancel'),
'name' => E::ts('Cancel'),
),
)
);
......@@ -205,14 +207,14 @@ class CRM_Sumfields_Form_SumFields extends CRM_Core_Form {
if ($values['when_to_apply_change'] == 'on_submit') {
$returnValues = array();
if (!sumfields_gen_data($returnValues)) {
$session::setStatus(ts("There was an error applying your changes.", array('domain' => 'net.ourpowerbase.sumfields')), ts('Error'), 'error');
$session::setStatus(E::ts("There was an error applying your changes."), E::ts('Error'), 'error');
}
else {
$session::setStatus(ts("Changes were applied successfully.", array('domain' => 'net.ourpowerbase.sumfields')), ts('Saved'), 'success');
$session::setStatus(E::ts("Changes were applied successfully."), E::ts('Saved'), 'success');
}
}
else {
$session::setStatus(ts("Your summary fields will begin being generated on the next scheduled job. It may take up to an hour to complete.", array('domain' => 'net.ourpowerbase.sumfields')), ts('Saved'), 'success');
$session::setStatus(E::ts("Your summary fields will begin being generated on the next scheduled job. It may take up to an hour to complete."), E::ts('Saved'), 'success');
}
$session->replaceUserContext(CRM_Utils_System::url('civicrm/admin/setting/sumfields'));
}
......
<?php
use CRM_Sumfields_ExtensionUtil as E;
/**
* Collection of upgrade steps.
*/
class CRM_Sumfields_Upgrader extends CRM_Sumfields_Upgrader_Base {
/**
* Re-build triggers and re-generate data.
*
* Since version 4.0.0 now tracks contributions by line items, we need
* to rebuild triggers and rebuild data to ensure we are current.
*
* @return TRUE on success
* @throws Exception
**/
public function upgrade_4000() {
$this->ctx->log->info('Planning update 4000'); // PEAR Log interface
$this->addTask(E::ts('Regenerate Data'), 'regenerateData');
$this->addTask(E::ts('Rebuild Triggers'), 'triggerRebuild');
return TRUE;
}
public function triggerRebuild() {
CRM_Core_DAO::triggerRebuild();
return TRUE;
}
public function regenerateData() {
return sumfields_generate_data_based_on_current_data();
}
}
Summary Fields make it easier to search for major donors, recent donors,
lapsed donors as well as to show a synopsis of a donor’s history.
Summary Fields extends your CiviCRM data by creating a tab of fields
that total up and summarize donation history.
Summary Fields make it easier to search for contacts (or insert tokens) based
on a summary or other calculation of the contact's previous interactions.
Once you've completed set-up, a new tab will appear alongside other tabs
in contact records showing the totals for each individual.
For example, you can access a contact's total lifetime contribution amount,
last membership contribution date, number of attended events, total of last
year's deductible contributions, and more.
All of the data in the Summary Fields group are calculated from other
data entered into your CiviCRM as contributions, membership or event
participation. The benefit of making these items available as calculated
fields is that they can be searched in Advanced Search and used as a
basis for a smart group as well as for tokens in email and print
communications.
Summary Fields extends your CiviCRM data by creating a tab of fields that total
up and summarize the fields you choose.
Once you've completed set-up, a new tab will appear alongside the other tabs in
contact records showing the totals for each individual. The fields in this tab
will appears in Advanced Search and will be available as tokens for emails or
PDF merges.
![Admin Screen](AdminScreen.png)
Adding more fields
Getting Started
-----------------
After installing the extension, you must configure it before any summary fields
are calculated.
You can configure the extension by going to `Adminster -> Customize Data and
Screens -> Summary Fields.`
Choose the fields you want to enable. Every field you enable will slow down the
performance of your database just a little, so only enable fields you really
need. You can always come back and enable additional fields later.
In addition, you can configure how Summary Fields works. For example, you can
choose which financial types should be included when calculating contribution
amounts. And you can dedide which participant status types should be considered
"attended" and which should be a considered a "no-show".
Want more summary fields?
------------------
This extension provides `hook_civicrm_sumfields_definitions` which allows you to add additional summary fields of your own.
Do you want more summary fields? Check out [Joinery's More Summary
Fields](https://github.com/twomice/com.joineryhq.jsumfields) for an extension
providing yet more fields.
Wnat *still more fields*?
You can write your own extension. It's easy!
This extension provides `hook_civicrm_sumfields_definitions` which allows you
to add additional summary fields of your own.
Example:
/**
......@@ -28,11 +56,18 @@ Example:
*/
function mycustom_civicrm_sumfields_definitions(&$custom) {
$custom['fields']['hard_and_soft'] = array(
// Choose which group you want this field to appear with.
'optgroup' => 'mycustom', // could just add this to the existing "fundraising" optgroup
'label' => 'All contributions + soft credits',
'data_type' => 'Money',
'html_type' => 'Text',
'weight' => '15',
'text_length' => '32',
// A change in the "trigger_table" should cause the field to be re-calculated.
'trigger_table' => 'civicrm_contribution',
// A parentheses enclosed SQL statement with a function to ensure a single
// value is returned. The value should be restricted to a single
// contact_id using the NEW.contact_id field
'trigger_sql' => '(
SELECT COALESCE(SUM(cont1.total_amount), 0)
FROM civicrm_contribution cont1
......@@ -41,8 +76,6 @@ Example:
WHERE (cont1.contact_id = NEW.contact_id OR soft.contact_id = NEW.contact_id)
AND cont1.contribution_status_id = 1 AND cont1.financial_type_id IN (%financial_type_ids)
)',
'trigger_table' => 'civicrm_contribution',
'optgroup' => 'mycustom', // could just add this to the existing "fundraising" optgroup
);
// If we don't want to add our fields to the existing optgroups or fieldsets on the admin form, we can make new ones
$custom['optgroups']['mycustom'] = array(
......@@ -51,3 +84,14 @@ Example:
'component' => 'CiviContribute',
);
}
When writing your own summary fields, here are some tips:
* Pick the table with the data you are calculating. This is the trigger_table
- when a change is made to this table, the summary field is updated.
* If this table has the contact_id field, then you are all set. Your
trigger_sql should reference NEW.contact_id
* If this table does not have a contact_id field, then it must contain a field
that can be used to calculate a contact_id (see the civicrm_line_item
examples in custom.php)
......@@ -8,14 +8,15 @@
<author>Jamie McClelland/Progressive Technology Project</author>
<email>jamie@progressivetech.org</email>
</maintainer>
<releaseDate>2018-04-09</releaseDate>
<version>3.1.3</version>
<releaseDate>2019-02-05</releaseDate>
<version>4.0.1</version>
<develStage>stable</develStage>
<compatibility>
<ver>4.4</ver>
<ver>4.5</ver>
<ver>4.6</ver>
<ver>4.7</ver>
<ver>5.0</ver>
</compatibility>
<comments>This extension adds custom data fields and triggers to your database. Disabling this extension will cause the custom data fields to be deleted and triggers removed.</comments>
<civix>
......
#: custom.php sumfields.php
msgid "Summary Fields"
msgstr ""
#: CRM/Sumfields/Form/SumFields.php
msgid "Active Fields"
msgstr ""
#: CRM/Sumfields/Form/SumFields.php
msgid "Financial Types"
msgstr ""
#: CRM/Sumfields/Form/SumFields.php
msgid "Membership Financial Types"
msgstr ""
#: CRM/Sumfields/Form/SumFields.php
msgid "Event Types"
msgstr ""
#: CRM/Sumfields/Form/SumFields.php
msgid "Participant Status"
msgstr ""
#: CRM/Sumfields/Form/SumFields.php
msgid "Save"
msgstr ""
#: CRM/Sumfields/Form/SumFields.php
msgid "Cancel"
msgstr ""
#: CRM/Sumfields/Form/SumFields.php
msgid "All summary fields have been updated."
msgstr ""
#: custom.php
msgid "Total Lifetime Contributions"
msgstr ""
#: custom.php
msgid "Total Contributions this Year"
msgstr ""
#: custom.php
msgid "Total Deductible Contributions this Year"
msgstr ""
#: custom.php
msgid "Total Contributions last Year"
msgstr ""
#: custom.php
msgid "Total Deductible Contributions last Year"
msgstr ""
#: custom.php
msgid "Total Contributions Year Before Last"
msgstr ""
#: custom.php
msgid "Total Deductible Contributions Year Before Last"
msgstr ""
#: custom.php
msgid "Amount of last contribution"
msgstr ""
#: custom.php
msgid "Date of Last Contribution"
msgstr ""
#: custom.php
msgid "Date of First Contribution"
msgstr ""
#: custom.php
msgid "Largest Contribution"
msgstr ""
#: custom.php
msgid "Count of Contributions"
msgstr ""
#: custom.php
msgid "Average Annual (Calendar Year) Contribution"
msgstr ""
#: custom.php
msgid "Date of Last Membership Payment"
msgstr ""
#: custom.php
msgid "Amount of Last Membership Payment"
msgstr ""
#: custom.php
msgid "Name of the last attended event"
msgstr ""
#: custom.php
msgid "Date of the last attended event"
msgstr ""
#: sumfields.php
msgid "Deleted custom field '%s'"
msgstr ""
#: sumfields.php
msgid "Failed to get the custom group parameters. Can't add new fields."
msgstr ""
#: sumfields.php
msgid "Added custom field '%s'"
msgstr ""
#: sumfields.php
msgid "Error deleting custom field $field '%s'"
msgstr ""
#: sumfields.php
msgid "Error adding custom field $field '%s'"
msgstr ""
#: templates/CRM/Sumfields/Form/SumFields.tpl
msgid ""
"Please indicate which of the available summary fields you would like to "
"enable."
msgstr ""
#: templates/CRM/Sumfields/Form/SumFields.tpl
msgid ""
"Please indicate the financial types you would like included when calculating "
"contribution related summary fields."
msgstr ""
#: templates/CRM/Sumfields/Form/SumFields.tpl
msgid ""
"Please indicate the financial types you would like included when calculating "
"membership payment related summary fields."
msgstr ""
#: templates/CRM/Sumfields/Form/SumFields.tpl
msgid ""
"Please indicate the event types you would like included when calculating "
"event-related summary fields."
msgstr ""
#: templates/CRM/Sumfields/Form/SumFields.tpl
msgid ""
"Please indicate the participat status you would like included when "
"calculating event-related summary fields."
msgstr ""
#: templates/CRM/Sumfields/Form/SumFields.tpl
msgid ""
"Please be patient - when saving these settings, the contents of the summary "
"table is re-created from scratch. This procedure may take a few minutes."
msgstr ""
#: sumfields.php
msgid "Error creating custom field '%s'"
msgstr ""
#: sumfields.php
msgid "Error deleting '%s'"
msgstr ""
#: sumfields.php
msgid "Error deleting custom field '%s': %s"
msgstr ""
#: sumfields.php
msgid "Error adding custom field '%s': %s"
msgstr ""
#!/bin/sh
l10n_tools="../../civi_l10n_tools"
${l10n_tools}/bin/create-pot-files-extensions.sh sumfields ../ ./
......@@ -2,6 +2,76 @@
// AUTO-GENERATED FILE -- Civix may overwrite any changes made to this file
/**
* The ExtensionUtil class provides small stubs for accessing resources of this
* extension.
*/
class CRM_Sumfields_ExtensionUtil {
const SHORT_NAME = "sumfields";
const LONG_NAME = "net.ourpowerbase.sumfields";
const CLASS_PREFIX = "CRM_Sumfields";
/**
* Translate a string using the extension's domain.
*
* If the extension doesn't have a specific translation
* for the string, fallback to the default translations.
*
* @param string $text
* Canonical message text (generally en_US).
* @param array $params
* @return string
* Translated text.
* @see ts
*/
public static function ts($text, $params = array()) {
if (!array_key_exists('domain', $params)) {
$params['domain'] = array(self::LONG_NAME, NULL);
}
return ts($text, $params);
}
/**
* Get the URL of a resource file (in this extension).
*
* @param string|NULL $file
* Ex: 'css/foo.css'.
* @return string
* Ex: 'http://example.org/sites/default/ext/org.example.foo/css/foo.css'.
*/
public static function url($file = NULL) {
return CRM_Core_Resources::singleton()->getUrl(self::LONG_NAME, $file);
}
/**
* Get the path of a resource file (in this extension).
*
* @param string|NULL $file
* Ex: 'css/foo.css'.
* @return string
* Ex: '/var/www/example.org/sites/default/ext/org.example.foo/css/foo.css'.
*/
public static function path($file = NULL) {
// return CRM_Core_Resources::singleton()->getPath(self::LONG_NAME, $file);
return __DIR__ . ($path === NULL ? '' : (DIRECTORY_SEPARATOR . $file));
}
/**
* Get the name of a class within this extension.
*
* @param string $suffix
* Ex: 'Page_HelloWorld' or 'Page\\HelloWorld'.
* @return string
* Ex: 'CRM_Foo_Page_HelloWorld'.
*/
public static function findClass($suffix) {
return self::CLASS_PREFIX . '_' . str_replace('\\', '_', $suffix);
}
}
use CRM_Sumfields_ExtensionUtil as E;
/**
* (Delegated) Implements hook_civicrm_config().
*
......@@ -190,7 +260,7 @@ function _sumfields_civix_civicrm_managed(&$entities) {
$es = include $file;
foreach ($es as $e) {
if (empty($e['module'])) {
$e['module'] = 'net.ourpowerbase.sumfields';
$e['module'] = E::LONG_NAME;
}
$entities[] = $e;
if (empty($e['params']['version'])) {
......@@ -222,7 +292,7 @@ function _sumfields_civix_civicrm_caseTypes(&$caseTypes) {
// throw new CRM_Core_Exception($errorMessage);
}
$caseTypes[$name] = array(
'module' => 'net.ourpowerbase.sumfields',
'module' => E::LONG_NAME,
'name' => $name,
'file' => $file,
);
......@@ -248,7 +318,7 @@ function _sumfields_civix_civicrm_angularModules(&$angularModules) {
$name = preg_replace(':\.ang\.php$:', '', basename($file));
$module = include $file;
if (empty($module['ext'])) {
$module['ext'] = 'net.ourpowerbase.sumfields';
$module['ext'] = E::LONG_NAME;
}
$angularModules[$name] = $module;
}
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment