From 95eb6fd51871577e5fb83756d84dd5b2e245e72a Mon Sep 17 00:00:00 2001
From: Tim Otten <totten@civicrm.org>
Date: Fri, 8 Feb 2019 16:13:41 -0500
Subject: [PATCH] Add docs/sandbox/planning-v0.2.md

---
 ext/afform/docs/sandbox/planning-v0.2.md | 166 +++++++++++++++++++++++
 1 file changed, 166 insertions(+)
 create mode 100644 ext/afform/docs/sandbox/planning-v0.2.md

diff --git a/ext/afform/docs/sandbox/planning-v0.2.md b/ext/afform/docs/sandbox/planning-v0.2.md
new file mode 100644
index 0000000000..7f7aa406bd
--- /dev/null
+++ b/ext/afform/docs/sandbox/planning-v0.2.md
@@ -0,0 +1,166 @@
+## Example Use Case
+
+A school has an application process which begins when a parent fills out a
+form with basic details about:
+
+* Themselves
+* Their spouse/coparent (if applicable)
+* The kid
+* A meeting request
+
+The data is saved to 4 entities:
+
+* "Parent" (or "You" or "Me")
+* "Spouse"
+* "Kid"
+* "Activity" (of type "Phone Call" assigned to a particular person)
+
+## General Metadata
+
+```php
+// The "library" is a definition of available tags/directives. It can be
+// used to validate form definitions; to advise sysadmins; and (probably)
+// to generate the $palette.
+//
+// Must NOT be required at runtime. Only required for administration.
+//
+// CONSIDER: Specifying non-conventional names for design/props variants
+$afformLibrary = [
+  'afl-entity' =>[
+    'attrs' => ['entity-name', 'matching-rule', 'assigned-values'],
+  ],
+  'afl-name' => [
+    'attrs' => ['contact-id', 'afl-label'],
+  ],
+  'afl-contact-email' => [
+    'attrs' => ['contact-id', 'afl-label'],
+  ],
+];
+
+// The "palette" is a list of things that can be selected by a web-based
+// admin and added to a form.
+//
+// The canonical form is flat-ish array, but it will be requested in 2-level indexed
+// format (e.g. `entity,id`).
+//
+// Must NOT be required at runtime. Only required for administration.
+$afformPalette = [
+  [
+    'id' => 'Parent:afl-name', /* string; should be stable but otherwise opaque to consumer */
+    'entity' => 'Parent',
+    'title' => 'Name',
+    'template' => '<afl-name contact-id="entities.parent.id" afl-label="Name"/>',
+  ],
+  [
+    'id' => 'Parent:afl-name',
+    'entity' => 'Parent',
+    'title' => 'Address',
+    'template' => '<afl-address contact-id="entities.parent.id" afl-label="Address"/>',
+  ],
+];
+```
+
+## Form Metadata: meta.json
+
+```json
+{
+  "server_route": "civicrm/hello-world",
+  "entities": {
+    "parent": {
+      "type": "Individual",
+      "set": {"favorite_color": "red"},
+      "matchingRule": "email_only"
+    }
+  }
+}
+```
+
+## Form Layout: layout.html
+
+```html
+<afl-form>
+  <crm-ui-tabset>
+
+    <crm-ui-tab>
+      <afl-entity name="parent">
+        <afl-name afl-label="Your Name" ng-required="true" name-style="First-Last" />
+        <afl-email afl-label="Your Email" ng-required="true" />
+      </afl-entity>
+    </crm-ui-tab>
+
+    <crm-ui-tab>
+      <afl-entity name="spouse">
+        <afl-name afl-label="Spouse Name" name-style="First-Last" />
+        <afl-email afl-label="Spouse Email" />
+      </afl-entity>
+    </crm-ui-tab>
+
+    <crm-ui-tab>
+      <afl-entity name="kid">
+        <afl-name afl-label="Kid Name" ng-required="true" name-style="First-Last" />
+      </afl-entity>      
+    </crm-ui-tab>
+  </crm-ui-tabset>
+
+  <button ng-click="save()">Save</button>
+</afl-form>
+```
+
+## Form Editor: Rendering the same layout
+
+```html
+<afl-form-af-design>
+  <crm-ui-tabset-af-design>
+    <crm-ui-tab-af-design>
+      
+    </crm-ui-tab-af-design>
+  </crm-ui-tabset-af-design>
+</afl-form-af-design>
+```
+
+## File Structure
+
+In v0.1, there was a convention of autoprefixing everything with `afform-`.
+This was generally tied to the goal of providing a strong symmetries in
+the names of folders/files/modules/directives/tags.
+
+In the long run, though, it doesn't seem sustainable force everything under
+the `afform-` prefix.
+
+* As we started spec'ing the standard library, it became clear that the
+  stdlib should have a diff namespace from the more business-oriented form defs.
+* As third parties start writing code, they're going to look for way to
+  make their own 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`)
+* The file name in the base-code provided by an extension should match
+  the file-name in the local override folder.
+
+The following file-structure preserves those parallels. It also:
+
+* Gives access to a full range of tag names
+* Is a bit easier with IDE file-opening (more unique file-names)
+* Is a bit harder to manually copy (e.g. `cp -r foo bar` => `mcp 'foo.*' 'bar.#1'`
+
+Which leads to this structure:
+
+```
+// A business-y form; in canonical definition and local override
+{ext:org.foobar}/ang/afform-edit-contact.aff.json
+{ext:org.foobar}/ang/afform-edit-contact.aff.html
+ {civicrm.files}/ang/afform-edit-contact.aff.json
+ {civicrm.files}/ang/afform-edit-contact.aff.html
+
+// An address block in the stdlib; in canonical definition and local override
+// Note: We also have the "design" and "props" variants
+{ext:org.foobar}/ang/afl-address.aff.json
+{ext:org.foobar}/ang/afl-address.aff.html
+{ext:org.foobar}/ang/afl-address.aff.props.html
+{ext:org.foobar}/ang/afl-address.aff.design.html
+ {civicrm.files}/ang/afl-address.aff.json
+ {civicrm.files}/ang/afl-address.aff.html
+```
+
-- 
2.25.1