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.

demo (coming soon) | working with editron | customize editron | api

• 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

Key Concepts

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

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