ext/afform/docs/angular.md

   1 # Full AngularJS: Integrating between Afform and vanilla AngularJS
   2
   3 Afform is a subset of AngularJS -- it emphasizes the use of *directives* as a way to *choose and arrange* the parts of
   4 your form.  There is more to AngularJS -- such as client-side routing, controllers, services, etc.  What to do if you
   5 need these?  Here are few tricks:
   6
   7 * You can create your own applications and pages with full AngularJS. (See also: [CiviCRM Developer Guide: AngularJS: Quick Start](https://docs.civicrm.org/dev/en/latest/framework/angular/quickstart/)).
   8   Then embed the afform (like `hello-world`) in your page with these steps:
   9     * Declare a dependency on module (`helloWorld`). This is usually done in `ang/MYMODULE.ang.php` and/or `ang/MYMODULE.js`.
  10     * In your HTML template, use the directive `<div hello-world=""></div>`.
  11     * If you want to provide extra data, services, or actions for the form author -- then pass them along.
  12 * You can write your own directives with full AngularJS (e.g. `civix generate:angular-directive`). These directives become available for use in other afforms.
  13 * If you start out distributing an `afform` and later find it too limiting, then you can change your mind and convert it to static code in full AngularJS.
  14   As long as you name it consistently (`angular.module('helloWorld').directive('helloWorld')`), downstream consumers can use the static version as a drop-in replacement.
  15
  16 > *(FIXME: But if you do convert to static, could you still permit downstream folks customize the HTML?  Let's
  17 > re-assess after we've patched core to allow full participation in the lifecycle of HTML partials.)*