Registry PE Style Guide

This style guide is a living document for COmanage Registry 5.x. See also: Registry PE Coding Guide and the Registry 4.x Style Guide.

This document is a work-in-progress and will be released concurrently with COmanage Registry 5.0.0.

Background

This page is an overview of the front-end of COmanage Registry v5. It describes what libraries are available to the views by default and provides guides for how to customize forms, form fields, JavaScript, components, and themes.

Contents

Constraints and Assumptions

The COmanage UI/UX is guided by a number of important considerations that impact the choices of user interface elements, the tooling used to build them, the theme, layout, and fonts, and even client/server interactions which impact the user experience.

1. Accessible

   COmanage’s user interface is built to conform to WCAG 2.1 AA. Colors, UI features, and underlying markup are chosen and constrained with accessibility at the top of mind. A guiding principal we follow is that an accessible application provides a better user experience for all users. The application must be keyboard navigable, screen reader compatible, and color contrast aware.
   
   
2. Responsive
   Modern applications are expected to work equally well across all devices and screen sizes. COmanage employs a mobile-first design paradigm and works appropriately with touch-screen devices. COmanage 5.x aligns its responsive breakpoints with the Bootstrap 5.x framework and uses CSS flexbox, columns, and grid where appropriate. Dark-mode is also supported as a user/OS preference for its contribution to environmental stewardship.
   
   
3. Licenses & Libraries
   COmanage is licensed under the Apache 2.0 open source license, and all packages and software libraries used within its suite of applications must fall under a license on Apache's "Category A" list. Front-end libraries such as JavaScript frameworks and widgets are held to the same constraints. In practice, we primarily aim for Apache 2.0 and MIT licensing among all front-end tools. See our version dependencies for a listing of and licensing information about included packages.
   
   
4. Simplicity
   COmanage Registry v5 is focused on ease-of-use and ease-of-development. COmanage’s adopters have significantly different development resources. In an effort to lower the boundaries to plugin development or theme customization, the project keeps tooling requirements to a minimum. Driven by that aim, COmanage’s user interface code requires only a text editor to modify. Developers must understand the basics of PHP and, specifically, CakePHP. Beyond this, we adopt few and widely understood libraries, and we weigh the selection of these both by their ability to serve the project’s needs as well as the library’s stability and size of its user base. Development that requires separate, specialized tooling or a separate build / pre-processing step is generally avoided.

Front-End Libraries

The most important front-end libraries on which COmanage Registry v5.x depends are the following (see version dependencies for a complete list). These libraries are always available for use.

• Bootstrap - provides responsive breakpoints, dialog boxes, some animations, and utilities. Note that a proliferation of utility classes are generally (but not entirely) avoided to simplify CSS overrides in a Registry theme. Registry themes (when they become available in version 5) are delivered from the database and edited through the web UI.
  
  
• Vue.js - provides reusable JavaScript components. MVEA components, date and time pickers, some dashboard widgets, and other components are built using vue.
  
  
• jQuery - the venerable jQuery, though no longer required by the latest versions of Bootstrap, remains an important part of of the front-end ecosystem and is used along with native JavaScript. Note that jQuery UI is not included in Registry v5+.
  
  
• Material Icons - material icons are used for all iconography in Registry v5.

Custom Themes

Custom themes, supported in previous versions of Registry, will not be available in the very first release of Registry v5.0.0 but will be available in a subsequent release. We aspire to provide both the advanced interface for header, footer, and CSS overrides that was found in Registry version 4, along with enhancements allowing simple color changes and logo uploads through a theme's administrative panel.

Fonts & Icons

The font chosen for the COmange project is  Open Sans Regular (weight 400). The version in use is licensed under the Apache license version 2.0.

COmanage makes use of the Material Icons font library for all icons. Material Icons is licensed under the Apache license version 2.0. Both the solid ("material-icons") and outlined ("material-icons-outlined") versions are supported.

Colors

All colors are defined as CSS3 variables in the file [registry-source]/app/webroot/css/co-color.css.

Themers should be mindful that both light mode and dark mode colors are defined, and that the default is light mode. The simplest way of overriding Registry's colors is to override the default variables (which can be accomplished via theming when that feature become available in version 5). Dark mode colors can be changed independently if desired but will continue to work with appropriate color contrast ratios if left unmodified.

Interior background colors in COmanage are grey-scale in an effort to make Custom Theming simpler. Deployers should be able to add a logo and change the banner color without the need to significantly modify interior colors of the application.

