X-Git-Url: https://vcs.fsf.org/?a=blobdiff_plain;f=ext%2Fafform%2FREADME.md;h=97e890ad787b4905f9ba2de67767bab0c1e0b7e7;hb=521b232a706cb95b6ef14ab16802de2a4a13c3b1;hp=81afea183263e6ed6af0d992679747dbf5b5e46f;hpb=83291832d853800db037a26f241fcc9bb9101100;p=civicrm-core.git

diff --git a/ext/afform/README.md b/ext/afform/README.md
index 81afea1832..97e890ad78 100644
--- a/ext/afform/README.md
+++ b/ext/afform/README.md
@@ -1,20 +1,30 @@
-# org.civicrm.afform
+# org.civicrm.afform (Early Proof of Concept)
 
-![Screenshot](/images/screenshot.png)
+> You are looking at the `master` branch of a proof-of-concept module.  It
+> may change radically (without full curation of docs, etc).  For previous
+> iterations with more stable/cogent materials, check other branches (e.g.
+> `0.1`).
+
+![Screenshot](docs/sandbox/3-Free-Blocks-Parent.png)
 
 The Affable Administrative Angular Form Framework (`afform`) is a system for administering AngularJS-based forms
 in CiviCRM which:
 
-1. Allows developers to declaratively define a canonical, baseline form.
-2. Allows administrators (or administrative tools) to use the API to revise the forms.
+1. Allows developers to declaratively define a canonical, baseline form using AngularJS.
+2. Allows administrators (or administrative GUI tools) to use the CRUD API to customize the forms.
+3. Allows developers (or administrators/tools) to embed these forms in other CiviCRM-AngularJS apps.
+4. Allows developers to apply change-sets via hook. (*WIP; pending upstream support*)
 
-The extension is licensed under [AGPL-3.0](LICENSE.txt).
+This extension is a proof-of-concept.  It aims to demonstrate the core model/concept -- however, there are 
+[known issues and additional components](docs/roadmap.md) to address, and some documentation will be easier to approach
+if you already have a basic understanding of CiviCRM API and AngularJS.  It is licensed under [AGPL-3.0](LICENSE.txt).
 
 ## Requirements
 
-* PHP v5.4+
-* CiviCRM v5.3+
+* PHP v7.0+
+* CiviCRM v5.22+
 
+<!--
 ## Installation (Web UI)
 
 This extension has not yet been published for installation via the web UI.
@@ -26,8 +36,9 @@ install it with the command-line tool [cv](https://github.com/civicrm/cv).
 
 ```bash
 cd <extension-dir>
-cv dl org.civicrm.afform@https://github.com/FIXME/org.civicrm.afform/archive/master.zip
+cv dl org.civicrm.afform@https://github.com/totten/afform/archive/master.zip
 ```
+-->
 
 ## Installation (CLI, Git)
 
@@ -35,79 +46,17 @@ Sysadmins and developers may clone the [Git](https://en.wikipedia.org/wiki/Git)
 install it with the command-line tool [cv](https://github.com/civicrm/cv).
 
 ```bash
-git clone https://github.com/FIXME/org.civicrm.afform.git
+git clone https://lab.civicrm.org/extensions/afform.git
 cv en afform
 ```
 
-## Usage (Developers): Create a form
-
-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
-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
-$ cv flush
-$ cv url civicrm/foobar?name=world
-```
-
-You can open the given URL in a web-browser.
-
-## Usage (Developers): Programmatically read and write forms
-
-Downstream, administrators may customize the form.
-
-```
-$ cv api afform.getsingle name=foobar
-{
-    "name": "foobar",
-    "requires": [
-        "afform",
-        "crmUi",
-        "crmUtil"
-    ],
-    "title": "",
-    "description": "",
-    "layout": {
-        "#tag": "div",
-        "#children": [
-            "Hello {{param.name}}"
-        ]
-    },
-    "id": "foobar"
-}
-$ cv api afform.create name=foobar title="The Foo Bar Screen"
-{
-    "is_error": 0,
-    "version": 3,
-    "count": 2,
-    "values": {
-        "name": "foobar",
-        "title": "The Foo Bar Screen"
-    }
-}
-```
-
-## Usage (Developers): Render a form
-
-(* FIXME *)
-
-## Usage (Developers): Include a customizable subform in your own page
-
-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:
-
-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>`.
-
-## Known Issues
+## Developer Documentation
 
-* The code is currently written as a proof-of-concept. There are several `FIXME`/`TODO` declarations in the code
-  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.
+* [Quick Start: Creating the canonical definition of a basic form](docs/quickstart.md)
+* [Writing Forms: Afform as basic AngularJS templates](docs/writing.md) (With example: *Contact Record*)
+* [Embedding Forms: Afform as reusable building-block](docs/embed.md) (With example: *Contact Record*)
+* [Form CRUD: Updating forms via programmatic API](docs/crud.md)
+* [Form Hooks: Updating forms via declarative selector](docs/alter.md) (*WIP; pending upstream support*)
+* [Full AngularJS: Integrating between Afform and vanilla AngularJS](docs/angular.md)
+* [Roadmap and Known Issues](docs/roadmap.md)
+* [Philosophy, Beliefs, Assumptions](docs/philosophy.md)