@appscode/ui-builder
v1.0.22
Published
## Motivation
Downloads
232
Readme
ui-builder
Install
npm i @appscode/ui-builder
Usage
For Nuxt, create a ui-builder.js
file inside your plugins
folder.
// plugins/ui-builder.js
import Vue from "vue";
import UiBuilder from "@appscode/ui-builder";
export default ({ store }) => {
// reason for using preserveState false https://vuex.vuejs.org/guide/modules.html#preserving-state
Vue.use(UiBuilder, { store, storeOptions: { preserveState: false } });
};
Vue.use
will register the component globally, so you can call this component from anythere in your Nuxt/Vue app. Notice, we also passed our store
object into the Vue.use
function. This will register a wizard
store module to your vuex store. You need to populate this module's state (ui
, schema
, model
and functions
objects) before you call this component. You can do this by calling the wizard
module's mutations
this.$store.commit("wizard/ui$set", uiJson);
this.$store.commit("wizard/schema$set", schemaJson);
this.$store.commit("wizard/model$init", modelJson);
this.$store.commit("wizard/functions$set", modelJson);
// initialize configureOptions array with the id of the steps that you wnat to be skipped
this.$store.commit("wizard/configureOptions$set", ["basic"]);
We will discuss more about these ui
, schema
, model
and functions
objects below.
Finally now, we can call our <ui-builder>
component -
<ui-builder
:show-options-step="showOptionsStep"
:on-options-valid="onOptionsValid"
:on-options-invalid="onOptionsInvalid"
:on-options-cancel="onOptionsCancel"
:on-valid="onValid"
:on-invalid="onInvalid"
:on-cancel="onCancel"
:on-deploy="onDeploy"
:chart-url="https://demo_url"
/>
showOptionsStep
- It denotes whether or not the wizard contains an options step. Iftrue
, two types of jsons should be provided, 1 for options and 1 for actual wizard, along with theonOptions
functions. Iffalse
or not provided, theonOptions
functions and options jsons are not required.onOptionsValid
- This function will be executed when user clicks the done button from the options step and the options wizard is in valid state.onOptionsInvalid
- It's executed in the final step, when the user clicks the done button from the options step and the options wizard is in invalid state.onOptionsCancel
- It will be executed when the user clicks the cancel button from the options step.onValid
- This function will be executed whenever preview step is shown (user clicks the final step done button) and the wizard is in valid state. The return value of this function will provide the preview step with the files to show. The return value of the function should be in the following format -[ { name: "file1", /*name of the file*/ content: "conent for file 1" /*content of the file*/ }, { name: "file2", /*name of the file*/ content: "conent for file 2" /*content of the file*/ }, ... ]
onInvalid
- It's executed in the final step, when the user clicks the done button and the wizard is in invalid state.onCancel
- It will be executed when the user clicks the cancel button from the wizard.onDeploy
- It will be execute when the user clicks on the deploy button from the preview step.chartUrl
- It denotes the default url for fetching reusable elements.
Motivation
Currently our charts include an openapi v3 schema. We are able to generate a HTML form from such a schema https://byte-builders-form.web.app/ .
But the ux of such an auto generated form is quite lacking compared to an hand written form. ui.json is a complementary json file format to any openapi_v3_schema.json to for schema driven form generation with no compromise on ux. Moreover, it can be used to generate UIs other than forms such as api driven list pages and details pages.
Observation
ui.json
will need to include 3 types of information in addition to the schema.
- Layout
- Data Loaders
- Conditional UI Elements
- Validations
ui.json
will be agnostic to any JS framework like Vue.js, React, etc.. Our implementation will be done for Vue.js.
Key objects
ui
-> The json describing the ui layout and html structureschema
-> The json describing the structure of the form. Follows OpenAPIV3 standards. Must not be emtpybaseModel
-> The initial values, can be empty.model
-> Output of the form after user interaction.keepEmptyModel
-> Flag Objects for model attributes. If corresponding model value of any ui elements is allowed to be empty, Then value of that path will be true in this object.asyncData
-> cache of data loaded vai http call (This is an optimization and can be skipped).functions
-> An object containing functions that can be referenced from ui.json to perform complex operations.language
- An object containg vue-i18n supported messages for localization of the wizard
These objects will be used to interpolate output, pre-fill fields and generate conditional UI elements and load data.
Modularity
UI Builder is fully moduler. You can divide the ui.json
along with it's associated language.json
and function.js
into several smaller modules and reference them inside your main ui.json
.
Read more about modularity from here
Object Description
ui
This descibes the ui and it's constituent elements. The whole UI of the application is redered by interpolating over this object. It should describe each and every UI element that should be present in the form or wizard.
Coniditional elements should also be described here as well as the conditions based on which they will be rendered.
Data fetching from API calls should also be described here. It should contain all relavent information associalted with making the API call.
There can be several different structures of this ui
schema, each responsible for generating different uis. One common property of this schema is the type
property. It indicates which type of ui this schema is ment to generate. The rest of the properties depend on this type
property.
The type
property
The type
property determines the type of ui component the ui.json
schema is describing. The types are -
multi-step-form
- also known as wizard.single-step-form
- also knows as simple form.array-input-form
- used for taking input array type elements.opject-input-form
- used for taking input object type (key value pairs) elements.input
- simple input boxtextarea
- simple textareaeditor
- editor similar to vscodeselect
- simple select boxcheckbox
- checkboxesradio
- radio elementsswitch
- switch/toggle elementstabs
- simple tabsanchor
- used for showing anchor type buttons for going to external or internal linksreusable-element
- used for reusing modules. Read more about modularity from here
The rest of the properties in ui.json
differs depending on the type
property.
The keepEmpty
property
The keepEmpty
property indicates the ui component's corresponding model value can be a empty value or not. Type of this attribute is boolean -
true
- The model value of this path can be empty. In corresposing path of schema for that component, will be set to true inkeepEmptyModel
.false
- The model value of this path can not be empty. Using this final model value's empty object can be trimmed.
The Multi Step Form
Example of ui.json
for mulit step form
{
"type": "multi-step-form",
"steps": [
{
"if": {
...
...
},
"title": "General Information",
"form": {
"type": "single-step-form",
.....
.....
}
},
{
"if": {
...
...
},
"title": "Topology",
"form": {
"type": "single-step-form",
.....
.....
}
},
........
........
]
}
From the example we see that the multi-step-form
has 2 more porperties in addition to the type
property. They are -
steps
- It is an array type property describing all the steps of the multi step form. Each step of a multistep form contains a single step form. It contains two properties -if
[OPTIONAL] - contains the description of the condition upon which the rendering of the form depends on. If the condition returnstrue
, the form is rendered otherwise it is hidded from view. For more details [click here](#Theif
property)title
- The of the step.form
- Aui.json
of typesingle-step-form
/multi-step-form
.
Every step of a
multi-step-form
must be asingle-step-form
or amulti-step-form
. Themulti-step-form
inside thesteps
array will be automatically nested in the UI.
The Single Step Form
Example of ui.json
for single step form
{
"type": "single-step-form",
"label": "demo form",
"show_label": true,
"discriminator": {
....
....
},
"if": {
....
....
},
"elements": [
{
"type": "select",
....
....
},
....
....
],
"style": {
"paddingLeft": "20px"
}
}
The properties are described below -
label
[OPTIONAL] - denotes the label for the form. It is optional, if not provided no labels will be shown for the form.show_label
[OPTIONAL] - specifies if we want to show the label of the form in the ui or not. It defaults tofalse
, that means by defaultlabel
is not shown. But when specied astrue
thelabel
will be shown in the ui.discriminator
[OPTIONAL] - contains the schema of the variables which are not inmodel
object or inside ourstore
object invue
. These variables are needed when the rendering of the form elements depends on values that are neither inmodel
object nor instore
object.if
[OPTIONAL] - contains the description of the condition upon which the rendering of the form depends on. If the condition returnstrue
, the form is rendered otherwise it is hidded from view. For more details [click here](#Theif
property)elements
- It is an array containing the list of all the elements within the form. Each item contains theui.json
of a simple form element. They can be -input
typetextarea
typeeditor
typeselect
typeanchor
typecheckbox
typeradio
typeswitch
typearray-input-form
typeobject-input-form
typesingle-step-form
typetabs
type
note: Multi step form can not be an element of Single step form.
style
[OPTIONAL] - contains a style object that can be used to bind inline styles to the single step form element.
The List Input Form
List input form is a form element that is used to take list of string as input from users. The example of ui.json
for list input form:
{
"type": "list-input-form",
"label": {
"text": "Demo list input form"
},
"if": {
...
...
},
"fetch": {
....
....
},
"element": {
"type": "input",
...
...
},
"schema": {
"$ref": "schema#/properties/..."
},
"disabled": true,
"individualItemDisabilityCheck": "demoChecker"
}
The properties are described below -
label
- The label property describes the label element for the list input form.if
[OPTIONAL] - contains the description of the condition upon which the rendering of the list input form element depends on. If the condition returnstrue
, the form element is rendered otherwise it is hidded from view.fetch
[OPTIONAL] - contains the description of the API that is needed to be called to fill the input field with data.element
- contains theui.json
for a single list element. A single list element can be -input
type
schema
- contains the JSON Schema or the reference to the schema for the array type variable that is being modified by the array input form element.$ref
- contains the JSON reference string pointing to the JSON schema.
disabled
[OPTIONAL] - If not specified, it isfalse
by default. If specified and set totrue
, the list input form is disabled and can not be modified. If specified and set to a string value then it specifies the function name declared in function.js to set this value usingfunctions.js
.individualItemDisabilityCheck
[OPTIONAL] - Specifies the function name declared in function.js. This function takes individual list items asitemCtx
inside the context object and returns a Boolean value. Iftrue
the individual list items will not be modifiable otherwise items will be be modifiable. DEFAULTS TOfalse
.itemCtx
for this will contain the string value of a particular item in list input form.
The Key Value Input Form
key value input form is a form element that is used to take the key value elements of an object from users. The example ui.json
is given below -
{
"type": "key-value-input-form",
"label": {
"text": "Demo key value input form"
},
"isArray": true,
"if": {
...
...
},
"fetch": {
....
....
},
"keys": {
"label": {
"text": "Demo key"
}
},
"values": {
"type": "input",
...
...
},
"schema": {
"$ref": "schema#/properties/..."
},
"disabled": true,
"individualItemDisabilityCheck": "demoChecker",
"newItemValidator": "demoValidator",
}
label
- The label property describes the label element for the key value input form.isArray
[OPTIONAL] - If not specified, it isfalse
by default. If specified and set totrue
, the key value input field can be multiple.if
[OPTIONAL] - contains the description of the condition upon which the rendering of the key value input form element depends on. If the condition returnstrue
, the form element is rendered otherwise it is hidden from view.fetch
[OPTIONAL] - contains the description of the API that is needed to be called to fill the key, value input fields of the key value input form with data.keys
- contains thelabel
of the input field for the keys of the object. Thislabel
property is an object that is similar to label of key value input form.values
- contains theui.json
for a key value. A single value can be -input
type
schema
- contains the JSON Schema or the reference to the schema for the object type variable that is being modified by the key value input form element.$ref
- contains the JSON reference string pointing to the JSON schema.
disabled
[OPTIONAL] - If not specified, it isfalse
by default. If specified and set totrue
, the key value input form is disabled and can not be modified. If specified and set to a string value then it specifies the function name declared in function.js to set this value usingfunctions.js
.individualItemDisabilityCheck
[OPTIONAL] - Specifies the function name declared in function.js. This function takes individual key value items asitemCtx
inside the context object and returns a Boolean value. Iftrue
the individual key value items will not be modifiable otherwise key value items will be be modifiable. DEFAULTS TOfalse
.itemCtx
for this will contain an object like -{ key: "demo_key", value: "Demo Value" }
for a particular item in key value input form.
newItemValidator
[OPTIONAL] - Specifies the function name declared in function.js. This function takes individual key value items asitemCtx
inside the context object which is candidate item for adding and returns an object. If the individual key value items is valid it returning empty object is okay. Otherwise it returns a object like -{ isInvalid: true, message: "demo message to show" }
itemCtx
for this will contain an object like -{ key: "demo_key", value: "Demo Value" }
for a particular item in key value input form.
The Key TextArea Input Form
key text area input form is a form element that is used to take the key value elements of an object from users where value input field will be an textarea field. The example ui.json
is given below -
{
"type": "key-text-area-input-form",
"label": {
"text": "Demo key area input form"
},
"isArray": true,
"if": {
...
...
},
"fetch": {
....
....
},
"keys": {
"label": {
"text": "Demo key"
}
},
"values": {
"type": "input",
...
...
},
"schema": {
"$ref": "schema#/properties/..."
},
"disabled": true,
"individualItemDisabilityCheck": "demoChecker",
"newItemValidator": "demoValidator",
}
label
- The label property describes the label element for the key text area input form.isArray
[OPTIONAL] - If not specified, it isfalse
by default. If specified and set totrue
, the key value input field can be multiple.if
[OPTIONAL] - contains the description of the condition upon which the rendering of the key value input form element depends on. If the condition returnstrue
, the form element is rendered otherwise it is hidden from view.fetch
[OPTIONAL] - contains the description of the API that is needed to be called to fill the key, value input fields of the key value input form with data.keys
- contains thelabel
of the input field for the keys of the object. Thislabel
property is an object that is similar to label of key text area input form.values
- contains theui.json
for a key value. A single value can be -input
type
schema
- contains the JSON Schema or the reference to the schema for the object type variable that is being modified by the key text area input form element.$ref
- contains the JSON reference string pointing to the JSON schema.
disabled
[OPTIONAL] - If not specified, it isfalse
by default. If specified and set totrue
, the key value input form is disabled and can not be modified. If specified and set to a string value then it specifies the function name declared in function.js to set this value usingfunctions.js
.individualItemDisabilityCheck
[OPTIONAL] - Specifies the function name declared in function.js. This function takes individual key value items asitemCtx
inside the context object and returns a Boolean value. Iftrue
the individual key value items will not be modifiable otherwise key value items will be be modifiable. DEFAULTS TOfalse
.itemCtx
for this will contain an object like -{ key: "demo_key", value: "Demo Value" }
for a particular item in key value input form.
The "Input" Form Element
The "Input" form element is a type of form element which is used to take a simple string, number or date as input. An example of ui.json
for a input form element is given below -
{
"type": "input",
"label": {
"text": "Demo input form element"
},
"if": {
....
....
},
"fetch": {
....
....
},
"schema": {
"$ref": "schema#/properties/..."
},
"disabled": true,
"hideValue: true
}
The properties are described below -
label
- The label property describes the label element for the simple input form.if
[OPTIONAL] - contains the description of the condition upon which the rendering of the input form element depends on. If the condition returnstrue
, the form element is rendered otherwise it is hidded from view.fetch
[OPTIONAL] - contains the description of the API that is needed to be called to fill the input field with data.schema
- contains the JSON Schema or the reference to the schema for the string / number / date type variable that is being modified by the input form element.$ref
- contains the JSON reference string pointing to the JSON schema.
disabled
[OPTIONAL] - If not specified, it isfalse
by default. If specified and set totrue
, the input field is disabled and can not be modified. If specified and set to a string value then it specifies the function name declared in function.js to set this value usingfunctions.js
.hideValue
[OPTIONAL] - If not specified, it isfalse
by default. If specified and set totrue
, the value of input field will be password type.
The "Textarea" Form Element
The "Textarea" form element is similer to the "Input" form element. It is useful when the string inside the input field is multilined.An example of ui.json
for a textarea form element is given below -
{
"type": "textarea",
"label": {
"text": "Demo textarea form element"
},
"if": {
....
....
},
"fetch": {
....
....
},
"schema": {
"$ref": "schema#/properties/..."
},
"disabled": true
}
The properties are described below -
label
- The label property describes the label element for the textarea input form.if
[OPTIONAL] - contains the description of the condition upon which the rendering of the textarea form element depends on. If the condition returnstrue
, the form element is rendered otherwise it is hidded from view.fetch
[OPTIONAL] - contains the description of the API that is needed to be called to fill the textarea with data.schema
- contains the JSON Schema or the reference to the schema for the string / number / date type variable that is being modified by the textarea form element.$ref
- contains the JSON reference string pointing to the JSON schema.
disabled
[OPTIONAL] - If not specified, it isfalse
by default. If specified and set totrue
, the textarea field is disabled and can not be modified. If specified and set to a string value then it specifies the function name declared in function.js to set this value usingfunctions.js
.
The "Editor" Form Element
The "Editor" form element renders a code editor similar to VS Code. It is useful when the content needed to be edited is a code file.An example of ui.json
for a editor form element is given below -
{
"type": "editor",
"label": {
"text": "Demo editor form element"
},
"language": "json",
"if": {
....
....
},
"fetch": {
....
....
},
"schema": {
"$ref": "schema#/properties/..."
},
"disabled": true
}
The properties are described below -
label
- The label property describes the label element for the editor input form.language
- The programming language of the content. Currently onlytext
,json
andyaml
languages are supported.if
[OPTIONAL] - contains the description of the condition upon which the rendering of the editor form element depends on. If the condition returnstrue
, the form element is rendered otherwise it is hidded from view.fetch
[OPTIONAL] - contains the description of the API that is needed to be called to fill the editor with data.schema
- contains the JSON Schema or the reference to the schema for the string type variable that is being modified by the editor form element.$ref
- contains the JSON reference string pointing to the JSON schema.
disabled
[OPTIONAL] - If not specified, it isfalse
by default. If specified and set totrue
, the editor field is readonly and can not be modified. If specified and set to a string value then it specifies the function name declared in function.js to set this value usingfunctions.js
.
The "Select" Form Element
The "Select" form element is a type of form element which is used to select one option from a number of provided options. An example fo the ui.json
is given below -
{
"type": "select",
"label": {
"text": "Department"
},
"if": {
....
....
},
"fetch": {
....
....
},
"options": [
{
"value": "cse",
"text": "Department of Computer Science & Engineering"
},
{
"value": "ict",
"text": "Department of Information & Communication Technology"
}
],
"add_new_button": {
"label": "Add new item",
"url": {
"params": {
"name": {
"$ref": "model#/name"
}
},
"path": "/${name}"
},
"target": "_blank"
},
"schema": {
"$ref": "schema#/properties/..."
},
"disabled": false,
"individualItemDisabilityCheck": "demoChecker",
"allowUserDefinedOption": true,
}
The properties are described below -
label
- The label property describes the label element for the select form element.if
[OPTIONAL] - contains the description of the condition upon which the rendering of the select form element depends on. If the condition returnstrue
, the form element is rendered otherwise it is hidded from view.fetch
[OPTIONAL] - contains the description of the API that is needed to be called to fetch the options for the select form. Only required if the options are not provided directly hereoptions
- contains an array of object or string representing the selectable options. One of which is selected using the select element. If contains object, then each option element has 2 properties -value
- The value attribute for the option element. It is the value that will be saved in themodel
object if the user selects the option.text
- The actual text that will represent the option to the user in the UI.
otherwise, each element will be array of strings refering value and text to display both.
add_new_button
[OPTIONAL] - This property is used if you want to add a "Add New" button to the select options. This select option acts as a anchor element and clicking it will take the user to a specified url is the current tab or new tab. All of this is configurable. It has 3 properties :label
- The label of the option. This is text that is displayed inside the option button.target
- The target attribute specifies where to open the link. Read more from [here](HTML DOM Anchor target Propertyurl
- This property describes the url that is thehref
of the anchor select element. It has the following properties -params
- describes the name and json reference of the variables that are used in thepath
property as placeholders. All the variables that are used in thepath
property must be declared here first. The json reference for the varaibles can be from themodel
object, thediscriminator
of the wrapping single input form or theVuex Store
object.path
- It is a string denoting a javascript template literal . The placeholders inside the literal must declared in theparams
property. The actual path is calculated by replacing the placeholders with their actual value.path
property is evaluated to get ourhref
for the anchor select element.
schema
- contains the JSON Schema or the reference to the schema for the string / number type variable that is being modified by the select form element.$ref
- contains the JSON reference string pointing to the JSON schema.
disabled
[OPTIONAL] - If not specified, it isfalse
by default. If specified and set totrue
, the select field is disabled and can not be modified. If specified and set to a string value then it specifies the function name declared in function.js to set this value usingfunctions.js
.individualItemDisabilityCheck
[OPTIONAL] - Specifies the function name declared in function.js. This function takes individual key value items asitemCtx
inside the context object and returns a Boolean value. Iftrue
the individual options in the select box will not be selectable otherwise options in the select form element will be be selectable. DEFAULTS TOfalse
.itemCtx
for this will contain an object like -{ text: "demo text", value: "demo_value" }
for a particular option in the Select form element.
allowUserDefinedOption
[OPTIONAL] - If not specified, it isfalse
by default. If specified and set totrue
, user can add new element to the option list.
The "Multiselect" Form Element
The "Multiselect" form element is a type of form element which is used to select one or multiple option from a number of provided options. An example fo the ui.json
is given below -
{
"type": "multiselect",
"label": {
"text": "Department"
},
"if": {
....
....
},
"fetch": {
....
....
},
"options": [
{
"value": "cse",
"text": "Department of Computer Science & Engineering"
},
{
"value": "ict",
"text": "Department of Information & Communication Technology"
}
],
"add_new_button": {
"label": "Add new item",
"url": {
"params": {
"name": {
"$ref": "model#/name"
}
},
"path": "/${name}"
},
"target": "_blank"
},
"schema": {
"$ref": "schema#/properties/..."
},
"disabled": false,
"individualItemDisabilityCheck": "demoChecker",
"allowUserDefinedOption": true,
}
The properties are described below -
label
- The label property describes the label element for the multiselect form element.if
[OPTIONAL] - contains the description of the condition upon which the rendering of the multiselect form element depends on. If the condition returnstrue
, the form element is rendered otherwise it is hidded from view.fetch
[OPTIONAL] - contains the description of the API that is needed to be called to fetch the options for the multiselect form. Only required if the options are not provided directly hereoptions
- contains an array of object or string representing the selectable options. If contains object, then each option element has 2 properties -value
- The value attribute for the option element. It is the value that will be saved in themodel
object if the user selects the option.text
- The actual text that will represent the option to the user in the UI.
otherwise, each element will be array of strings refering value and text to display both.
add_new_button
[OPTIONAL] - This property is used if you want to add a "Add New" button to the select options. This select option acts as a anchor element and clicking it will take the user to a specified url is the current tab or new tab. All of this is configurable. It has 3 properties :label
- The label of the option. This is text that is displayed inside the option button.target
- The target attribute specifies where to open the link. Read more from [here](HTML DOM Anchor target Propertyurl
- This property describes the url that is thehref
of the anchor select element. It has the following properties -params
- describes the name and json reference of the variables that are used in thepath
property as placeholders. All the variables that are used in thepath
property must be declared here first. The json reference for the varaibles can be from themodel
object, thediscriminator
of the wrapping single input form or theVuex Store
object.path
- It is a string denoting a javascript template literal . The placeholders inside the literal must declared in theparams
property. The actual path is calculated by replacing the placeholders with their actual value.path
property is evaluated to get ourhref
for the anchor select element.
schema
- contains the JSON Schema or the reference to the schema for the string / number type variable that is being modified by the select form element.$ref
- contains the JSON reference string pointing to the JSON schema.
disabled
[OPTIONAL] - If not specified, it isfalse
by default. If specified and set totrue
, the select field is disabled and can not be modified. If specified and set to a string value then it specifies the function name declared in function.js to set this value usingfunctions.js
.individualItemDisabilityCheck
[OPTIONAL] - Specifies the function name declared in function.js. This function takes individual key value items asitemCtx
inside the context object and returns a Boolean value. Iftrue
the individual options in the select box will not be selectable otherwise options in the multiselect form element will be be selectable. DEFAULTS TOfalse
.itemCtx
for this will contain an object like -{ text: "demo text", value: "demo_value" }
for a particular option in the Multiselect form element.
allowUserDefinedOption
[OPTIONAL] - If not specified, it isfalse
by default. If specified and set totrue
, user can add new element to the option list.
The "Configure Options" Form Element
The "Configure Options" form element is a type of form element which is used to render special checkbox field where users can check their needed configuration items. An example of the ui.json
is given below -
{
"type": "configure-options",
"label": {
"text": "Demo configure options"
},
"hasDescription": true,
"hasDependencies": true,
"if": {
....
....
},
"fetch": {
....
....
},
"owner": {
"$ref": "store#/user/username"
},
"cluster": {
"$ref": "store#/clusterInfo/name"
},
"options": [
{
"value": "demo1",
"text": "Demo 1",
"description": "Description of demo 1",
"dependencies": [{
"name": "demo Dependency",
"url": "demo_url"
}],
"disabled": true
},
{
"value": "demo2",
"text": "Demo 2",
"description": "Description of demo 2"
}
],
"schema": {
"$ref": "schema#/properties/..."
},
"disabled": true,
}
The properties are described below -
label
- The label property describes the label element for the configure options input form.owner
- It can bestring
orobject
type value. Ifstring
theowner
's value will be directly set. Otherwise, it describes the json reference of the variables that are used to setowner
value.$ref
- contains the JSON reference string. The json reference for the varaibles can be from themodel
object, therouter
object of the current route or thestore
asVuex Store
object.
cluster
- It can bestring
orobject
type value. Ifstring
thecluster
's value will be directly set. Otherwise, it describes the json reference of the variables that are used to setcluster
value.$ref
- contains the JSON reference string. The json reference for the varaibles can be from themodel
object, therouter
object of the current route or thestore
asVuex Store
object.
hasDescription
[OPTIONAL] - It indicates whether or not the options of the checkbox items contain any kind of description. It is by defaultfalse
. If set totrue
, the options of the checkbox must contain thedescription
property.hasDependency
[OPTIONAL] - It indicates whether or not the options of the checkbox items may contain any kind of dependencies. It is by defaultfalse
. If set totrue
, the options of the checkbox may contain thedependencies
property.if
[OPTIONAL] - contains the description of the condition upon which the rendering of the checkbox form element depends on. If the condition returnstrue
, the form element is rendered otherwise it is hidden from view.fetch
[OPTIONAL] - contains the description of the API that is needed to be called to fetch the options for the checkbox form element. Only required if the options are not provided directly hereoptions
- contains an array of object representing the selectable options. Each option element has 2 properties -value
- The value attribute for the option element. It is the value that will be saved in themodel
object if the user selects the option.text
- The actual text that will represent the option to the user in the UI.description
[OPTIONAL] - This contains some description about the option. It's optional, if thehasDescription
property is set totrue
this descrption will be shown.dependencies
[OPTIONAL] - contains an array of dependencies objects each describing a dependency element. Each dependencies object has 2 properties -name
- Name of the dependencyurl
- URL link for the dependency
disabled
[OPTIONAL] - This indicates the particular option is disabled or not. If not specified, it isfalse
by default.
schema
- contains the JSON Schema or the reference to the schema for the string / number type variable that is being modified by the configuration options form element.$ref
- contains the JSON reference string pointing to the JSON schema.
disabled
[OPTIONAL] - If not specified, it isfalse
by default. If specified and set totrue
, the checkbox field is disabled and can not be modified. If specified and set to a string value then it specifies the function name declared in function.js to set this value usingfunctions.js
.individualItemDisabilityCheck
[OPTIONAL] - Specifies the function name declared in function.js. This function takes individual configure option items asitemCtx
inside the context object and returns a Boolean value. Iftrue
the individual list items will not be modifiable otherwise items will be be modifiable. DEFAULTS TOfalse
.itemCtx
for this will contain the object value of a particular item in Configure Options Form.
The "Checkbox" Form Element
The "Checkbox" form element is a type of form element which is used to render checkboxes. Users one can check one or more items. An example fo the ui.json
is given below -
{
"type": "checkbox",
"label": {
"text": "Demo checkbox"
},
"hasDescription": true,
"if": {
....
....
},
"fetch": {
....
....
},
"options": [
{
"value": "demo1",
"text": "Demo 1",
"description": "Description of demo 1"
},
{
"value": "demo2",
"text": "Demo 2",
"description": "Description of demo 2"
}
],
"schema": {
"$ref": "schema#/properties/..."
},
"disabled": true,
"individualItemDisabilityCheck": "demoChecker"
}
The properties are described below -
label
- The label property describes the label element for the checkbox form element.hasDescription
[OPTIONAL] - It indicates whether or not the options of the checkbox items contain any kind of description. It is by defaultfalse
. If set totrue
, the options of the checkbox must contain thedescription
property.if
[OPTIONAL] - contains the description of the condition upon which the rendering of the checkbox form element depends on. If the condition returnstrue
, the form element is rendered otherwise it is hidded from view.fetch
[OPTIONAL] - contains the description of the API that is needed to be called to fetch the options for the checkbox form element. Only required if the options are not provided directly hereoptions
- contains an array of object representing the selectable options. Each option element has 2 properties -value
- The value attribute for the option element. It is the value that will be saved in themodel
object if the user selects the option.text
- The actual text that will represent the option to the user in the UI.description
[OPTIONAL] - This contains some description about the option. It's optional, if thehasDescription
property is set totrue
this descrption will be shown.
schema
- contains the JSON Schema or the reference to the schema for the string / number type variable that is being modified by the checkbox form element.$ref
- contains the JSON reference string pointing to the JSON schema.
disabled
[OPTIONAL] - If not specified, it isfalse
by default. If specified and set totrue
, the checkbox field is disabled and can not be modified. If specified and set to a string value then it specifies the function name declared in function.js to set this value usingfunctions.js
.individualItemDisabilityCheck
[OPTIONAL] - Specifies the function name declared in function.js. This function takes individual key value items asitemCtx
inside the context object and returns a Boolean value. Iftrue
the individual options in the checkbox will not be clickable otherwise options in the checkbox will be be clickable. DEFAULTS TOfalse
.itemCtx
for this will contain an object like -{ text: "demo text", value: "demo_value" }
for a particular option in the Checkbox.
The "Radio" Form Element
The "Radio" form element is a type of form element which is used to render radio elements. Users can pick only one item. An example fo the ui.json
is given below -
{
"type": "radio",
"label": {
"text": "Demo radio"
},
"if": {
....
....
},
"fetch": {
....
....
},
"options": [
{
"value": "demo1",
"text": "Demo 1"
},
{
"value": "demo2",
"text": "Demo 2"
}
],
"schema": {
"$ref": "schema#/properties/..."
},
"disabled": true,
"individualItemDisabilityCheck": "demoChecker"
}
The properties are described below -
label
- The label property describes the label element for the radio input form element.hasDescription
[OPTIONAL] - It indicates whether or not the options of the radio items contain any kind of description. It is by defaultfalse
. If set totrue
, the options of the radio must contain thedescription
property.if
[OPTIONAL] - contains the description of the condition upon which the rendering of the radio form element depends on. If the condition returnstrue
, the form element is rendered otherwise it is hidded from view.fetch
[OPTIONAL] - contains the description of the API that is needed to be called to fetch the options for the radio form element. Only required if the options are not provided directly hereoptions
- contains an array of object representing the selectable options. Each option element has 2 properties -value
- The value attribute for the option element. It is the value that will be saved in themodel
object if the user selects the option.text
- The actual text that will represent the option to the user in the UI.description
[OPTIONAL] - This contains some description about the option. It's optional, if thehasDescription
property is set totrue
this descrption will be shown.
schema
- contains the JSON Schema or the reference to the schema for the string / number type variable that is being modified by the radio form element.$ref
- contains the JSON reference string pointing to the JSON schema.
disabled
[OPTIONAL] - If not specified, it isfalse
by default. If specified and set totrue
, the radio field is disabled and can not be modified. If specified and set to a string value then it specifies the function name declared in function.js to set this value usingfunctions.js
.individualItemDisabilityCheck
[OPTIONAL] - Specifies the function name declared in function.js. This function takes individual key value items asitemCtx
inside the context object and returns a Boolean value. Iftrue
the individual options in the radio will not be clickable otherwise options in the radio will be be clickable. DEFAULTS TOfalse
.itemCtx
for this will contain an object like -{ text: "demo text", value: "demo_value" }
for a particular option in the Radio.
The "Switch" Form Element
The "Switch" form element is a type of form element which is used to take a simple boolean (true
/false
) as input. An example of ui.json
for a switch form element is given below -
{
"type": "switch",
"label": {
"text": "Demo switch"
},
"if": {
....
....
},
"fetch": {
....
....
},
"schema": {
"$ref": "schema#/properties/..."
},
"disabled": true
}
The properties are described below -
label
- The label property describes the label element for the switch form element.if
[OPTIONAL] - contains the description of the condition upon which the rendering of the switch form element depends on. If the condition returnstrue
, the form element is rendered otherwise it is hidded from view.fetch
[OPTIONAL] - contains the description of the API that is needed to be called to set or reset the switch.schema
- contains the JSON Schema or the reference to the schema for the boolean variable that is being modified by the switch form element.$ref
- contains the JSON reference string pointing to the JSON schema.
disabled
[OPTIONAL] - If not specified, it isfalse
by default. If specified and set totrue
, the switch field is disabled and can not be modified. If specified and set to a string value then it specifies the function name declared in function.js to set this value usingfunctions.js
.
The "Anchor" Form Element
The "Anchor" form element is a type of form element which is used provide a link to the user. Users can click on the element to visit the link in the same tab or new tab. The link can point to same domain or different domain. An exampe ui.json
-
{
"type":"anchor",
"label": {
"text": "Demo anchor"
},
"target":"_blank",
"url":{
"params":{
"name":{
"$ref":"model#/name"
}
},
"path":"/${name}"
},
"if":{
....
....
},
"disabled": true
}
The properties are described below -
label
- The label property describes the label element for the anchor form element.target
- The target attribute specifies where to open the linked document. Read more from [here](HTML DOM Anchor target Propertyurl
- This property describes the url that is thehref
of the anchor element. It has the following properties -params
- describes the name and json reference of the variables that are used in thepath
property as placeholders. All the variables that are used in thepath
property must be declared here first. The json reference for the varaibles can be from themodel
object, thediscriminator
of the wrapping single input form or theVuex Store
object.path
- It is a string denoting a javascript template literal . The placeholders inside the literal must declared in theparams
property. The actual path is calculated by replacing the placeholders with their actual value.path
property is evaluated to get ourhref
for the anchor element.
if
[OPTIONAL] - contains the description of the condition upon which the rendering of the anchor element depends on. If the condition returnstrue
, the element is rendered otherwise it is hidded from view.disabled
[OPTIONAL] - If not specified, it isfalse
by default. If specified and set totrue
, the anchor button is disabled and can not be clicked. If specified and set to a string value then it specifies the function name declared in function.js to set this value usingfunctions.js
.
The "Label" Form Element
The "Label" form element is a type of form element that is used to show a field independent Label in form. An exampe ui.json
-
{
"type": "label-element",
"label": {
"text": "Demo Label",
"hasLine": true,
"isSubsection": true
},
"customClass": "mr-10"
}
The properties are described below -
label
- The label property describes the label element for the label form element.customClass
[OPTIONAL] - Value type string. Pass custom class name for styling.
The "Tabs" Form Element
The "Tabs" form element is a type of form element that is used to switch between different forms that are in different tabs. Example of ui.json
-
{
"type": "tabs",
"label": "Demo Tabs",
"tabs": [
{
"value": "demo-value-1",
"text": "Demo Value 1"
},
{
"value": "demo-value-2",
"text": "Demo Value 2"
}
],
"schema": {
"$ref": "discriminator#/activeTab"
}
}
The properties are described below -
label
- The label of the tabs element. It is not shown in the UI, only needed for logical reasons.tabs
- contains an array of tab objects each describing a tab element. Each tab object has 2 properties -value
- The actual value that will be saved to a variable when the tab is selected by usertext
The title of the tab that will be shown to the user.
schema
- contains the JSON Schema or the reference to the schema for the string / number type variable that is being modified by the tabs form element.$ref
- contains the JSON reference string pointing to the JSON schema.
The Single Step Form Array
The single step form array is form that is used to take input array of object. An exampe ui.json
-
{
"type": "single-step-form-array",
"label": {
"text": "Demo Single Step Form Array"
},
"schema": {
"$ref": "schema#/properties/..."
},
"addFormLabel": "demo form label",
"tableContents": [
{
"type": "value",
"typeOfValue": "string",
"inTableColumn": true,
"label": {
"text": "Demo Label"
},
"path": "root/child1/child2/....",
"tableContents": [
...
...
]
}
],
"element": {
"type": "single-input-form",
...
...
}
}
The properties are described below -
label
- The label property describes the label element for the single step form array element.addFormLabel
this form label is used showing the new item adding button text,if
[OPTIONAL] - contains the description of the condition upon which the rendering of the array input form element depends on. If the condition returnstrue
, the form element is rendered otherwise it is hidded from view.fetch
[OPTIONAL] - contains the description of the API that is needed to be called to fill the input field with data.tableContents
- contains information about attributes for each object to show the table view of objects. each item of this array contains -type
Possible value can bevalue
orlabel
typeOfValue
- Required, if type is set tovalue
. Possible value can bestring
,array
,key-value
,code
orkey-operator-values-array
,inTableColummn
- It indicates the visibility of this field in table column. If not specified, it isfalse
by default.label
- Label object must contain text property. Also, It has 2 optional properties for styling -text
text part of the label. This part will be shown as table column name and label in details section.hasLine
[OPTIONAL] Value type boolean. Show an optional line for the label.isSubsection
[OPTIONAL] Value type boolean. Decrease font size for subsection label.
path
to access the value from object item.computed
- to compute the value using function fromfunction.js
. After fetching the value it will be stored on declaredpath
.tableContents
- contains information about attributes of childsingle-object-from-array
for each object to show the table view of objects. It is required when child object is also asingle-step-form-array
.
element
- contains theui.json
for a single array element. The ui for the existing array elements along with taking new array element as input is rendered using thisui.json
. A single array element can be -label-element
typeinput
typetextarea
typeeditor
typeselect
typecheckbox
typeradio
typeswitch
typesingle-step-form
typearray-input-form
typeobject-input-form
type
schema
- contains the JSON Schema or the reference to the schema for the array type variable that is being modified by the single step form array element.$ref
- contains the JSON reference string pointing to the JSON schema.
disabled
[OPTIONAL] - If not specified, it isfalse
by default. If specified and set totrue
, the single step form array will be disabled and can not be modified. If specified and set to a string value then it specifies the function name declared in function.js to set this value usingfunctions.js
.newItemValidator
[OPTIONAL] - Specifies the function name declared in function.js. This function takes individual single step form array items asitemCtx
inside the context object which is candidate item for adding and returns an object. If the individual single step form array item is valid, then returning empty object is okay. Otherwise it returns a object like -{ isInvalid: true, message: "demo message to show" }
for a particular item in key value input form.
individualItemDisabilityCheck
[OPTIONAL] - Specifies the function name declared in function.js. This function takes individual list items asitemCtx
inside the context object and should return an Object like -
{
isEditDisabled: true,
isDeleteDisabeld: true,
}
isEditDisabled
indicates the the item will e editable or not. Similarly, isDeleteDisabled
indicates the the item can be deleted or not.
The "Reusable-Element"
The reusable element is an element that is used to import and reuse wizard modules that are stored remotely and can be used in multiple places.
Special Properties
There are some special propertie such as discriminator
, if
, fetch
that are used to equip the UI with special abilities such as conditional rendering of elements, fetching data using api calls, etc. Here, we will look a more detailed description about these properties.
The discriminator
property
The discriminator
is a property that is used inside a single-step-form
to describe the schema of the variables which are not in model
object or inside our store
object in vue
. These variables are needed when the rendering of the form elements depends on values that are neither in model
object nor in store
object.
In implementation, these variables are declared inside the SingleStepForm
component and passed as a prop to the child form elements. The child form elements may reference these variables from inside their if
or fetch
property as parameters. Also, this value can be emitted to parent discriminator value, using emitAs
property in discriminator.
An example of discriminator
property is given below -
{
"discriminator": {
"activeTab": {
"type": "string",
"default": "default-tab",
"emitAs": "demo_parent_discriminator_name_to_emit"
}
}
}
The schema described inside the discriminator
follows the general Open API V3 schema conventions.
The if
property
The if
is a property that is used inside a form element such as single-step-form
, array-input-form
, object-input-fomr
, input
, select
, checkbox
, textarea
, editor
, radio
, switch
, anchor
to describe the condition upon which the rendering of the form elements depends on. It is an optional property.
This property is optional for form elements, if mentioned then the condition is resolved and if the condition resolves to true
, the form element is rendered otherwise it is hidden
An example is given below -
{
"if": {
"params": {
"applyinForPosition": {
"$ref": "model#/applyingForPosition"
}
},
"expression": "applyingForPosition === 'fe-software-eng'"
}
}
params
- describes the name and json reference of the variables that are used in theexpression
for the evaluation of the conditoin. All the variables that are used in the expression must be declared here first. The json reference for the varaibles can be from themodel
object, thediscriminator
of the wrapping single input form or theVuex Store
object.expression
- it is a string describing the expression that is evaluated to resolve the condition. It is a simple javascript expression that is resolved using.eval()
method. The variables used in this expression must be described inparams
first.
The fetch
property
The fetch
property is an optional property that is mentioned inside a form elemnt such as select
, checkbox
, radio
where we require option list to be fetched via HTTP requests from external servers or load data from a file in project directory. This property describes the necessary elements requred to make the HTTP call from the UI.
Example:
{
"fetch": {
"type": "post",
"data": {
"type": "application/x-www-form-urlencoded",
"params": {
"userId": {
"$ref": "store#/user/data/uid"
},
"body": "This is a demo post by s4k1b",
"title": "demo post sakib"
}
},
"params": {
"storyId": {
"$ref": "model#/cloud/topStory"
}
},
"path": "/item/${storyId}.json",
"filters": [
{
"$ref": "#/kids"
},
{
"text": {
"$ref": "#/"
},
"value": {
"$ref": "#/"
}
}
]
}
}
type
- describes the type of the http call. It can be either "get" or "post".data
- Required only if the type is set as "post". It describes the post reqest body object. It has several properties -type
- describes the format of data to be sent. Can be eitherapplication/json
orapplication/x-www-form-urlencoded
. If set toapplication/json
, the data object is sent as a plain JSON object. If set toapplication/x-www-form-urlencoded
, the data object is formatted to a key value pair where the keys and values are encoded in key-value tuples separated by'&'
, with a'='
between the key and the value.params
- describes the actual body of the data object to be sent. It contains the data object property names and their values. It either contains the direct values or reference to the actual values.
params
- describes the name and json reference of the variables that are used in thepath
property as placeholders. All the variables that are used in thepath
property must be declared here first. The json reference for the varaibles can be from themodel
object, thediscriminator
of the wrapping single input form or theVuex Store
object.path
- It is a string denoting a javascript template literal . The placeholders inside the literal must declared in theparams
property. The actual path is calculated by replacing the placeholders with their actual value.path
property describes the url to which api requests are made.filters
- This property describes the array of operations required for json-filter to extract relevant value from our api response. Iffilters
property is not provided, then the whole api response data is taken as our reponse value.The user should filter the api response according to the form element. If the form element is input type, then filtered response should be string, If if element is array-input-form then filtered response should be array, if element is object-input-type then it should be object type and so on.
In case of
select
element, the filtered response should be an array of objects each containing two properties,text
property andvalue
property. Thetext
property denotes the select option text and thevalue
property denotes the value for that option.
You can learn about how to write your
filters
according to your needs from here.You can also use
fetch
property to load data from a file stored in yourasset
folder:- The
method
prop in case of loading data from file is "load". - The file directory must be relative to your
/src/assets/wizard-resources/
directory in your project folder. - There must be a
/src/assets/wizard-resources/
directory in your project folder. - The
url
prop in case of loading data from file denotes the relative path for the file inside/src/assets/wizard-resources/
directory. All data files must be nested inside this directory. - Rest of the properties inside the
fetch
property acts in the same way as they did for making api calls. - Example:
"fetch": { "method": "load", "filters": [ { "value": { "$ref": "#/id" }, "text": { "$ref": "#/file" } } ], "path": "demo.json" }
The computed
property
The computed
property is an optional property that is mentioned inside a form elemnt such as list-input-form
, key-value-input-form
,object-input-form
,editor
,input
,textarea
,array-input-form
, select
, checkbox
, radio
where we require the value of element to be set from function call using function.js .
Example:
{
"computed": "demoFunction"
}
The customClass
property
The customClass
property is an optional property that is mentioned inside a form elemnt where we require to add any custom css class to that form element.
Example:
{
"customClass": "mb-20"
}
The required
property
The required
property is an optional property that can be mentioned inside all form elemnt except reusable-element
, multi-step-form
where we require to set the element will be required field or not. The value can be two types. boolean
or string
. String value is used to set it using functions.js
.
Example:
{
"required": true
}
The onChange
property
The onChange
property is an optional property that can be used on any form element. It denotes a function name which must be declared in functions.js. This function is executed whenever the value of the correspoinding form element changes. User can perform their required task inside the function body.
{
"onChange": "onChangeFunction"
}
The label
property
This object is responsible to show label of a form element. Label object must contain text property. Also, It has 2 optional properties for styling -
Example:
{
"label": {
"text": "demo text",
"hasLine": true,
"isSubsection": true
}
}
text
The label text of the form element.hasLine
[OPTIONAL] Value type boolean. Show an optional line for the label. Default value is false.isSubsection
[OPTIONAL] Value type boolean. Decrease font size for subsection label. Default value is false.
The encoder
property
Contains a string refers to the function from functions.js
. This function is responsible for encode the value to appropiate format if needed.
{
"encoder": "demoEncoderFunction"
}
The decoder
property
Contains a string refers to the function from functions.js
. This function is responsible for decode the value to appropiate format if needed.
{
"decoder": "demoDecoderFunction"
}
functions
The functions.js
file will contain user defined functions that can be referenced from ui.json
and has access to a context
variable that the user can use to perform complex tasks. Users can reference the functions from the fetch
and if
property in ui.json
. Function name can not contain '|', ::' or '/' characters
Parameters
The first argument for each function is a
context
object, containig all necessary methods and data that the user needs access to in this function.The remaining arguments ar passed by the user when the funtion is referenced from
ui.json
. eg -// example of passing arguments in function from ui.json { ... "if": "showAdditionalInfo|software-eng" ... }
Here,
showAdditionalInfo
is a function declared infunctions.js
file. The'software-eng'
is a string that is passed as a second argument when the function is called.// example function.js declaring showAdditionalInfo function function showAdditionalInfo({ model, getValue }, value) { const applyingForPosition = getValue(model, "/applyingForPosition"); return applyingForPosition === value; }
In the above example the string
'software-eng'
is passed as the parametervalue
. More paremeters can be passed by concatinating them using the|
character inui.json
file. eg:funtionName|parameter1|parameter2|...
.
Return value
The return value of the function depends on which property it was referenced by in ui.json
.
- If the function was referenced in
"if"
property, the return value of the function should be aboolean
value. - If the function was referenced in
"fetch"
property, the return value of the function should be in accordance with the required format by the ui element.
The context
object
Each function in the function.js
file has access to a context
object that will be passed as first argum