Easily generate web forms from a JSON template with data binding.
View Demo
·
Report Bug
·
Request Feature
This project was created to quickly scaffold a settings UI or similar web form and binding it's data to be used in your JavaScript app. It generates HTML UI components from a template JSON. You can easily extend it with your own components!
npm install settings-ui
<script src="https://unpkg.com/settings-ui/dist/index.umd.js"></script>
Settings-UI comes with some basic styling. Not required, but you could install it like so:
import 'settings-ui/dist/index.css';
<link rel="stylesheet" href="https://unpkg.com/settings-ui/dist/index.css" />
Import it as module:
import SettingsUI from 'settings-ui';
Then use it like so:
// template from which the ui is generated
const template = [
{
id: 'number',
type: 'number',
},
{
id: 'text',
type: 'text',
},
{
id: 'selection',
type: 'number',
values: [1, 2, 3],
},
];
const ui = SettingsUI();
// create ui and bind to a store object
const store = ui.bind(template);
// render ui
ui.render().to(document.body);
Creates the ui from template and bind it's values to a store object. Returns a store
object.
Name | Type | Description |
---|---|---|
template | array | Your template from which the ui is generated. |
store | object | Optional Use a predefined object to store the inputted data. If not set, an empty one is created. |
const ui = SettingsUI();
const store = {};
ui.bind(template, store);
Object that stores inputted data. Using the ids from template as keys.
console.log(store);
/* OUTPUT:
{
ballCount: 245,
number: 3,
section: {
title: 'someText',
speed: 23
},
}
*/
console.log(store.section.speed); // => 23
Schema, that describes the settings data. Used to generate the UI.
Every object in the array defines one property in the settings store object.
Name | Type | Description |
---|---|---|
id | string | Required Used as property names for the store and for ids in HTML. |
name | string | Short description. Used mainly for labels. |
help | string | Help text. Used for titles or placeholders |
type | string | Defines value type. Values can be number , text , boolean , section . Falls back to default HTML input types. These also define that type of element is generated. |
description | string | Currently not used by core components. |
name | string | Short description. Used mainly for labels. |
min | number | For number: lowest possible number, for text: minimal character length. |
max | number | For number: highest possible number, for text: max character length. |
steps | number | Available steps for inputting numbers. |
inputType | string | Forces specific elements: input , radio , selection . |
defaultValue | string | Value that is used when no value has been set. E.g. when clearing an input field, this value is set. |
values | array | Defines a set of possible values. Generates a HTML <select> or <input type="radio/>" element. Each value can be a direct value or an object with a name and value property. e.g.{name: 'one', value: 1} |
options | array | For type = "section" : Defines subtypes for a section. |
onUpdate(newValue) | function | Function that is called whenever the value changes. Called with the new value as parameter. |
Have a look at the example template file.
Adds a listener that is called every time a value was updated.
Name | Type | Description |
---|---|---|
listener | function | Is called with a id and value as parameter. |
ui.addChangeListener((key, value) =>
console.log(`${key} was updated to ${value}`)
);
Removes a change listener.
Name | Type | Description |
---|---|---|
listener | function | Listener function to be removed. |
Renders the UI. Returns an object for method chaining with following methods:
Renders to a specific HTML element.
Name | Type | Description |
---|---|---|
element | HTMLDOMElement | Element to render the UI in. |
ui.render().to(document.getElementById('out'));
Similar to to(element)
but replaces the element with the generated UI.
Name | Type | Description |
---|---|---|
element | HTMLDOMElement | Element to replace. |
ui.render().replace(document.getElementById('out'));
Returns the generated element without appending it to the dom.
ui.render().get();
Updates HTMLElements with values from store.
Name | Type | Description |
---|---|---|
id | string | (optional) If defined, only updates specific element with id |
Currently the Settings UI core can only handle a few basic types like input, selection, radio, checkbox, range and sections. You can however extend it to handle anything you throw at it.
Plugins can be registered when creating the SettingsUI Object:
const ui = SettingsUI({
plugins: [],
});
A plugin is a simple function that can use following parameters:
Name | Type | Description |
---|---|---|
templateEntry | object | A single entry from the template array. |
update | function | A function that updates the form data. |
If the plugin function does not return anything (or null
), the entry is skipped.
Otherwise you can return an object that can have following properties:
with
Name | Type | Description |
---|---|---|
htmlElements | array | Elements to render on the webpage. |
onStoreUpdate | function | Function that is called whenever the value in the store is updated. Receives the new value. |
This is how you could handle a special message type with a clear button:
const plugins = [
({ id, type, help, defaultValue }, update) => {
// only handle template entries with type = 'message'
if (type === 'message') {
const htmlElements = [];
const text = document.createElement('textarea');
text.id = id;
text.placeholder = help || defaultValue || '';
if (defaultValue || defaultValue === 0) text.value = defaultValue;
text.addEventListener('input', e => update(e.target.value));
const clear = document.createElement('button');
label.innerHTML = 'Clear';
label.addEventListener('click', () => {
text.value = '';
update('');
});
htmlElements.push(label);
htmlElements.push(text);
return { htmlElements };
}
},
];
// then register the plugin
const ui = SettingsUI({ plugins });
- slider, radio, checkbox components
- dynamic lists: add function for handling lists with variable length
Contributions are welcome!
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature
) - Commit your Changes (
git commit -m 'feat: Add some AmazingFeature'
) - Push to the Branch (
git push origin feature/AmazingFeature
) - Open a Pull Request
This project uses semantic-release for automated release versions. So commits in this project follow the Conventional Commits guidelines. I recommend using commitizen for automated commit messages.
Distributed under the MIT License. See LICENSE for more information.
Timo Bechtel - @TimoBechtel
Project Link: https://github.com/TimoBechtel/settings-ui