X-Git-Url: https://vcs.fsf.org/?a=blobdiff_plain;f=ext%2Fafform%2FREADME.md;h=97e890ad787b4905f9ba2de67767bab0c1e0b7e7;hb=521b232a706cb95b6ef14ab16802de2a4a13c3b1;hp=d86f289465a1f9474a9c7d4078fe8d9259817bb3;hpb=76a5831d993b2ae0744757c8bc630a6c190736c7;p=civicrm-core.git diff --git a/ext/afform/README.md b/ext/afform/README.md index d86f289465..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 (CLI, Git) @@ -35,124 +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 ``` -## 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/`. In -this example, we create a form named `foobar`: - -``` -$ cd /path/to/my/own/extension -$ mkdir -p afform/foobar -$ echo '{"server_route": "civicrm/pretty-page"}' > afform/foobar/meta.json -$ echo '
Hello {{routeParams.name}}
' > afform/foobar/layout.html -$ cv flush -``` - -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. - -## Development: Form CRUD API - -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 -{ - "name": "foobar", - "requires": [ - "afform", - "crmUi", - "crmUtil" - ], - "title": "", - "description": "", - "layout": { - "#tag": "div", - "#children": [ - "Hello {{routeParams.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" - } -} -``` - -## 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')}}`. - -## Development: Every form is an AngularJS directive - -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. - -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 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 `
`. - -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 -
-``` - -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 +## 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. -* We generally need to provide more services for managing/accessing data (e.g. `crm-api3`). +* [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)