ext/afform/docs/quickstart.md

   1 # Quick Start: Creating the canonical definition of a basic form
   2
   3 As an extension author, you can define a form along with its default,
   4 canonical content. Simply create a file  `ang/MYFORM.aff.html`. In
   5 this example, we create a form named `helloWorld`:
   6
   7 ```
   8 $ cd /path/to/my/own/extension
   9 $ mkdir ang
  10 $ echo '<div>Hello {{routeParams.name}}</div>' > ang/helloWorld.aff.html
  11 $ echo '{"server_route": "civicrm/hello-world"}' > ang/helloWorld.aff.json
  12 $ cv flush
  13 ```
  14
  15 A few things to note:
  16
  17 * The `ang` folder is the typical location for AngularJS modules in CiviCRM extensions.
  18 * We defined a route `civicrm/hello-world`. This appears in the same routing system used by CiviCRM forms. It also supports properties such as `title` (page title) and `is_public` (defaults to `false`).
  19 * After creating a new form or file, we should flush the cache.
  20 * If you're going to actively edit/revise the content of the file, then you should navigate
  21   to **Administer > System Settings > Debugging** and disable asset caching.
  22 * The extension `*.aff.html` represents an AngularJS HTML document. It has access to all the general features of Angular HTML (discussed more later).
  23 * In AngularJS, there is a distinction between a "module" (unit-of-code to be shared; usually appears as `camelCase`) and a "directive" (a custom
  24   HTML element; may appear as `camelCase` or as `kebab-case` depending on context). Afform supports a [tactical simplification](angular.md) in which one
  25   `*.aff.html` corresponds to one eponymous module and one eponymous directive.
  26
  27 Now that we've created a form, we'll want to determine its URL. As with most
  28 CiviCRM forms, the URL depends on the CMS configuration. Here is an example
  29 from a local Drupal 7 site:
  30
  31 ```
  32 $ cv url "civicrm/hello-world"
  33 "http://dmaster.localhost/civicrm/hello-world"
  34 $ cv url "civicrm/hello-world/#/?name=world"
  35 "http://dmaster.localhost/civicrm/hello-world/#/?name=world"
  36 ```
  37
  38 Open the URLs and see what you get.