Informary

A browser forms data marshalling library that synchronizes HTML form data with JavaScript objects. Provides two-way binding via data-i-* attributes, transaction storage with localStorage, and undo/redo snapshot rings with field-level change detection.

Features

• Two-Way Marshalling - Reads form fields into nested JavaScript objects and populates forms from objects, using dot-notation data-i-datum attributes
• Transaction Storage - Persists form data in browser localStorage keyed by user, context, and GUID for offline use
• Undo/Redo Snapshots - Circular buffer snapshot rings with configurable depth (default 25 levels)
• Crash Recovery - Detects unsaved changes from prior sessions and offers detailed diff-based recovery scenarios
• Field-Level Deltas - Computes detailed diffs between current state and undo/redo buffers, including GUID-level element tracking
• Array Containers - Supports repeated form sections via data-i-container and data-i-index attributes
• Non-HTML State - Stores programmatic state that gets merged into the marshalled record object without requiring DOM elements
• Browser Compatible - Builds for modern browsers and legacy environments (including wkhtmltopdf)

Installation

npm install informary

Quick Start

<input type="text" data-i-form="MyForm" data-i-datum="Name.First" value="">
<input type="text" data-i-form="MyForm" data-i-datum="Name.Last" value="">

const Informary = require('informary');

let informary = new Informary({ Form: 'MyForm', jQuery: jQuery });

// Populate the form from a data object
informary.marshalDataToForm({ Name: { First: 'Steven', Last: 'Velozo' } }, () => {});

// Read the form back into an object
let record = {};
informary.marshalFormToData(record, () =>
{
    console.log(record.Name.First); // "Steven"
});

How It Works

Informary uses HTML data-i-* attributes to map form elements to paths in a JavaScript object tree. The data-i-form attribute identifies which form an element belongs to, and data-i-datum provides the dot-notation path into the data object.

Data Attributes

| Attribute | Required | Description | |-----------|----------|-------------| | data-i-form | Yes | Form identifier matching Settings.Form | | data-i-datum | Yes | Dot-notation path to the property (e.g. Header.Location.Station) | | data-i-container | No | Array container path for repeated sections | | data-i-index | No | Array index within the container | | data-i-guid | No | Unique identifier for tracking element additions/deletions |

Documentation

Full documentation is available in the docs folder:

• Getting Started
• API Reference
• Usage Lifecycle

Part of the Retold Framework

Informary is designed to work with other Pict packages for building form-driven applications:

• pict - UI framework
• pict-provider - Provider base class
• fable - Application services framework

Testing

Run the test suite:

npm test

Run with coverage:

npm run coverage

Building

Build for modern browsers:

npm run build

Build for legacy browser compatibility:

npm run build-compatible

Related Packages

• pict - MVC application framework
• cachetrax - Caching service
• fable - Application services framework

License

MIT

Contributing

Pull requests are welcome. For details on our code of conduct, contribution process, and testing requirements, see the Retold Contributing Guide.