@eafmm/core

Form Minimap

Usage no npm install needed!

<script type="module">
  import eafmmCore from 'https://cdn.skypack.dev/@eafmm/core';
</script>

README

Form Minimap

This library displays a minimap for an HTML form. It shows the location, value, and status message for each element in the form. It also tries to compute the overall form status based on the constituent element statuses.

Screenshot

The minimap is especially useful for long forms which may not fit in the viewport and require scrolling to see the whole form itself. Most pages would have only one minimap for the form, but multiple minimaps may be useful in a wizard, for example, one for each step of the wizard. This would allow users to see the values entered in previous steps. The ability to see off-screen form element values can be useful for context, as well as cutting and pasting.

The minimap can be set permanently visible in a panel DIV or popped up on mouse enter in a per-minimap DIV. The details for each form element can be shown in a permanently visible shared DIV or in a popup per minimap.

The minimap reflects the aspect ratio of the form. The height (or width if useWidthToScale is true) is sized to fit the dimension of the parent panel. For anchored minimaps, the appropriate constraint is set on the CSS selector 'fmm-popup'.

Anchored minimaps may be toggle zoomed by zoomFactor by clicking on the title bar. A popup minimap will hide itself when the mouse leaves the popup unless pinned down with the pushpin. Hint: when zooming back in, it may be advisable to pin the pushpin first since the mouse pointer may end up outside the popup upon resize and the popup may therefore hide itself.

When a form is destroyed, its corresponding minimap should be detached or destroyed. The Angular, React, and Vue components supplied with this library will detach the minimap when the component is destroyed. This will happen when the component tag is placed inside the form.

Please feel free to play around with the Angular, React, and Vue demos. Feedback is always welcome.

Limitations:

  • Only form elements with an ID or NAME attribute, which are not HIDDEN, are monitored.
  • Only bootstrap4, material-ui, and angular material handlers are supplied with the library, although it should be easy enough to use these as a starting point to write your own handler for other layout frameworks.
  • Complicated forms may not be supported, although css display changes are handled to some extent.
  • No automated testing yet.
  • No WCAG accessibility yet. It might even be better to hide the minimap and panel from screen readers since they duplicate information already in the form.

If you find this software useful, please feel free to Buy Me A Coffee

Thank you.


Getting Started

Installation

npm install --save @eafmm/core

Usage

  1. Create a minimap specifying either a parent DIV for an always-visible minimap, or an anchor DIV for a popup minimap.
  2. Destroy the minimap when its corresponding form is destroyed.

Example

import { Fmm, FmmMinimap } from '@eafmm/core';

const p: FmmMinimapCreateParam = {
   form: myForm,
   title: 'Important Info'
};
const minimap = Fmm.createMinimap(p, parentDiv);

...

minimap.destructor();

Usage Of Wizard Panel With Multiple Minimaps

  1. Create a panel for the wizard.
  2. Create a minimap using the panel for the form in each step of the wizard.
  3. Detach the minimap when a step is navigated away and its corresponding form is destroyed. The minimap will be shown greyed out so it can still be used for context and cut-and-paste.
  4. Destroy the panel when the wizard is no longer needed. All detached minimaps in this panel will be destroyed.

Example Wizard

import { Fmm, FmmMinimap, FmmPanel } from '@eafmm/core';

const panel = Fmm.createPanel(parentDiv, detailParentDiv);
const p1: FmmMinimapCreateParam = {
   form: myForm1,
   title: 'Step 1',
   usePanelDetail: true
};
const minimap1 = panel.createMinimap(p1);

...

minimap1.detach();
const p2: FmmMinimapCreateParam = {
   form: myForm2,
   title: 'Step 2',
   usePanelDetail: true
};
const minimap2 = panel.createMinimap(p2);

...

panel.destructor();

API

Fmm

Static Method Parameter/Returns Description
createMinimap ( Create a minimap.
  p: FmmMinimapCreateParam
  parent?: HTMLElement Parent for the minimap. If undefined, an anchor must be specified in the FmmMinimapCreateParam parameter.
  ef?: FmmElementFactory Advanced usage. Can be undefined for most cases.
  ): FmmMinimap
createPanel ( Create a panel to hold multiple minimaps.
  parent: HTMLElement Parent for the panel.
  detailParent?: HTMLElement Parent for the detail area. If undefined, details will be shown in a popup.
  vertical?: boolean Stack minimaps vertically in the panel.
  ef?: FmmElementFactory Advanced usage. Can be undefined for most cases.
  ): FmmPanel

FmmElementFactory

FmmForm

Constructor Parameter Type Description
form HTMLFormElement The form.
page HTMElement

FmmFramework

FmmMapString

FmmMinimap

Method Parameter/Returns Description
compose ( Sync the minimap with changes in form composition if elements were added or removed.
  customElementIds?: string[] List of non-standard form elements by ID or NAME attribute.
  ): void
destructor (): void Destroy this minimap and remove it from the DOM.
detach (): void Detach this minimap. Detached minimaps will be shown grayed out.
takeSnapshot (): boolean Sync the minimap with the values and statuses of form elements. Returns false if minimap was detached or destroyed.

FmmMinimapCreateParam

Property Type Default Description
aggregateLabels FmmMapString
anchor HTMLElement The element whose mouse enter event will show the minimap as a popup. If undefined, the minimap will be shown in the panel.
debounceMsec number 200 Delay for responding to form changes.
dynamicLabels string[] List of ID or NAME of form elements whose label may change after creation.
form FmmForm Required
framework FmmFramework
onUpdate FmmOnUpdate Callback when the minimap updates itself for whatever reason.
store FmmStore
title string Required Minimap title.
usePanelDetail boolean false Show details in panel instead of creating a popup per minimap.
useWidthToScale boolean false Use width rather than height to size the minimap, maintaining aspect ratio of the form (or page if specified).
verbosity number 0 Set to 1 to see processing times in console.
zoomFactor number Zoom factor of anchored minimap (capped at 5.0 times).

FmmOnUpdate

FmmPanel

Method Parameter/Returns Description
createMinimap ( Create a mininap in this panel.
  p: FmmMinimapCreateParam
  ): FmmMinimap
destroyDetached (): void Destroy all detached minimaps in this panel.
destructor (): void Destroy this panel and remove it from the DOM.

FmmStore

Constructs a store as a single source of truth (SSOT) for form values and errors. Without a store, the form elements will be monitored directly.