[civicrm-core.git] / ext / afform / docs / crud.md

# Form CRUD: Updating forms via programmatic API

Now that we've defined a baseline form, it's possible for administrators and
GUI applications to inspect the form using the API:

```
$ cv api4 afform.get +w name=helloWorld
{
    "0": {
        "name": "helloWorld",
        "requires": [
            "afCore"
        ],
        "title": "",
        "description": "",
        "is_dashlet": false,
        "is_public": false,
        "server_route": "civicrm/hello-world",
        "layout": {
            "#tag": "div",
            "#children": [
                "Hello {{routeParams.name}}"
            ]
        },
    }
}
```

Additionally, you can also update the forms:

```
$ cv api4 afform.update +w name=helloWorld +v title="The Foo Bar Screen"
{
    "0": {
        "name": "helloWorld",
        "title": "The Foo Bar Screen"
    }
}
```

A few important things to note about this:

* The changes made through the API are only applied on this site.
* Once you make a change with the CRUD API, there will be two copies of the form:
    * `[myextension]/ang/helloWorld.aff.html` is the default, canonical version.
    * `[civicrm.files]/ang/helloWorld.aff.html` is the local, custom version.
* The `layout` field is stored as an Angular-style HTML document (`helloWorld.aff.html`), so you can edit it on disk like
  normal Angular code. However, when CRUD'ing the `layout` through the API, it is presented in JSON-style.

To undo the change, you can use the `revert` API.  This will remove any local overrides so that the canonical content
(`[myextension]/ang/helloWorld.aff.html`) is activated.

```
$ cv api4 afform.revert +w name=helloWorld
```
Commit	Line	Data
	1	# Form CRUD: Updating forms via programmatic API
	2
	3	Now that we've defined a baseline form, it's possible for administrators and
	4	GUI applications to inspect the form using the API:
	5
	6	```
	7	$ cv api4 afform.get +w name=helloWorld
	8	{
	9	"0": {
	10	"name": "helloWorld",
	11	"requires": [
	12	"afCore"
	13	],
	14	"title": "",
	15	"description": "",
	16	"is_dashlet": false,
	17	"is_public": false,
	18	"server_route": "civicrm/hello-world",
	19	"layout": {
	20	"#tag": "div",
	21	"#children": [
	22	"Hello {{routeParams.name}}"
	23	]
	24	},
	25	}
	26	}
	27	```
	28
	29	Additionally, you can also update the forms:
	30
	31	```
	32	$ cv api4 afform.update +w name=helloWorld +v title="The Foo Bar Screen"
	33	{
	34	"0": {
	35	"name": "helloWorld",
	36	"title": "The Foo Bar Screen"
	37	}
	38	}
	39	```
	40
	41	A few important things to note about this:
	42
	43	* The changes made through the API are only applied on this site.
	44	* Once you make a change with the CRUD API, there will be two copies of the form:
	45	* `[myextension]/ang/helloWorld.aff.html` is the default, canonical version.
	46	* `[civicrm.files]/ang/helloWorld.aff.html` is the local, custom version.
	47	* The `layout` field is stored as an Angular-style HTML document (`helloWorld.aff.html`), so you can edit it on disk like
	48	normal Angular code. However, when CRUD'ing the `layout` through the API, it is presented in JSON-style.
	49
	50	To undo the change, you can use the `revert` API. This will remove any local overrides so that the canonical content
	51	(`[myextension]/ang/helloWorld.aff.html`) is activated.
	52
	53	```
	54	$ cv api4 afform.revert +w name=helloWorld
	55	```