-# org.civicrm.afform
+# org.civicrm.afform (Early Proof of Concept)
-
+> 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`).
+
+
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.
```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)
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/<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/pretty-page"}' > afform/foobar/meta.json
-$ echo '<div>Hello {{routeParams.name}}</div>' > 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 `<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
+## 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)
projects / civicrm-core.git / blobdiff