{"id":16355941,"url":"https://github.com/timobechtel/settings-ui","last_synced_at":"2025-03-21T00:31:32.215Z","repository":{"id":38174570,"uuid":"250633556","full_name":"TimoBechtel/settings-ui","owner":"TimoBechtel","description":"Easily generate web forms with data binding using a JSON template","archived":false,"fork":false,"pushed_at":"2023-01-05T17:33:56.000Z","size":2569,"stargazers_count":3,"open_issues_count":17,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-17T19:13:26.070Z","etag":null,"topics":["forms","javascript","json","template","ui-components"],"latest_commit_sha":null,"homepage":"https://timobechtel.github.io/settings-ui/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TimoBechtel.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-03-27T19:55:57.000Z","updated_at":"2023-03-07T02:39:31.000Z","dependencies_parsed_at":"2023-02-04T08:45:17.329Z","dependency_job_id":null,"html_url":"https://github.com/TimoBechtel/settings-ui","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimoBechtel%2Fsettings-ui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimoBechtel%2Fsettings-ui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimoBechtel%2Fsettings-ui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimoBechtel%2Fsettings-ui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TimoBechtel","download_url":"https://codeload.github.com/TimoBechtel/settings-ui/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244717377,"owners_count":20498283,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["forms","javascript","json","template","ui-components"],"created_at":"2024-10-11T01:42:12.943Z","updated_at":"2025-03-21T00:31:31.860Z","avatar_url":"https://github.com/TimoBechtel.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Forks][forks-shield]][forks-url]\n[![Stargazers][stars-shield]][stars-url]\n[![Issues][issues-shield]][issues-url]\n[![MIT License][license-shield]][license-url]\n\n\u003c!-- PROJECT LOGO --\u003e\n\u003cbr /\u003e\n\u003cp align=\"center\"\u003e\n  \u003ch3 align=\"center\"\u003eSettings-UI\u003c/h3\u003e\n\n  \u003cp align=\"center\"\u003e\n    Easily generate web forms from a JSON template with data binding.\n    \u003cbr /\u003e\n    \u003cbr /\u003e\n    \u003ca href=\"https://timobechtel.github.io/settings-ui/\"\u003eView Demo\u003c/a\u003e\n    ·\n    \u003ca href=\"https://github.com/TimoBechtel/settings-ui/issues\"\u003eReport Bug\u003c/a\u003e\n    ·\n    \u003ca href=\"https://github.com/TimoBechtel/settings-ui/issues\"\u003eRequest Feature\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/p\u003e\n\n## Table of Contents\n\n- [About the Project](#about-the-project)\n- [Getting Started](#getting-started)\n  - [Installation](#installation)\n- [Usage](#usage)\n  - [API](#API)\n- [Plugins](#Plugins)\n- [Roadmap](#roadmap)\n- [Contributing](#contributing)\n- [License](#license)\n- [Contact](#contact)\n\n## About The Project\n\nThis 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.\nIt generates HTML UI components from a template JSON. You can easily extend it with your own components!\n\n## Getting Started\n\n### Installation\n\n#### NPM:\n\n```sh\nnpm install settings-ui\n```\n\n#### CDN:\n\n```html\n\u003cscript src=\"https://unpkg.com/settings-ui/dist/index.umd.js\"\u003e\u003c/script\u003e\n```\n\n### CSS\n\nSettings-UI comes with some basic styling. Not required, but you could install it like so:\n\n#### Using a bundler\n\n```javascript\nimport 'settings-ui/dist/index.css';\n```\n\n#### CDN\n\n```html\n\u003clink rel=\"stylesheet\" href=\"https://unpkg.com/settings-ui/dist/index.css\" /\u003e\n```\n\n## Usage\n\nImport it as module:\n\n```javascript\nimport SettingsUI from 'settings-ui';\n```\n\nThen use it like so:\n\n```javascript\n// template from which the ui is generated\nconst template = [\n  {\n    id: 'number',\n    type: 'number',\n  },\n  {\n    id: 'text',\n    type: 'text',\n  },\n  {\n    id: 'selection',\n    type: 'number',\n    values: [1, 2, 3],\n  },\n];\n\nconst ui = SettingsUI();\n// create ui and bind to a store object\nconst store = ui.bind(template);\n// render ui\nui.render().to(document.body);\n```\n\n### API\n\n#### `bind`: function\n\nCreates the ui from template and bind it's values to a store object. Returns a `store` object.\n\n##### Parameters\n\n| Name     |  Type  |                                                                                         Description |\n| -------- | :----: | --------------------------------------------------------------------------------------------------: |\n| template | array  |                                                       Your template from which the ui is generated. |\n| store    | object | _Optional_ Use a predefined object to store the inputted data. If not set, an empty one is created. |\n\n##### Example\n\n```javascript\nconst ui = SettingsUI();\nconst store = {};\nui.bind(template, store);\n```\n\n##### `store`: object\n\nObject that stores inputted data. Using the ids from template as keys.\n\n##### Might look like this\n\n```javascript\nconsole.log(store);\n\n/* OUTPUT:\n{\n  ballCount: 245,\n  number: 3,\n  section: {\n    title: 'someText',\n    speed: 23\n  },\n}\n*/\n\nconsole.log(store.section.speed); // =\u003e 23\n```\n\n##### `template`: array\n\nSchema, that describes the settings data. Used to generate the UI.\n\nEvery object in the array defines one property in the settings store object.\n\n##### Properties\n\n| Name               |   Type   |                                                                                                                                                                                                       Description |\n| ------------------ | :------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |\n| id                 |  string  |                                                                                                                                            **Required** Used as property names for the store and for ids in HTML. |\n| name               |  string  |                                                                                                                                                                        Short description. Used mainly for labels. |\n| help               |  string  |                                                                                                                                                                        Help text. Used for titles or placeholders |\n| 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. |\n| description        |  string  |                                                                                                                                                                            Currently not used by core components. |\n| name               |  string  |                                                                                                                                                                        Short description. Used mainly for labels. |\n| min                |  number  |                                                                                                                                           For number: lowest possible number, for text: minimal character length. |\n| max                |  number  |                                                                                                                                              For number: highest possible number, for text: max character length. |\n| steps              |  number  |                                                                                                                                                                            Available steps for inputting numbers. |\n| inputType          |  string  |                                                                                                                                                          Forces specific elements: `input`, `radio`, `selection`. |\n| defaultValue       |  string  |                                                                                                              Value that is used when no value has been set. E.g. when clearing an input field, this value is set. |\n| values             |  array   | Defines a set of possible values. Generates a HTML `\u003cselect\u003e` or `\u003cinput type=\"radio/\u003e\"` element. Each value can be a direct value or an object with a `name` and `value` property. e.g.`{name: 'one', value: 1}` |\n| options            |  array   |                                                                                                                                                           For `type = \"section\"`: Defines subtypes for a section. |\n| onUpdate(newValue) | function |                                                                                                                       Function that is called whenever the value changes. Called with the new value as parameter. |\n\n##### Example\n\nHave a look at the [example](https://github.com/TimoBechtel/settings-ui/blob/main/example/example.js) template file.\n\n#### `addChangeListener`: function\n\nAdds a listener that is called every time a value was updated.\n\n##### Parameters\n\n| Name     |   Type   |                                     Description |\n| -------- | :------: | ----------------------------------------------: |\n| listener | function | Is called with a `id` and `value` as parameter. |\n\n##### Example\n\n```javascript\nui.addChangeListener((key, value) =\u003e\n  console.log(`${key} was updated to ${value}`)\n);\n```\n\n#### `removeChangeListener`: function\n\nRemoves a change listener.\n\n##### Parameters\n\n| Name     |   Type   |                      Description |\n| -------- | :------: | -------------------------------: |\n| listener | function | Listener function to be removed. |\n\n#### `render`: function\n\nRenders the UI. Returns an object for method chaining with following methods:\n\n##### `to`: function\n\nRenders to a specific HTML element.\n\n###### Parameters\n\n| Name    |      Type      |                  Description |\n| ------- | :------------: | ---------------------------: |\n| element | HTMLDOMElement | Element to render the UI in. |\n\n##### Example\n\n```javascript\nui.render().to(document.getElementById('out'));\n```\n\n##### `replace`: function\n\nSimilar to `to(element)` but replaces the element with the generated UI.\n\n###### Parameters\n\n| Name    |      Type      |         Description |\n| ------- | :------------: | ------------------: |\n| element | HTMLDOMElement | Element to replace. |\n\n```javascript\nui.render().replace(document.getElementById('out'));\n```\n\n##### `get`: function\n\nReturns the generated element without appending it to the dom.\n\n##### Example\n\n```javascript\nui.render().get();\n```\n\n#### `update`: function\n\nUpdates HTMLElements with values from store.\n\n##### Parameters\n\n| Name |  Type  |                                                  Description |\n| ---- | :----: | -----------------------------------------------------------: |\n| id   | string | (optional) If defined, only updates specific element with id |\n\n## Plugins\n\nCurrently 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.\n\nPlugins can be registered when creating the SettingsUI Object:\n\n```javascript\nconst ui = SettingsUI({\n  plugins: [],\n});\n```\n\nA plugin is a simple function that can use following parameters:\n\n### Parameters\n\n| Name          |   Type   |                             Description |\n| ------------- | :------: | --------------------------------------: |\n| templateEntry |  object  | A single entry from the template array. |\n| update        | function |  A function that updates the form data. |\n\nIf the plugin function does not return anything (or `null`), the entry is skipped.\n\nOtherwise you can return an object that can have following properties:\n\n### Returns: Object\n\nwith\n\n#### Properties\n\n| Name          |   Type   |                                                                                 Description |\n| ------------- | :------: | ------------------------------------------------------------------------------------------: |\n| htmlElements  |  array   |                                                          Elements to render on the webpage. |\n| onStoreUpdate | function | Function that is called whenever the value in the store is updated. Receives the new value. |\n\n### Example\n\nThis is how you could handle a special message type with a clear button:\n\n```javascript\nconst plugins = [\n  ({ id, type, help, defaultValue }, update) =\u003e {\n    // only handle template entries with type = 'message'\n    if (type === 'message') {\n      const htmlElements = [];\n      const text = document.createElement('textarea');\n      text.id = id;\n      text.placeholder = help || defaultValue || '';\n      if (defaultValue || defaultValue === 0) text.value = defaultValue;\n\n      text.addEventListener('input', e =\u003e update(e.target.value));\n\n      const clear = document.createElement('button');\n      label.innerHTML = 'Clear';\n      label.addEventListener('click', () =\u003e {\n        text.value = '';\n        update('');\n      });\n\n      htmlElements.push(label);\n      htmlElements.push(text);\n      return { htmlElements };\n    }\n  },\n];\n\n// then register the plugin\nconst ui = SettingsUI({ plugins });\n```\n\n## Roadmap\n\n- [x] slider, radio, checkbox components\n- [ ] dynamic lists: add function for handling lists with variable length\n\n## Contributing\n\nContributions are **welcome**!\n\n1. Fork the Project\n2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your Changes (`git commit -m 'feat: Add some AmazingFeature'`)\n4. Push to the Branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n### Commit messages\n\nThis project uses semantic-release for automated release versions. So commits in this project follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0-beta.2/) guidelines. I recommend using [commitizen](https://github.com/commitizen/cz-cli) for automated commit messages.\n\n## License\n\nDistributed under the MIT License. See [LICENSE](https://github.com/TimoBechtel/settings-ui/blob/main/LICENSE) for more information.\n\n## Contact\n\nTimo Bechtel - [@TimoBechtel](https://twitter.com/TimoBechtel)\n\nProject Link: [https://github.com/TimoBechtel/settings-ui](https://github.com/TimoBechtel/settings-ui)\n\n\u003c!-- MARKDOWN LINKS \u0026 IMAGES --\u003e\n\u003c!-- https://www.markdownguide.org/basic-syntax/#reference-style-links --\u003e\n\n[forks-shield]: https://img.shields.io/github/forks/TimoBechtel/settings-ui?style=flat-square\n[forks-url]: https://github.com/TimoBechtel/settings-ui/network/members\n[stars-shield]: https://img.shields.io/github/stars/TimoBechtel/settings-ui?style=flat-square\n[stars-url]: https://github.com/TimoBechtel/settings-ui/stargazers\n[issues-shield]: https://img.shields.io/github/issues/TimoBechtel/settings-ui?style=flat-square\n[issues-url]: https://github.com/TimoBechtel/settings-ui/issues\n[license-shield]: https://img.shields.io/github/license/TimoBechtel/settings-ui?style=flat-square\n[license-url]: https://github.com/TimoBechtel/settings-ui/blob/main/LICENSE\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimobechtel%2Fsettings-ui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftimobechtel%2Fsettings-ui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimobechtel%2Fsettings-ui/lists"}