@eafmm/core v4.0.0

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.

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 and width are adjusted to fit the dimension of the parent panel. When creating anchored minimaps, the boolean-valued property useWidthToScale determines whether height or width is adjusted for aspect ratio, the other value being set in CSS using the selector .fmm-popup.

The size of popup minimaps may be toggle zoomed by zoomFactor by clicking on the popup's 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

Thank you.

Getting Started

Installation

npm install --save @eafmm/core

Example Popup Minimap

1. Create a popup minimap specifying an anchor DIV.
2. Destroy the minimap when its corresponding form is destroyed.

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

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

...

minimap.destructor();

Example Wizard Panel With Always-Visible Minimaps

1. Create a panel soecifying the number of wizard steps, i.e. the number of minimaps expected.
2. Use the panel to create a minimap 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.
5. A 'wizard' with only one step is a perfectly legitimate use case to show an always-visible minimap.

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

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

...

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

...

panel.destructor();

API

Fmm

| p: FmmMinimapCreateParam | 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. | minimapsCount: number | Number of child minimaps expected. | 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

FmmFramework

FmmMapString

FmmMinimap

| ): 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

FmmOnUpdate

FmmPanel

| 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.