Page-oriented site customization workflow

workflow.md

Concepts:

• Gum: A notation for diff'ing and merging HTML documents. (Normal line-oriented diffs are prone to gratuitious merge-conflicts when moving or reindenting code. Gum handles these changes explicitly, but it requires that every HTML node have a unique ID.)
• Page: A broad HTML document that describes the major elements of the screen. A page is an amalgamation that merges together preferences from multiple sources (e.g. the original/upstream page, the local configuration, the active extensions). (Civi Examples: "View Contact", "Event Registration", "Contribution Page", "New Mailing".)
• Component: A widget, input, or layout element that can be used within a page. Components look like special HTML tags or attributes. (Angular 1.x Directives, Angular 2.x Components, WebComponents, and Bootstrap CSS would all be examples.) (Civi Examples: "API Field", "Name block", "Billing block", "Emails block")
• Well-formed page: A page with an open-ended vocabulary of tags, attributes, classes.
• Strictly valid page: A page with a restricted vocabulary of tags, attributes, classes.
• Page schema: The whitelist of tags, attributes, classes which are acceptable on valid pages.

Rules:

• Administrators can define/edit pages locally -- using a GUI. However, this only works if the page is strictly valid.
• Developers can define/edit pages locally -- using HTML. (The HTML might edited with a local IDE or a browser-based TEXTAREA/Ace editor.)
• Developers can define/edit pages AND components by creating an extension. (This is only done through an IDE.)
• HTML pages are stored as files (sites/default/files/civicrm/html) so that it's easier to copy/sync between systems.
• Hooks may apply patches to a page.

Let's consider some perspectives / stories for different people. Alice is a site administrator (who doesn't know any HTML). Bob and Carol are web designers (with different degrees of programming/PHP/JS skills).

• Alice goes to the "View Contact" page. As an administrator, she sees a special "Edit Page" button, which opens up a GUI. She picks components from a predefined menu and drags/drops them. If she wants something more (not on the menu), then she'll have to find/download an extension or hire a developer.
  • This page is strictly-valid. If she upgrades civicrm-core or an extension, it may need to merge a patch into her page to ensure that it remains strictly-valid.
• Bob goes to the "View Contact" page. As an administrator, he sees a special "Edit Page" button. He wants to add display the "Notes" section differently, but there are no suitable options in the predefined menu. Since he knows a little HTML/JS, he switches to "HTML" mode, and he inserts some tags referencing APIv3 and ng-repeat.
  • The page is not strictly valid anymore. That's OK -- we're not trying to force-feed our abstractions to Bob. However, the GUI based editor will be disabled, and we may show some redflags/sign-posts.
  • Page-upgrades are not black/white. They are essentially diffs. Using gum for the diff improves the chances that we can apply it automatically, but if there's a genuine conflict, the upgrader will have to display an alert.
• Carol was once like Bob, but she's grown a bit more sophisticated. She prefers an IDE, knows Javascript and PHP better, and studied Angular more. She builds a new component progressively:
  • First, she edits sites/default/files/civicrm/html/view_contact.html with her IDE and uses APIv3+ng-repeat to display the notes. (Much like Bob).
  • Next, she creates an extension (civix generate:module). She defines a new component, <carol-notes-block cid="contact.id">, and moves her code from view_contact.html to carol_notes_block.html.
  • Now, Carol can install the extension on all her client sites. This improves re-use and mergeability (because there's less custom code in `view_conta however, the "View Contact" page is not strictly-valid; the page uses a custom component, so the GUI editor doesn't work.
  • Finally, if Carol wants to go all the way (distributing this publicly or merging it into core), she'll need to get the GUI editor to work. That means adding extra metadata and config UI for the editor.