CRM-20600 Expose AngularJS screens to hooks

Overview

CiviCRM supports a set of hooks that allow third-parties to programmatically inject extra content/form elements on any page written in QuickForm/Smarty. This issue aims to provide a similar benefit by enabling third-parties to inject extra content on any page written in AngularJS.

Proposed solution

• Core updates
  • Define a hook in which one can manipulate Angular HTML partials using phpQuery ( https://github.com/electrolinux/phpquery )
  • Define a hook in which one can update dependency list for an Angular module.
  • Define a hook in which one can manipulate JS "settings" data
  • Enable aggressive caching of the AngularJS *.json resources (partials+translations)
  • Define a status-check: if a hook modifies an Angular HTML file, and if that file isn't flagged for downstream customization, then display a warning.
• Other deliverables
  • Implement an example extension which manipulates the "New Mailing" screen to inject a new field, "Keywords".
  • Publish documentation explaining the example extension.
  • Publish documentation of the hooks created

Discussion

• The base page "civicrm/a" is indiscriminate about which files it sends – this means that any/all work for hooking/parsing/translating HTML snippets must be completed for that page. Rather than add even more overhead, we'll precompute this data and store it in a public cache file. The result should be both faster and more flexible than the old system.
• If you alter an HTML document to call some new directives, this may constitute a change in the Angular dependency graph. I think we'll need a way to modify the dependency.
• IMHO, the QuickForm/Smarty hooks are difficult for downstream devs because they took a short-cut: they exposed the entire form system as the "contract" for downstream devs, but many of these elements weren't conceived/written/tested/maintained as a "contract". (In other words, they skipped the hard work of OHUPA-1 and went straight to OHUPA-2.) I appreciate that we want progress on this before having elegant component library. The status-check is a compromise: you can hook into any Angular stuff, but it may show a warning to the sysadmin if you hook into something that isn't officially flagged.

Acceptance criteria

• Existing AngularJS screens still work (in normal mode).
• Existing AngularJS screens still work (in debug mode).
• The example extension is able to save+load a list of "keywords" for each mailing.
• Page-load time is not significantly worse than before. (Preferably, better than before.)