All default colors comply with WCAG AA 2.0 contrast guidelines.

Text colors

• The color for general hyperlinks is #06c. This color passes accessibility contrast checking on white and gray backgrounds down to #e7e7e7.
• The standard body font color is #222 (dark gray).
• Color for headings (h1, h2, h3, etc) is #444.
• Please note: text colors should never be lighter than #666 on backgrounds from white down to #eee. On a #ddd background, text colors should not be lighter than #555. The ".text-muted" class may be used to lighten text on backgrounds down to #ddd.

Form Field Colors

• Input focus color: #ffd (light yellow)
• Input error and requirement markers (*): #c00 (red)

Primary Blue

The primary background color is white (#fff).

For all color definitions, see co-color.css.

Alerts

Registry makes use of standard Bootstrap alerts, using the COmanage color scheme:

To add an alert, include the following:

<?= $this->Alert->alert('your i18n text here', 'information'|'success'|'warning'|'error', true|false)  ?>

for example, 

<?= $this->Alert->alert(__d('information', 'ExternalIdentitySources.retrieve'), 'warning', false)  ?>

where the third parameter (true|false) determines whether the alert is dismissable.

Output for above example :

<div class="alert alert-warning co-alert" role="alert">
  <div class="alert-body d-flex align-items-center">
    <span class="alert-title d-flex align-items-center">
      <span class="material-icons-outlined alert-icon">report_problem</span>
    </span>
    <span class="alert-message">        
      This is the current record available directly from the source.
    </span>        
  </div>
</div>

Loading Animation

Full-page loading animation

The loading animation is CSS-only using the bare minimum CSS and HTML markup. It is designed to be delivered on-page during authentication without the need to reference external resources. By default, the loading animation runs when a form is submitted, when any item with a .spin class is clicked, or when any anchor tag lacking the .nospin class is clicked. When launched, the ever present #co-loading div that contains the CSS animation will be made visible. Because many buttons are on-page controls, the loading animation does not automatically launch for normal buttons.

To enable the loading animation on a button (or other element on click), add the "spin" CSS class to the button. To disable the loading animation on an anchor or other element where it loads by default, add the "no-spin" CSS class.

To launch or hide the loading animation programmatically, call displaySpinner(); or stopSpinner(); with JavaScript.

JavaScript

For Forms and Form Fields

Many Registry forms in both the core code and Plugins require JavaScript interactivity to modify a form's state (such as field visibility) based on changes users make to form elements. Registry provides the function jsLocalOnLoad() for initializing any on-page JavaScript and  jsLocalOnSubmit ( ) for handling any onSubmit JavaScript. By convention, most state changes to fields on a specific form are made in a function named updateGadgets(). Several convenience functions,  showFields() and hideFields(), are used for hiding and revealing form elements.

For example in app/templates/Types/fields.inc:

// If the jsLocalOnLoad() function is present, Registry will run it on page load.
function jsLocalOnLoad() {
  updateGadgets(true);

  // You can add other functions (or direct functionality) here,
  // and they will run on page load.
}

// Here we define the updateGadgets() function that responds to user activity.
// updateGadgets() accepts the boolean parameter "isPageLoad" - which should be 
// true on page load to establish default state without any animation.  
function updateGadgets(isPageLoad) {
  // What happens in here can be arbitrarily complex. This example is intentionally 
  // simple: we use the value of the "attribute" field to set the visibility of 
  // the "edupersonaffiliation" field.
  var attr = document.getElementById('attribute').value;

  // Handle page interaction; showFields() and hideFields() can take a list of ids.
  // Note that the initial state will be set without any animation if isPageLoad is true.
  if(attr == 'PersonRoles.affiliation_type') {
    showFields(['edupersonaffiliation'], isPageLoad);
  } else {
    hideFields(['edupersonaffiliation'], isPageLoad);
  }
}

Later, as a user interacts with form elements, updateGadgets() can be called again:

// The following field's 'onChange' parameter has been set to the updateGadgets() function
// which is called without a parameter. This allows the show/hide behavior to animate,
// helping the user see what's changing.
print $this->Field->control(
  fieldName: 'attribute', 
  options: [
    'onChange' => 'updateGadgets()', 
    'readonly' => $vv_action == 'edit'
  ]
);

Minor notes (to be included in the final document):

• Icons - when part of links or menus - should be placed to the left of the associated link text. The only exception to this is the user-menu toggle.