{"id":19560088,"url":"https://github.com/plotdb/konfig","last_synced_at":"2026-05-06T14:02:57.043Z","repository":{"id":44094364,"uuid":"332515209","full_name":"plotdb/konfig","owner":"plotdb","description":null,"archived":false,"fork":false,"pushed_at":"2024-04-11T17:40:14.000Z","size":5164,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-04-12T23:44:50.115Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/plotdb.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2021-01-24T17:47:16.000Z","updated_at":"2024-04-15T06:48:42.564Z","dependencies_parsed_at":"2023-12-04T13:40:59.657Z","dependency_job_id":"dbb2080a-f62e-469a-83b8-f90a0f368cb9","html_url":"https://github.com/plotdb/konfig","commit_stats":{"total_commits":274,"total_committers":1,"mean_commits":274.0,"dds":0.0,"last_synced_commit":"3fa7386e51d320f0f4b585639a3a3bd79c9ea2c5"},"previous_names":[],"tags_count":121,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plotdb%2Fkonfig","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plotdb%2Fkonfig/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plotdb%2Fkonfig/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plotdb%2Fkonfig/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/plotdb","download_url":"https://codeload.github.com/plotdb/konfig/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240817175,"owners_count":19862435,"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":[],"created_at":"2024-11-11T05:05:53.874Z","updated_at":"2026-05-06T14:02:57.018Z","avatar_url":"https://github.com/plotdb.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @plotdb/konfig\n\nConfig editor.\n\n\n## Usage\n\nFollowing modules are needed:\n\n    npm install --save @plotdb/konfig @plotdb/semver @plotdb/block @plotdb/rescope @plotdb/csscope @loadingio/debounce.js proxise @loadingio/ldquery ldview\n\ninclude them:\n\n    /* here we use `@zbryikt/template` syntax */\n    +script({\n      {name: \"proxise\"},\n      {name: \"@loadingio/debounce.js\"},\n      {name: \"@loadingio/ldquery\"},\n      {name: \"ldview\"},\n      {name: \"@plotdb/semver\"},\n      {name: \"@plotdb/rescope\"},\n      {name: \"@plotdb/csscope\"},\n      {name: \"@plotdb/block\"},\n      {name: \"@plotdb/konfig\"},\n      {name: \"@plotdb/konfig\", path: \"konfig.widget.bootstrap.min.js\"}\n    });\n\nThen the initialization script:\n\n    kfg = new konfig({...});\n    kfg.on(\"change\", function(cfg) { ... });\n    kfg.init().then(function() { ... });\n\n\nConstructor options:\n\n - `root`: root node or CSS selector for root node.\n   - root node is used to place root tab for this config.\n - `useBundle`: true if use bundle blocks, if availale. default true.\n   - when true, this will create block classes from class object stored in `konfig.bundle`.\n     include `@plotdb/konfig:konfig.widget.bootstrap.min.js` will fill this field automatically with builtin widgets;\n   - (TBD) this is more like an option for debugging:\n     - It's only needed when we have to prepare `konfig.bundle` but want to kepp them out of block manager.\n     - Consider removing this in the future.\n - `debounce`: true to debounce updating. default true.\n - `autotab`: true to use meta object field key as tab name by default. default false\n - `meta`: meta object. see spec for more information.\n - `tab`: tab object. see spec for more information.\n - `manager`: block manager for retrieving blocks\n   - use default manager if omitted, which always throw an Error except for blocks available in bundle.\n - `typemap(name)`: converter from widget name to `@plotdb/block` definition.\n   - `name`: a widget name, such as `number`, `color`, etc.\n   - return value: should be an object for block definition such as `{name: 'number', version: '0.0.1'}`\n   - note:\n     - we usually use simple names in konfig meta, so `typemap` is necessary for converting names to bid.\n     - here is an example using typemap along with builtin widget bundle:\n\n           typemap: function(name) {\n             return {name: \"@plotdb/konfig\", version: \"main\", path: \"bootstrap/\" + name};\n           }\n\n       check `web/src/pug/blockdefault` and `web/src/pug/block/bootstrap` to see supported widgets in the bundle.\n - `view`: view for rendering. optional, default null. For more information, see `Views` section below.\n\n\nA common sample usage:\n\n    kfg = new konfig({\n      root: document.querySelector('.kfg'),\n      /* define how blocks are found baed on name */\n      typemap: function(name) {\n          return {name: \"@plotdb/konfig\", version: \"main\", path: \"bootstrap/\" + name};\n      },\n      view: 'simple',\n      meta: { sample: { type: 'number' } }\n    });\n    kfg.on(\"change\", function() { ... });\n    kfg.init().then(function() {\n    });\n\nwith this DOM:\n\n    .kfg(ld-scope): div(ld-each=\"ctrl\")\n\n\n### API\n\n - `init()`: initialization.\n    - return Promise, resolved initial config on initialized.\n - `render()`: re-render controls\n - `limited(opt)`: return if current config uses some limited values.\n   - return value is based on `opt`, an object with a fields `detail`. when `detail` is:\n     - omitted or `false`: return true or false, indicating if any value is limited.\n     - `true`: return an object with `true` in corresponding field if that field uses a limited value.\n - `get()`: get value object.\n - `set(v, opt)`: set value object to `v`.\n   - options: an option object with possibly following field:\n     - `append`: default false. if true, only fields with value other than undefined will be update.\n - `obj()`: instead of a plain, serializable JSON, `obj()` return a Promise resolved with objects corresponding to operatable objects provided by widgets.\n - `default()`: get a config object with all values from default value.\n - `reset()`: reset config object to default value.\n - `meta(opt)`: return `meta` object if `opt` is omitted. otherwise update `meta` object, return Promise.\n   - parameters: either\n     - the meta object\n     - `{meta, tab}` object.\n - `tab()`: update `tab` object.\n - `interface(meta)`: return a Promise resolved with an interface for the widget defined by `meta`.\n - `on(event, cb(args...))`\n - `fire(event, args...)`\n - `ensureBuilt()`: in case that konfig is building interface and not yet ready, use `ensureBuilt` which return a Promise that resolves when konfig is ready.\n\n\n## Class API\n\n - `merge(des, obj1, obj2, ...)`: recursively merge meta objs by order into `des`, and return `des`.\n   - this is for merging meta objects.\n - `append(o1, o2, o3, ...)`: recursively append config object backward to o1. return merged object.\n   - this is for merging config objects.\n\n\n## Events\n\n - `meta:building`: fired when meta is going to change.\n - `meta:built`: fired when meta is changed and built.\n - `change`: fired when value is changed. Params:\n   - `value`: (serialized) value object return by `get`.\n - `action`: fired when widget fires this event.\n   - this is for customized widgets to send user-defined events. `data` below is defined by user.\n   - Params:\n     - `src`: source widget that fires this event\n     -`data`: data sent along with the original event by source widget.\n\n\n## Sample Usage\n\n    kfg = new konfig({\n      root: document.body,\n      meta: {\n        showText: { type: 'boolean' },\n        textSize: { type: 'number', range: false, min: 10, max: 64, step: 1 },\n        textAlign: { type: 'choice', values: [\"left\", \"right\", \"center\"], default: 'left' },\n        textColor: { type: 'color', tab: 'color' }\n      }\n    });\n\n\n## Meta Specification\n\nCheck `doc/spec.md` for more information.\n\n\n## Views\n\nTo correctly render your configuration editor, you have to specify how it should be rendered. This can be done by setting the `view` option in constructor.\n\n`view` can be either a string, an object or a function. Following explains the details about the usage of corresponding types. \n\n\n### Builtin Views\n\n`@plotdb/konfig` uses `ldview` for widget rendering, and provide some builtin views which can be specified by their name, by setting `view` option to following strings along with the corresponding sample DOM for ldview, for example:\n\n    new konfig({\n      view: \"simple\"\n    });\n\nWhile `@plotdb/konfig` provides a set of default view dynamics, you still have to define the looks and feels of your views. Following are possible values of `view`, including `simple`, `default` and `recurse`, along with the corresponding sample DOMs.\n\nAdditionally, you may want to scope your DOM if you are also using ldview for UI rendering:\n\n    div(ld-scope): div(ld-each=\"ctrl\")\n\n\n#### simple\n\nA simple list of controls. sample DOM:\n\n    div(ld-each=\"ctrl\")\n\n\n#### default\n\nControls with tabs. sample DOM:\n\n    div(ld-each=\"tab\")\n      div(ld=\"name\")\n      div(ld-each=\"ctrl\")\n\n\n#### recurse\n\nControls in recursive tabs. sample DOM:\n\n    div(ld=\"template\")\n      div(ld=\"name\")\n      div(ld-each=\"ctrl\")\n      div(ld-each=\"tab\")\n\nDOM will be reused for recursive tabs so you have to specify a template roo node with `ld=\"template\"`.\n\nNote `ctrl` should be outside of `tab`.\n\n\n\n### view as object\n\nWhen `view` option is an object, it can be anything with following methods:\n\n - `render()`: called when `@plotdb/konfig` renders tabs and ctrls.\n - `ctx(opt)`: called when `meta` changes, with a parameter object `opt`, with following fields:\n   - `root`: root element\n   - `ctrls`: ctrl list\n   - `tabs`: tab list\n\nwhich can be implemented using ldView.\n\n\n### view as function\n\nWhen `view` option is a function, it should accept an parameter object with following fields:\n\n - `root`: konfig root element\n - `ctrls`: list of controls\n - `tabs`: list of tabs\n\nAdditionally, it should return an object with at least following method:\n\n - `render()`: this is called everytime when `konfig` needs to br re-rendered.\n\nThis function is called everytime a konfig rebuild is necessary ( e.g., when `meta` is updated ). You should implement singleton by yourself if needed.\n\n\n## Action Loop\n\nWidgets may need to communicate with its controller, but there is no direct access or interface of konfig to widgets. Two way communication is possible with action:\n\n    rpc = proxise -\u003e itf.fire \\action, {name: \\rpc, data: {...}}; return null\n    new itf action: rpc: -\u003e rpc.resolve it\n    ...\n    rpc!then -\u003e ...\n    \n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplotdb%2Fkonfig","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fplotdb%2Fkonfig","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplotdb%2Fkonfig/lists"}