Editron NPM | npm.io

Editron creates an html user interface with validation for your data, solely based on a json-schema, with almost no programming required. Then, use Editron with your own components and plugins to completely customize the user interface according to your needs.

editron is a JSON-Editor, which generates an user interface based on a JSON-Schema
editron will display the JSON-Schema's title, detailed descriptions, structure and live validation results in an HTML form
to improve usability, editron can be customized to display data in an appropriate way

a JSON-Schema is quick to write, readable and easy to extend
because it represents all types of JSON data structures, it can be the single interface for all forms
being JSON and thus serializable it can be distributed over http, stored in a database and read by any programming language
JSON-Schema is a standard and has a range of validators for many common languages

customizability
- via json-schema
- selection of what to render and where (specific properties, trees or lists within the data)
extensibility
- custom editor-widgets, framework agnostic
- custom validation methods (sync and async)
design
- performant
- follows simple concepts in interpreting the JSON-Schema to build an HTML form
features - supports collaborative editing, - live inline validation - complete json-schema draft04 spec - support for multiple languages - tested and used in production

requires programming skills for a custom editor-widget
currently no theming options: for layout adjustments either custom css or custom editor-widgets are required
not recommended for text-heavy applications like in docs or word
if you only need a login-form, this project might not be worth the Kb
complex data-types result in complex user-interfaces. could be solved through specific editor-widgets

Key Concepts

Before using editron, you should be familiar with some specifications, like JSON-Schema, JSON-Schema Validation and JSON-Pointer.

JSON-Schema is a declarative format for describing the structure of data and itself is stored as a JSON-file. A JSON-Schema may be used to describe the data you need and also describe the user-interface to create this data.

JSON-Schema Validation extends the JSON-Schema with validation rules for the input values. These rules are used to further evaluate the corresponding data and respond with errors, if the given rules are not met.

JSON-Pointer defines a string syntax for identifying a specific value within a JSON document and is supported by JSON-Schema. Given a JSON document, it behaves similar to a lodash path (a[0].b.c), which follows JS-syntax, but instead uses / separators, e.g. (a/0/b/c). In the end, you describe a path into the JSON data to a specific point.

Installation

npm install editron

Editron can be loaded through script tags in HMTL or bundled with your application. This README will refer to a bundled setup using import-statements. For a detailed setup using HTML-scripts or bundling, refer to docs/how-setup-editron.

Working With Editron

For a general understanding of a json-schema and editron editors refer to the introduction docs/json-schema-and-editron-editors.

For details about editron configuration and interaction refer to docs/howto-work-with-editron. What follows is a quick overview:

Create an instance of editron, passing your json-schema

import Editron from "editron";
const editron = new Editron(schema);

Then, pick a DOM-element and render a form for all your data

const editor = editron.createEditor("#", document.querySelector(".editron"));

finally, remove the view with

editron.destroyEditor(editor);

Interaction

Get the current data

const data = editron.getData();

change the data

editron.setData(data);

get the current validation errors

const errors = editron.getErrors();
const isValid = errors.length === 0;

and finally, remove editron

editron.destroy();

The complete editron-api is explained in docs/howto-work-with-editron

Configure Bundled Editors

Each instance of an editor supports a set of options, that can be added on a json-schema property, called editron:ui. For configuration options for all editors bundled with editron, refer to docs/doc-editor-options

Custom Input Validation

Validators are used to validate input-data for a JSON-Schema. E.g. a schema { type: "string", minLength: 1 } tests if the passed input is a string, another validator checks if the given minLength-rule passes. You can validate everything, even remote ressources, which are validated asynchronous. See how to write, add and setup validators in docs/howto-add-custom-validator.

Custom Editor

Default input-forms will not always be suited best for your data. For this reason, editron can be extended by or completly replaced with custom editors. In general, you create custom editors to

improve usability of input, collecting data in a more appropriate way, e.g. pointing to a map, instead of asking for x- and y-coordinates
improve usability of form, where you break the rendering flow, hiding details per default
preview data, e.g. show an image to an image-url input

With a custom editor you take complete control of rendering of and interaction with data. In addition, you may choose, which child-values are rendered with editron or should be taken care of in the custom-editor.

For a general overview how to set up editors, refer to docs/howto-work-with-editron. You can read about adding a custom value editor extending from AbstractValueEditor in docs/howto-write-value-editor or the complete editor-documentation in docs/docs-editron-editor.

Plugins

Editron does support plugins through a plugin-api that exposes lifecycle-hooks. This allows you to add data-based features and cross-editor features. You can refer to the plugin overview or read through howto write a plugin.

Further examples

Besides getting-started, the following examples can be found in the ./examples directory

see how to create multiple editors from one instance in examples/multiple-editors
see how to create multiple independent editron instances in examples/multiple-controller

Breaking Changes

03/2021 with v9 Controller has been renamed to Editron for consistency.

07/2020 with v8 editron is written using typescript. Due to module-syntax, some exports have changed, mainly:

accessing services has change to a method editron.service(serviceName)
Event system has mostly been replaced with a simple watch-method receiving all events
The EVENTS-object in services is now exported separately and not on its object import { EVENTS } from "./DataService
The main-module now exports all helpers separately and the controller is exported as default.
All components are exported individually, having no default in src/components/index.ts
dependency mitt has been replaced by nanoevents
test-runner ava has been replaced by mocha

Additionally all source files have been moved to src-folder, which must be adjusted in the imports

11/2019 with v7 editron has been updated to mithril@2, json-schema-library@4, mithril-material-forms@3. and all editors have new required method setActive(boolean) to enable or disabled editor input-interaction. Please refer to each library version for Breaking Changes. In short:

mithril-material-forms has a consistent api for forms. Any callbacks have changes to lowercase mithril-style e.g. onclick or onchange (button, checkbox, input are affected)
json-schema-library has undergone a major change in its api (schema is mostly optional)
mithril has dropped support for m.withAttrs