Skip to content

Instantly share code, notes, and snippets.

@totten

totten/notes.md

Last active February 16, 2021 14:27
Show Gist options
  • Save totten/a0bbccd3016242f060d5c906370ae473 to your computer and use it in GitHub Desktop.
Save totten/a0bbccd3016242f060d5c906370ae473 to your computer and use it in GitHub Desktop.
Download ZIP
An Opinionated Hierarchy of Unified Page Architectures (OHUPA)
Raw
notes.md

An Opinionated Hierarchy of Unified Page Architectures (OHUPA)

OHUPA is a classification scheme for page/form/layout/composition-systems. The main concern of OHUPA is how much your ecosystem relies on you to provide clear, stable, high-quality components.

Table of Contents

  • Context
  • Level 0: Non-Componentized
  • Level 1: Component-Oriented; Component-Library
  • Level 2: Developer Customization (e.g Hook, Selector)
  • Level 3: Admin Customization (e.g. GUI Editor)
  • Level 4: Multi-Master: Customization by multiple parties

Context

OHUPA is opinionated -- it assumes a number of goals/opinions about the software and the ecosystem around it. OHUPA classifications may be a useful discussion aide if you share these goals/opinions:

  1. Page Architecture: You want to write software which generates a page or screen with some layout -- that is, a mix of dashlets, tabs, accordions, fieldsets, fields, data-tables, charts, and so on.
  2. Unified Architecture: The list of components which make up a page should be defined according to a single, consistent standard -- because doing so will increase leverage or productivity. Documentation, training, testing, code, workflows, etc can be mixed in more ways and relied upon by more people.
  3. Ecosystem: Many stakeholders -- product managers, upstream software developers, downstream software developers, site administrators, and so on -- should be empowered to influence the page's composition. The stakeholders agree in broad terms about the scope/purpose/composition of most pages, but they occasionally have differences of opinion about specific elements, and the differences are important enough to require accommodation, and they are common enough that the costs for each customization (discovery, setup, maintenance, etc) is a significant issue.
  4. Incremental Delivery/Hierarchal Classification:The software cannot be written directly in its final form. Limitations or ambiguities (in technology, in skill, in wisdom, in timeline, in funding, etc) require shipping intermediate, compromise versions that only address some partial requirements. The software should evolve until satisfies the above goals.

These assumptions are not universal. For example:

In many applications, the page-architecture is a minor consideration. A computer game, Internet search engine, or proof-generator is a major software system -- but the page-layout is a fairly small part of the system. However, for software that deals with CMS, CRM, ERP, surveying, or reporting, the page-layout can be major focus area.

Many, many applications have small or closed teams -- if you are a solo developer or solo designer or solo product-owner, then you're probably not in the business of directly and broadly empowering multiple stakeholders. But if your application involves multiple organizations or an open/collaborative development process, then the ecosystem dynamics are a major consideration.

Many people do not need or want a single, consistent standard for elements in a page. If you only need two dropdowns to be user-configurable, then it's much easier to define two sui-generis codes specifically for those dropdowns -- and all the other dropdowns can be hardcoded by a developer. But if you're going to let users define multipage surveys, or if you're letting consultants define a dashboard of business charts, then maybe you need a unified architecture.

Some organizations may not require incremental development. They might enjoy a favorable balance of technology, skills, wisdom, timeline, budget, and/or requirements which allow them to comfortably and directly develop the final product. If you work for one, then kudos. Otherwise, you may need to ship a number intermediate releases which compromise on the vision.

For purposes of OHUPA, it can be hard to classify an application based on one technology. JSON might appear at level 0 or level 4. The differences between JSON, XML, HTML, and YAML have little affect. It only matters that the page/form-layouts are encoded in some consistent way. It doesn't matter if the components are implemented in Symfony Forms, Drupal Form API, AngularJS, or ReactJS. It only matters that they are implemented in a consistent way. The main concern of OHUPA is how much your ecosystem relies on you to provide clear, stable, high-quality components.

OHUPA Level 0: Non-Componentized

  • Description: The application does not define components. (Or it does define components, but they are framed in a way that would be unintelligble or useless to your audience.)
  • Strengths:
    • As a new developer, it's easier to write at Level 0 while also meeting precise requirements.
    • You don't need to make many broad ontological commitments.
  • Weaknesses:
    • Hard to read/learn/audit/imitate the code.
    • The only way to customize a UI is change the code in the original implementation.
  • Symptoms/Indicators that you are at Level 0
    • The logical, user-facing concepts such as "Tabs" or "Address Blocks" are not discrete components.
    • The only homegrown concept is the Page. The page has one controller and one HTML file, and they are both quite long.
  • Examples
    • A developer is likely to write Level 0 code if (a) writing their first application in an unfamiliar framework or (b) working under pressure to produce many features or satisfy tight timelines.

