ext/afform/docs/crud.md

   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         "is_token": false,
  19         "server_route": "civicrm/hello-world",
  20         "layout": {
  21             "#tag": "div",
  22             "#children": [
  23                 "Hello {{routeParams.name}}"
  24             ]
  25         },
  26     }
  27 }
  28 ```
  29
  30 Additionally, you can also update the forms:
  31
  32 ```
  33 $ cv api4 afform.update +w name=helloWorld +v title="The Foo Bar Screen"
  34 {
  35     "0": {
  36         "name": "helloWorld",
  37         "title": "The Foo Bar Screen"
  38     }
  39 }
  40 ```
  41
  42 A few important things to note about this:
  43
  44 * The changes made through the API are only applied on this site.
  45 * Once you make a change with the CRUD API, there will be two copies of the form:
  46     * `[myextension]/ang/helloWorld.aff.html` is the default, canonical version.
  47     * `[civicrm.files]/ang/helloWorld.aff.html` is the local, custom version.
  48 * The `layout` field is stored as an Angular-style HTML document (`helloWorld.aff.html`), so you can edit it on disk like
  49   normal Angular code. However, when CRUD'ing the `layout` through the API, it is presented in JSON-style.
  50
  51 To undo the change, you can use the `revert` API.  This will remove any local overrides so that the canonical content
  52 (`[myextension]/ang/helloWorld.aff.html`) is activated.
  53
  54 ```
  55 $ cv api4 afform.revert +w name=helloWorld
  56 ```