diff --git a/Gemfile b/Gemfile index a1dda40..5f9e9b0 100644 --- a/Gemfile +++ b/Gemfile @@ -1,3 +1,3 @@ source "https://rubygems.org" -ruby '2.4.6' +ruby '2.4.7' gemspec diff --git a/src/_posts/2019-08-30-civicrm-mailing-validation.md b/src/_posts/2019-08-30-civicrm-mailing-validation.md new file mode 100644 index 0000000..a14b6d4 --- /dev/null +++ b/src/_posts/2019-08-30-civicrm-mailing-validation.md @@ -0,0 +1,129 @@ +--- +layout: post +title: CiviCRM AngularJS extension +description: Adding custom validation to the CiviCRM Mailing form +image: civicrm_validation_header.jpg +category: howto +date: 2019-08-30 +--- + +We support [Campaign Against Arms Trade](https://caat.org.uk), a right-on group +that works to end the international arms trade, with their technology – +including CiviCRM](https://civicrm.org/), a popular open source +"constituent relationship management" platform. + +Among other things, CAAT uses CiviCRM's "Mailing" features to send out emails to +their supporters, and they told us that they're experiencing an annoying bug: if +a user sends out a mailing with the same name (not subject line, just the +internal identifier 🙄) as an existing one, it'll cause the CRM to freeze up +elsewhere. + +As an added challenge, the mailing features of CiviCRM [now use +AngularJS](https://docs.civicrm.org/dev/en/latest/framework/angular/) following +a recent rebuild by the developers, and there aren't many tutorials or examples +out there to customise it. Luckily, the CiviCRM developer community was +super-helpful, and we managed to sort out some in-form validation to prevent +duplicate mailing names for our client… and now for you, too! + +## Create a new extension + +Using [`civix`](https://github.com/totten/civix), we set up a new CiviCRM extension for our code: + + civix generate:module mailing + +(We called our extension `mailing`, because our creative director was occupied +with an Art at the time) + +Our client sensibly keeps their custom CiviCRM extensions in `git`, so at this +stage we initialised a repository, added the boilerplate template code, and +pushed. + +## Set up the AngularJS hook + +A function called `mailing_civicrm_alterAngular()` will get executed whenever +an AngularJS page loads, and you can use a `ChangeSet` to edit an AngularJS +template. Because AngularJS templates specify form logic, this also lets you +change the validation behaviour. Our hook function looks like this: + + function mailing_civicrm_alterAngular($angular) { + $changeSet = \Civi\Angular\ChangeSet::create('mailing_name_unique') + ->alterHtml('~/crmMailing/BlockSummary.html', function(phpQueryObject $doc) { + // name validation + $doc->find('.crm-group:has([crm-ui-id="subform.mailingName"])')->attr('ng-controller', 'NameValidateCtrl'); + $doc->find('[crm-ui-id="subform.mailingName"]')->attr('ng-blur', 'validateName(mailing, \'name\')'); + $doc->find('[crm-ui-id="subform.mailingName"]')->attr('crm-ui-validate', 'isValid'); + }); + + $angular->add($changeSet); + + CRM_Core_Resources::singleton()->addScriptFile('mailing', 'js/disallow-duplicate-names.js'); + } + + +Setting `crm-ui-validate` to `validateName` directly fired the event _way_ too +many times, so instead `validateName` is only called when focus leaves the +field, `ng-blur`, which then sets the `isValid` variable that's checked by +`crm-ui-validate`. + +## Create the `validateName` function + +Then, the code which queries the CiviCRM API to check for mailings with +duplicate names: + + var validating = false; + + (function(angular, $) { + var crmMailing = angular.module('crmMailing'); + + crmMailing.controller('NameValidateCtrl', function($scope) { + $scope.isValid = false; + + $scope.validateName = function(mailing, field) { + if (!validating) { + validating = true; + + CRM.api3('Mailing', 'get', { + "sequential": 1, + "name": mailing[field], + "id": {"!=": mailing.id} + }).then(function(result) { + // do something with result + if (result.count > 0 ) { + $scope.isValid = false; + CRM.alert(ts('There is already a mailing with this name; sending this one will crash CiviCRM!')); + } else { + $scope.isValid = true; + } + }, function(error) { + // oops + console.log(error); + }); + + validating = false; + } + }; + }); + })(angular, CRM.$); + +(saved as `js/disallow-duplicate-names.js`) + +## Conclusion + +Activate the extension, e.g. with `cv` + + $ cv en mailing + +Now, open a mailing and try to give it the same name as an existing one – you +should see the field border turn red, and you'll be prevented from continuing or +sending the mailing: + +!["Mailing name" field showing the field with a red border and red label](/assets/images/2019-08-30_civicrm_validation.png) + +(As a bonus, the extension also sends a notification to the user using +`CRM.alert` to explain the error) + +It does seem like a red border sometimes hangs around the field label even after +the value is valid again… but apart from that, the feature is working great! + +Lastly, props to CAAT for being a great member of the CiviCRM community and +supporting us writing this post to share our work with y'all. diff --git a/src/assets/images/2019-08-30_civicrm_validation.png b/src/assets/images/2019-08-30_civicrm_validation.png new file mode 100644 index 0000000..b2e9521 Binary files /dev/null and b/src/assets/images/2019-08-30_civicrm_validation.png differ diff --git a/src/assets/images/2019-08-30_civicrm_validation_header.jpg b/src/assets/images/2019-08-30_civicrm_validation_header.jpg new file mode 100644 index 0000000..46b82e9 Binary files /dev/null and b/src/assets/images/2019-08-30_civicrm_validation_header.jpg differ