OHUPA Level 1: Component-Oriented; Component-Library

  • Description: The application is organized around components, but the infrastructure is addressed to an in-group/in-house audience.
  • Strengths:
    • Components have defined contracts and low coupling. They are amenable to testing in isolation.
    • Components are more browseable than Level 0.
    • Building new pages and rearranging existing pages is easier than Level 0.
  • Weaknesses:
    • You must explore the library of components to become effective.
    • The only way to customize a UI is change the code in the original implementation.
  • Symptoms/Indicators that you are doing Level 1 well
    • Provide documentation/examples of using each component.
    • Support common lifecycle stages like initialization, rendering, validation, on-change
    • Be cohesive. If a piece of HTML is closely linked to a piece of JS or CSS, then they should appear adjacent in the file-structure/IDE. (Ex: Matching files for .js, .html, .css. Possibly light inlining.)
    • Work with either (a) individual fields or (b) API data-records. Or, in other words, the data models should either be (a) very simple (single datum) or (b) named/documented/inspectable/tested.
    • Begin with a single, readable, meaningful, top-level document that describes the overall structure of the page.
    • Include components at multiple grains/layers, such as:
      • Layout (tabs, accordions, wizards, modals)
      • Assimilation (iframes, external forms, Drupal blocks)
      • Data tables
      • Common fieldsets (Address, Phone, CustomGroup, CustomGroups)
      • API fields
      • API I/O, metadata
    • Prefer using the coarsest-grained components that will fit.
  • Proposed Implementation Details for CiviCRM-Angular:
    • Iterate multiple times on the concepts/scoping/implementation of the components. Check that they make-sense and work in multiple use-cases.
    • (TODO) Lookup or discuss or regenerate notes on list of should-have components.
  • Examples
    • A developer who works with a major development framework (Rails, Symfony SE, Angular, Ember, etal), who is properly enculturated, and who's given a reasonable timeline should produce an application at OHUPA Level 1.

OHUPA Level 2: Developer Customization (e.g Hook, Selector)

  • Description: The code is already component-oriented. A third-party with developer skills can create a customization, such as adding a field or moving a block.
  • Strengths:
    • Organizations with technical capacity (volunteer/staff/contracted developers) can have diverse/tweaked/customized systems.
    • Because we've already satisfied Level 1, there are documents/examples/tests which improve onboarding and reduce risk.
    • You don't need to work as hard at idiot-proofing (compared to Level 2).
  • Weaknesses:
    • If you go to Level 2 without satisfying Level 1, your downstream is screwed because they can't rely on anything you give them.
    • Customization is still fairly expensive (time/money) because it still requires software-developer skillset.
  • Symptoms/Indicators that you are doing Level 2 well
    • Hooks/events allow developers to programmatically inspect/modify/rearrange existing components.
    • Selectors allow developers to perform batch operations on multiple components.
    • Downstream developers can create their own components with the same sophistication/concepts as upstream.
    • Naming-conventions provide a predictable way to store/browse any new or overriden components.
  • Examples
    • Drupal Form API with hook_alter resembles OHUPA level 2 (assuming the components are well-defined).
    • Client-side jQuery app with CSS selectors resembles OHUPA level 2 (assuming the components are well-defined).
  • Proposed Implementation Details for CiviCRM-Angular:
    • hook_civicrm_angularPartials(): Inspect/alter partials with phpQuery
    • (TODO) Identify JS-builder/aggregator hook

OHUPA Level 3: Admin Customization (e.g. GUI Editor)

  • Description: The code is already component-oriented. A third-party with administrator/site-builder/excel++ skills can create a customization, such as adding a field or moving a block.
  • Strengths:
    • Improves the reach -- more organizations/people can benefit from tweaking their systems.
    • Administrators can iterate on designs more quickly. There's not much cost to making a mistake.
  • Weaknesses:
    • If you go to Level 3 without satisfying Level 1, your downstream is screwed because they can't rely on anything you give them.
    • If you go to Level 3 without satisfying Level 2, then you missed an opportunity to test the quality of your model in more-forgiving circumstances. Sink or swim!
    • Administrators will have less space for customizations than developers. The GUI provided to administrators is reductive (compared to the native system).
  • Symptoms/Indicators that you are doing Level 3 well
    • You have a graphical editor which can load/display/save the definition of a component/page.
    • You allow an administrator to override a component/page, and you notify them about changes in the original/upstream version.
  • Examples
    • Drupal Views allow definition of data-table via code or GUI editor. However, they cannot mix multiple customizations from multiple stakeholders over time. (If you use a GUI editor, then the GUI overrides all else.)
  • Proposed Implementation Details for CiviCRM-Angular:
    • Define a new module org.civicrm.formeditor.
    • Implement a new screen for editing a component. (If the screen contains unrecognized/invalid markup, then )
    • Use hook_civicrm_angularPartials to apply the user's customizations
    • Provide an option for defining a route.

OHUPA Level 4: Multi-Master: Customization by multiple parties

  • Description: The code is already component-oriented. Multiple customizations (from multiple developers and administrators) are combined in a single page, with variations over time. Revisions and conflicts are identified and handled in a structured way.
  • Strengths:
  • Weaknesses:
  • Symptoms/Indicators that you are doing Level 3 well
  • Proposed Implementation Details for CiviCRM-Angular:
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment