From 304ead2486715a619ea89c5db884cb8bba79ced9 Mon Sep 17 00:00:00 2001 From: Tim Otten Date: Tue, 12 Jun 2018 23:40:50 -0700 Subject: [PATCH] README.md --- ext/afform/README.md | 38 +++++++++++++++++++++++++++----------- 1 file changed, 27 insertions(+), 11 deletions(-) diff --git a/ext/afform/README.md b/ext/afform/README.md index 2fb50ce597..67789e9b80 100644 --- a/ext/afform/README.md +++ b/ext/afform/README.md @@ -58,33 +58,45 @@ $ cv flush A few things to note: * We defined a route `civicrm/pretty-page`. This is defined in the same routing system used by CiviCRM forms. -* 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). +* The file `layout.html` is an AngularJS HTML document. It has access to all the general features of Angular HTML (discussed more later). * 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: +Now that we've created a form, we'll want to determine its URL. As with most +CiviCRM forms, the URL depends on the CMS configuration. Here is an example +from a local Drupal 7 site: ``` -$ cv url civicrm/pretty-page +$ cv url "civicrm/pretty-page" "http://dmaster.localhost/civicrm/pretty-page" -$ cv url civicrm/pretty-page/#/?name=world +$ 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. +Open the URLs and see what you get. -## Development: Scope variables and functions +## Development: Scopes, variables, and directives - oh my! -In AngularJS, every component has its own *scope* -- which defines a list of variables you can access. +In AngularJS, the primary language for orchestrating a screen is HTML. You can embed code in here. -By default, `afform` provides a few variables in the scope of every form: +One key concept *scope* -- the *scope* defines the list of variables which you can access. By default, `afform` +provides a few variables within 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. +* `meta`: The stored meta data (`meta.json`) for this form. * `ts`: This is a utility function which translates strings, as in `{{ts('Hello world')}}`. +Additionally, AngularJS allows *directives* -- these are extra HTML attributes and HTML tags. For example: + +* `ng-if` will conditionally create or destroy elements in the page. +* `ng-repeat` will loop through data. +* `ng-style` and `ng-class` will conditionally apply styling. + +A full explanation of these features is out-of-scope for this document, but the key point is that you can use standard +AngularJS features. + ## Development: Display a contact record Let's say we want `foobar` to become a basic "View Contact" page. A user @@ -94,11 +106,15 @@ would request a URL like: http://dmaster.localhost/civicrm/pretty-page/#/?cid=123 ``` -How do we use the `cid` to get information about the contact? Update `layout.html` to call APIv3: +How do we use the `cid` to get information about the contact? Update `layout.html` to include data from APIv33: ```html -
+
+
+

{{contact.display_name}}

Key Contact Fields

-- 2.25.1