README.md - Multiple updates

diff --git a/ext/afform/README.md b/ext/afform/README.md
index 81afea183263e6ed6af0d992679747dbf5b5e46f..d86f289465a1f9474a9c7d4078fe8d9259817bb3 100644 (file)
--- a/ext/afform/README.md
+++ b/ext/afform/README.md
@@ -39,7 +39,7 @@ git clone https://github.com/FIXME/org.civicrm.afform.git
 cv en afform
 ```
 
-## Usage (Developers): Create a form
+## Development: Quick Start
 
 As an upstream publisher of a form, you can define the default, canonical
 substance of the form by creating a folder named `afform/<MY-FORM>`. In
@@ -48,17 +48,34 @@ this example, we create a form named `foobar`:
 ```
 $ cd /path/to/my/own/extension
 $ mkdir -p afform/foobar
-$ echo '{"server_route": "civicrm/foobar"}' > afform/foobar/meta.json
-$ echo '<div>Hello {{param.name}}</div>' > afform/foobar/layout.html
+$ echo '{"server_route": "civicrm/pretty-page"}' > afform/foobar/meta.json
+$ echo '<div>Hello {{routeParams.name}}</div>' > afform/foobar/layout.html
 $ cv flush
-$ cv url civicrm/foobar?name=world
+```
+
+A few things to note:
+
+* The file `layout.html` is an AngularJS HTML document. It has access to all the general templating features, such as variable substition
+  (`{{routeParams.name}}`) and the standard library of directives (`ng-if`, `ng-style`, `ng-repeat`, etc).
+* After creating a new form or file, we should flush the cache.
+* If you're going to actively edit/revise the content of the file, then you should navigate
+  to **Administer > System Settings > Debugging** and disable asset caching.
+
+Now that we've created a form, we'll want to determine its URL:
+
+```
+$ cv url civicrm/pretty-page
+"http://dmaster.localhost/civicrm/pretty-page"
+$ cv url civicrm/pretty-page/#/?name=world
+"http://dmaster.localhost/civicrm/pretty-page/#/?name=world"
 ```
 
 You can open the given URL in a web-browser.
 
-## Usage (Developers): Programmatically read and write forms
+## Development: Form CRUD API
 
-Downstream, administrators may customize the form.
+Now that we've defined a baseline form, it's possible for administrators and
+GUI applications to inspect and revise this form using the API.
 
 ```
 $ cv api afform.getsingle name=foobar
@@ -74,7 +91,7 @@ $ cv api afform.getsingle name=foobar
     "layout": {
         "#tag": "div",
         "#children": [
-            "Hello {{param.name}}"
+            "Hello {{routeParams.name}}"
         ]
     },
     "id": "foobar"
@@ -91,19 +108,46 @@ $ cv api afform.create name=foobar title="The Foo Bar Screen"
 }
 ```
 
-## Usage (Developers): Render a form
+## Development: Scope variables and functions
+
+In AngularJS, every component has its own *scope* -- which defines a list of variables you can access.
+
+By default, `afform` provides a few variables in the scope of every form:
+
+* `routeParams`: This is a reference to the [$routeParams](https://docs.angularjs.org/api/ngRoute/service/$routeParams)
+  service. In the example, we used `routeParams` to get a reference to a `name` from the URL.
+* `ts`: This is a utility function which translates strings, as in `{{ts('Hello world')}}`.
 
-(* FIXME *)
+## Development: Every form is an AngularJS directive
 
-## Usage (Developers): Include a customizable subform in your own page
+In the quick-start example, we registered a new route (`"server_route": "civicrm/pretty-page"`) -- this created a
+standalone page with the sole purpose of displaying the `foobar` form.
 
-Suppose you've created an AngularJS UI based on [the developer
-documentation](https://docs.civicrm.org/dev/en/latest/framework/angular/quickstart/).  You'd like to use the
-customizable `foobar` form as part of your UI.  Fortunately, `foobar` is available as an AngularJS module named
-`afformFoobar`.  You can use it with two steps:
+However, there's no obligation to use the `foobar` form in a standalone fashion.  Think of `foobar` as a *re-usable
+sub-form* or as a *directive*.  If you've created an AngluarJS application, then you can embed `foobar` with
+two small steps:
 
-1. In your module metadata (`ang/MYMODULE.ang.php`), update the `requires` to include `afformFoobar`.
-2. In your HTML template, use the directive `<div afform-foobar="..."></div>`.
+1. In your application, declare a dependency on module `afformFoobar`. This is usually done in `ang/MYMODULE.ang.php`
+   and/or `ang/MYMODULE.js`.
+2. In your HTML template, use the directive `<div afform-foobar=""></div>`.
+
+This technique is particularly useful if you want to provide extra data for the form author to use.  For example, your
+application might pass in the current phase of the moon:
+
+```html
+<div afform-foobar="{phaseOfMoon: 'waxing'}"></div>
+```
+
+Now, in `afform/foobar/layout.html`, you can use the `phaseOfMoon`:
+
+```html
+Hello, {{routeParams.name}}. The moon is currently {{options.phaseOfMoon}}.
+```
+
+
+```html
+Hello, {{routeParams.name ? routeParams.name : 'anonymous'}}. The moon is currently {{options.phaseOfMoon ? options.phaseOfMoon : 'on hiatus'}}.
+```
 
 ## Known Issues
 
@@ -111,3 +155,4 @@ customizable `foobar` form as part of your UI.  Fortunately, `foobar` is availab
   for checking pre-conditions, reporting errors, handling edge-cases, etc.
 * Although afforms are can be used in AngularJS, they don't fully support tooling like `cv ang:html:list`
   and `hook_civicrm_alterAngular`. We'll need a core patch to allow that.
+* We generally need to provide more services for managing/accessing data (e.g. `crm-api3`).