https://github.com/plotdb/konfig

https://github.com/plotdb/konfig

Last synced: about 2 months ago
JSON representation

• Host: GitHub
• URL: https://github.com/plotdb/konfig
• Owner: plotdb
• Created: 2021-01-24T17:47:16.000Z (almost 4 years ago)
• Default Branch: master
• Last Pushed: 2024-04-11T17:40:14.000Z (9 months ago)
• Last Synced: 2024-04-12T23:44:50.115Z (9 months ago)
• Language: HTML
• Size: 4.92 MB
• Stars: 0
• Watchers: 2
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md

Awesome Lists containing this project

README

        
# @plotdb/konfig

Config editor.

## Usage

Following modules are needed:

    npm install --save @plotdb/konfig @plotdb/semver @plotdb/block @plotdb/rescope @plotdb/csscope @loadingio/debounce.js proxise @loadingio/ldquery ldview

include them:

    /* here we use `@zbryikt/template` syntax */

    +script({

      {name: "proxise"},

      {name: "@loadingio/debounce.js"},

      {name: "@loadingio/ldquery"},

      {name: "ldview"},

      {name: "@plotdb/semver"},

      {name: "@plotdb/rescope"},

      {name: "@plotdb/csscope"},

      {name: "@plotdb/block"},

      {name: "@plotdb/konfig"},

      {name: "@plotdb/konfig", path: "konfig.widget.bootstrap.min.js"}

    });

Then the initialization script:

    kfg = new konfig({...});

    kfg.on("change", function(cfg) { ... });

    kfg.init().then(function() { ... });

Constructor options:

 - `root`: root node or CSS selector for root node.

   - root node is used to place root tab for this config.

 - `useBundle`: true if use bundle blocks, if availale. default true.

 - `debounce`: true to debounce updating. default true.

 - `autotab`: true to use meta object field key as tab name by default. default false

 - `meta`: meta object. see spec for more information.

 - `tab`: tab object. see spec for more information.

 - `manager`: block manager for retrieving blocks

   - use default manager if omitted, which always throw an Error except for blocks available in bundle.

 - `typemap(name)`: converter from widget name to `@plotdb/block` definition. For widget customization.

   - `name`: a widget name, such as `number`, `color`, etc.

   - return value: should be an object for block definition such as `{name: 'number', version: '0.0.1'}`

 - `view`: view for rendering. optional, default null. For more information, see `Views` section below.

A common sample usage:

    kfg = new konfig({

      root: document.querySelector('.kfg'),

      useBundle: true /* bundle from konfig.widget.bootstrap.min.js */

      view: 'simple'

      meta: { sample: { type: 'number' } }

      view: 'simple'

    });

    kfg.on("change", function() { ... });

    kfg.init().then(function() {

    });

with this DOM:

    .kfg(ld-scope): div(ld-each="ctrl")

### API

 - `init()`: initialization.

    - return Promise, resolved initial config on initialized.

 - `render()`: re-render controls

 - `limited(opt)`: return if current config uses some limited values.

   - return value is based on `opt`, an object with a fields `detail`. when `detail` is:

     - omitted or `false`: return true or false, indicating if any value is limited.

     - `true`: return an object with `true` in corresponding field if that field uses a limited value.

 - `get()`: get value object.

 - `set(v, opt)`: set value object to `v`.

   - options: an option object with possibly following field:

     - `append`: default false. if true, only fields with value other than undefined will be update.

 - `obj()`: instead of a plain, serializable JSON, `obj()` return a Promise resolved with objects corresponding to operatable objects provided by widgets.

 - `default()`: get a config object with all values from default value.

 - `reset()`: reset config object to default value.

 - `meta(opt)`: update `meta` object. return Promise

   - parameters: either

     - the meta object

     - `{meta, tab}` object.

 - `tab()`: update `tab` object.

 - `interface(meta)`: return a Promise resolved with an interface for the widget defined by `meta`.

 - `on(event, cb(args...))`

 - `fire(event, args...)`

 - `ensureBuilt()`: in case that konfig is building interface and not yet ready, use `ensureBuilt` which return a Promise that resolves when konfig is ready.

## Class API

 - `merge(des, obj1, obj2, ...)`: recursively merge meta objs by order into `des`, and return `des`.

   - this is for merging meta objects.

 - `append(o1, o2, o3, ...)`: recursively append config object backward to o1. return merged object.

   - this is for merging config objects.

## Events

 - `change`: fired when value is changed. Params:

   - `value`: (serialized) value object return by `get`.

 - `action`: fired when widget fires this event.

   - this is for customized widgets to send user-defined events. `data` below is defined by user.

   - Params:

     - `src`: source widget that fires this event

     -`data`: data sent along with the original event by source widget.

## Sample Usage

    kfg = new konfig({

      root: document.body,

      meta: {

        showText: { type: 'boolean' },

        textSize: { type: 'number', range: false, min: 10, max: 64, step: 1 },

        textAlign: { type: 'choice', values: ["left", "right", "center"], default: 'left' },

        textColor: { type: 'color', tab: 'color' }

      }

    });

## Meta Specification

Check `doc/spec.md` for more information.

## Views

To 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.

`view` can be either a string, an object or a function. Following explains the details about the usage of corresponding types. 

### Builtin Views

`@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:

    new konfig({

      view: "simple"

    });

While `@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.

Additionally, you may want to scope your DOM if you are also using ldview for UI rendering:

    div(ld-scope): div(ld-each="ctrl")

#### simple

A simple list of controls. sample DOM:

    div(ld-each="ctrl")

#### default

Controls with tabs. sample DOM:

    div(ld-each="tab")

      div(ld="name")

      div(ld-each="ctrl")

#### recurse

Controls in recursive tabs. sample DOM:

    div(ld="template")

      div(ld="name")

      div(ld-each="ctrl")

      div(ld-each="tab")

DOM will be reused for recursive tabs so you have to specify a template roo node with `ld="template"`.

Note `ctrl` should be outside of `tab`.

### view as object

When `view` option is an object, it can be anything with following methods:

 - `render()`: called when `@plotdb/konfig` renders tabs and ctrls.

 - `ctx(opt)`: called when `meta` changes, with a parameter object `opt`, with following fields:

   - `root`: root element

   - `ctrls`: ctrl list

   - `tabs`: tab list

### view as function

When `view` option is a function, it should accept an parameter object with following fields:

 - `root`: konfig root element

 - `ctrls`: list of controls

 - `tabs`: list of tabs

Additionally, it should return an object with at least following method:

 - `render()`: this is called everytime when `konfig` needs to br re-rendered.

This function is called everytime a konfig rebuild is necessary ( e.g., when `meta` is updated ). You should implement singleton by yourself if needed.

## Action Loop

Widgets 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:

    rpc = proxise -> itf.fire \action, {name: \rpc, data: {...}}; return null

    new itf action: rpc: -> rpc.resolve it

    ...

    rpc!then -> ...

    

## License

MIT