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.
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
Thank you.
Getting Started
Installation
npm install --save @eafmm/core
Usage
- Create a minimap specifying either a parent DIV for an always-visible minimap, or an anchor DIV for a popup minimap.
- 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
- Create a panel for the wizard.
- Create a minimap using the panel for the form in each step of the wizard.
- 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.
- 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
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.