From: Tim Otten Date: Sat, 9 Feb 2019 05:11:58 +0000 (-0500) Subject: docs - Update to reflect new naming convention. General copy-editing. X-Git-Url: https://vcs.fsf.org/?a=commitdiff_plain;h=4f4b64873ba6ad357e06349723bcd2be95f282e6;p=civicrm-core.git docs - Update to reflect new naming convention. General copy-editing. --- diff --git a/ext/afform/docs/angular.md b/ext/afform/docs/angular.md index fc18a01b24..e23ba26cd9 100644 --- a/ext/afform/docs/angular.md +++ b/ext/afform/docs/angular.md @@ -5,13 +5,13 @@ your form. There is more to AngularJS -- such as client-side routing, controlle need these? Here are few tricks: * You can create your own applications and pages with full AngularJS. (See also: [CiviCRM Developer Guide: AngularJS: Quick Start](https://docs.civicrm.org/dev/en/latest/framework/angular/quickstart/)). - Then embed the afform (like `helloworld`) in your page with these steps: - * Declare a dependency on module (`afformHelloworld`). This is usually done in `ang/MYMODULE.ang.php` and/or `ang/MYMODULE.js`. - * In your HTML template, use the directive `
`. + Then embed the afform (like `hello-world`) in your page with these steps: + * Declare a dependency on module (`helloWorld`). This is usually done in `ang/MYMODULE.ang.php` and/or `ang/MYMODULE.js`. + * In your HTML template, use the directive `
`. * If you want to provide extra data, services, or actions for the form author -- then pass them along. * You can write your own directives with full AngularJS (e.g. `civix generate:angular-directive`). These directives become available for use in other afforms. * If you start out distributing an `afform` and later find it too limiting, then you can change your mind and convert it to static code in full AngularJS. - As long as you name it consistently (e.g. `afform-helloworld`), downstream consumers can use the static version as a drop-in replacement. + As long as you name it consistently (`angular.module('helloWorld').directive('helloWorld')`), downstream consumers can use the static version as a drop-in replacement. > *(FIXME: But if you do convert to static, could you still permit downstream folks customize the HTML? Let's > re-assess after we've patched core to allow full participation in the lifecycle of HTML partials.)* diff --git a/ext/afform/docs/crud.md b/ext/afform/docs/crud.md index e99174a4dd..47e54064e2 100644 --- a/ext/afform/docs/crud.md +++ b/ext/afform/docs/crud.md @@ -4,10 +4,10 @@ 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 +$ cv api4 afform.get +w name=helloWorld { "0": { - "name": "helloworld", + "name": "helloWorld", "requires": [ "afformCore" ], @@ -28,10 +28,10 @@ $ cv api4 afform.get +w name=helloworld Additionally, you can also update the forms: ``` -$ cv api4 afform.update +w name=helloworld +v title="The Foo Bar Screen" +$ cv api4 afform.update +w name=helloWorld +v title="The Foo Bar Screen" { "0": { - "name": "helloworld", + "name": "helloWorld", "title": "The Foo Bar Screen" } } @@ -41,7 +41,14 @@ 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]/afform/helloworld/` is the default, canonical version. - * `[civicrm.files]/afform/helloworld/` is the local, custom version. -* The `layout` field is stored as an Angular-style HTML document (`layout.html`), so you can edit it on disk like + * `[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 +``` diff --git a/ext/afform/docs/embed.md b/ext/afform/docs/embed.md index 4be406dfe9..e1ac30d5ca 100644 --- a/ext/afform/docs/embed.md +++ b/ext/afform/docs/embed.md @@ -1,23 +1,23 @@ # Embedding Forms: Afform as reusable building-block In the [quick-start example](quickstart.md), we registered a new route (`"server_route": "civicrm/hello-world"`) -- this created a -simple, standalone page with the sole purpose of displaying the `helloworld` form. What if we want to embed the form +simple, standalone page with the sole purpose of displaying the `helloWorld` form. What if we want to embed the form somewhere else -- e.g. as a dialog inside an event-listing or membership directory? Afforms are actually *re-usable sub-forms*. -How does this work? Every `afform` is an *AngularJS directive*. For example, `helloworld` can be embedded with: +How does this work? Every `afform` is an *AngularJS directive*. For example, `hello-world` can be embedded with: ```html -
+
``` -Moreover, you can pass options to `helloworld`: +Moreover, you can pass options to `helloWorld`: ```html -
+
``` -Now, in `afform/helloworld/layout.html`, you can use `options.phaseOfMoon`: +Now, in `ang/helloWorld.aff.html`, you can use `options.phaseOfMoon`: ```html Hello, {{routeParams.name}}. The moon is currently {{options.phaseOfMoon}}. @@ -29,11 +29,11 @@ Is this useful? Let's suppose you're building a contact record page. First, we should make a few building-blocks: -1. `afform/contactName/layout.html` displays a sub-form for editing first name, lastname, prefix, suffix, etc. -2. `afform/contactAddressess/layout.html` displays a sub-form for editing street addresses. -3. `afform/contactEmails/layout.html` displays a sub-form for editing email addresses. +1. `ang/afformContactName.aff.html` displays a sub-form for editing first name, lastname, prefix, suffix, etc. +2. `ang/afformContactAddresses.aff.html` displays a sub-form for editing street addresses. +3. `ang/afformContactEmails.aff.html` displays a sub-form for editing email addresses. -Next, we should create an overall `afform/contact/layout.html` which uses these building-blocks: +Next, we should create an overall `ang/afformContact.aff.html` which uses these building-blocks: ```html
@@ -49,7 +49,7 @@ Next, we should create an overall `afform/contact/layout.html` which uses these
``` -And we should create a `afform/contact/meta.json` looking like +And we should create a `ang/afformContact.aff.json` looking like ```json { @@ -57,8 +57,20 @@ And we should create a `afform/contact/meta.json` looking like "requires" : ["afformContactName", "afformContactEmails", "afformContactAddresses"] } ``` -> *(FIXME: In the parent form's `meta.json`, we need to manually add `afformContactName`, `afformContactAddresses`, `afformContactEmails` to the `requires` list. We should autodetect these instead.)* +> *(FIXME: In the parent form's `*.aff.json`, we need to manually add `afformContactName`, `afformContactAddresses`, `afformContactEmails` to the `requires` list. We should autodetect these instead.)* -What does this buy us? It means that a downstream admin (using APIs/GUIs) can fork `afform/contactName/layout.html` -- +We've created new files, so we'll need to flush the file-index + +``` +cv flush +``` + +and now we can open the page + +``` +cv open 'civicrm/contact?cid=100' +``` + +What does this buy us? It means that a downstream admin (using APIs/GUIs) can fork `ang/afformContactName.aff.html` -- but all the other components can cleanly track the canonical release. This significantly reduces the costs and risks of manging upgrades and changes. diff --git a/ext/afform/docs/quickstart.md b/ext/afform/docs/quickstart.md index d67ffc51fc..53000a16d6 100644 --- a/ext/afform/docs/quickstart.md +++ b/ext/afform/docs/quickstart.md @@ -1,24 +1,28 @@ # Quick Start: Creating the canonical definition of a basic form As an extension author, you can define a form along with its default, -canonical content. Simply create a folder named `afform/`. In -this example, we create a form named `helloworld`: +canonical content. Simply create a file `ang/MYFORM.aff.html`. In +this example, we create a form named `helloWorld`: ``` $ cd /path/to/my/own/extension -$ mkdir -p afform/helloworld -$ echo '{"server_route": "civicrm/hello-world"}' > afform/helloworld/meta.json -$ echo '
Hello {{routeParams.name}}
' > afform/helloworld/layout.html +$ mkdir ang +$ echo '
Hello {{routeParams.name}}
' > ang/helloWorld.aff.html +$ echo '{"server_route": "civicrm/hello-world"}' > ang/helloWorld.aff.json $ cv flush ``` A few things to note: -* We defined a route `civicrm/hello-world`. This is defined in the same routing system used by CiviCRM forms. It also supports properties such as `title` (page title) and `is_public` (defaults to `false`). -* The file `layout.html` is an AngularJS HTML document. It has access to all the general features of Angular HTML (discussed more later). +* The `ang` folder is the typical location for AngularJS modules in CiviCRM extensions. +* 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`). * 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. +* The extension `*.aff.html` represents an AngularJS HTML document. It has access to all the general features of Angular HTML (discussed more later). +* In AngularJS, there is a distinction between a "module" (unit-of-code to be shared; usually appears as `camelCase`) and a "directive" (a custom + HTML element; may appear as `camelCase` or as `kebab-case` depending on context). Afform supports a [tactical simplification](angular.md) in which one + `*.aff.html` corresponds to one eponymous module and one eponymous directive. 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 diff --git a/ext/afform/docs/roadmap.md b/ext/afform/docs/roadmap.md index 4e375694fa..3ef1bd771f 100644 --- a/ext/afform/docs/roadmap.md +++ b/ext/afform/docs/roadmap.md @@ -30,12 +30,11 @@ Within this extension, there are things which need updating/addressing: * We generally need to provide more services for managing/accessing data (e.g. `crm-api3`). * We need a formal way to enumerate the library of available tags/directives/attributes. This, in turn, will drive the drag-drop UI and any validation/auditing. -* Need to implement the `Afform.revert` API to undo local customizations. * Haven't decided if we should support a `client_route` property (i.e. defining a skeletal controller and route for any form). On the plus side, make it easier to add items to the `civicrm/a` base-page. On the flipside, we don't currently have - a strong use-case, and developers can get the same effect with `civix generate:angular-page` and embedding `
`. + a strong use-case, and developers can get the same effect with `civix generate:angular-page` and embedding `
`. * Injecting an afform onto an existing Civi page is currently as difficult as injecting any other AngularJS widget -- - which is to say that (a) it's fine a pure-Angular page and (b) it's lousy on a non-Angular page. + which is to say that (a) it's fine for a Civi-Angular page and (b) it's lousy on a non-Angular page. * The data-storage of user-edited forms supports primitive branching and no merging or rebasing. In an ideal world (OHUPA-4), we'd incorporate a merge or rebase mechanism (and provide the diff/export on web+cli). To reduce unnecessary merge-conflicts and allow structured UI for bona-fide merge-conflicts, the diff/merge should be based on HTML elements and diff --git a/ext/afform/docs/sandbox/planning-v0.2.md b/ext/afform/docs/sandbox/planning-v0.2.md index 7f7aa406bd..6f5a5f9812 100644 --- a/ext/afform/docs/sandbox/planning-v0.2.md +++ b/ext/afform/docs/sandbox/planning-v0.2.md @@ -60,7 +60,7 @@ $afformPalette = [ ]; ``` -## Form Metadata: meta.json +## Form Metadata: *.aff.json ```json { @@ -75,7 +75,7 @@ $afformPalette = [ } ``` -## Form Layout: layout.html +## Form Layout: *.aff.html ```html @@ -135,7 +135,7 @@ the `afform-` prefix. However, we still want to preserve the strong symmetries in the filesystem where: * The symbol in HTML (e.g. `afform-email`) should match the file-name (e.g. - `afform/Email/layout.html` or `afform-email.html`) + `afform/Email/layout.html` or `afform-email.aff.html`) * The file name in the base-code provided by an extension should match the file-name in the local override folder. diff --git a/ext/afform/docs/writing.md b/ext/afform/docs/writing.md index 3b398d2970..1df877d743 100644 --- a/ext/afform/docs/writing.md +++ b/ext/afform/docs/writing.md @@ -1,6 +1,6 @@ # Writing Forms: Afform as basic AngularJS templates -In AngularJS, the primary language for orchestrating a screen is HTML. You can do interesting things in Angular +In AngularJS, the primary language for composing a screen is HTML. You can do interesting things in Angular HTML, such as displaying variables and applying directives. One key concept is *scope* -- the *scope* determines the list of variables which you can access. By default, `afform` @@ -8,10 +8,10 @@ creates a scope with these variables: * `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. +* `meta`: The stored meta data (`*.aff.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 which create behavior. For example: +Additionally, AngularJS allows *directives* -- these are extensions to HTML (custom tags and attributes) which create behavior. For example: * `ng-if` will conditionally create or destroy elements in the page. * `ng-repeat` will loop through data. @@ -22,15 +22,15 @@ AngularJS markup. ## Example: Contact record -Let's say we want `helloworld` to become a basic "View Contact" page. A user +Let's say we want `civicrm/hello-world` to become a basic "View Contact" page. A user would request a URL like: ``` http://dmaster.localhost/civicrm/hello-world/#/?cid=123 ``` -How do we use the `cid` to get information about the contact? Update `layout.html` to fetch data with -`Contact.get` API and the [afform-api3](https://github.com/totten/afform/blob/master/ang/afformCore/Api3Ctrl.md) utility: +How do we use the `cid` to get information about the contact? Update `helloWorld.aff.html` to fetch data with +`Contact.get` API and call the [afform-api3](https://github.com/totten/afform/blob/master/ang/afformCore/Api3Ctrl.md) utility: ```html
@@ -58,6 +58,7 @@ How do we use the `cid` to get information about the contact? Update `layout.ht
``` -This example is useful pedagogically and may be useful in a crunch -- but in the longer term, -we should have a richer library of directives so that typical user-managed forms don't drill-down -at this level of detail. +This example is useful pedagogically and may be useful in a crunch -- but +for typical user-managed forms, it would be better to use more high-level +directives. You can create such directives by [embedding forms](embed.md) +or creating [conventional AngularJS directives](angular.md).