@humany/widget-forms

This package contains utilities for creating form definitions for Humany widgets, used in different parts in the widget framework. The utilities are meant to be used together with other APIs, such as the Conversation Platform API, and it does not have capabilities to render a UI completely on its own.

FormBuilder

The FormBuilder provides a convenient way to create and modify Form objects. Create an instance by using the create() factory as shown below.

import { FormBuilder } from '@humany/widget-forms';

const builder = FormBuilder.create();

createComponent(info: ComponentInfo, createChildren?: ComponentFactory);

Creates a new component based on the provided ComponentInfo object and appends it to the current Form.

builder.createComponent({
    component: 'Text',
    type: 'string',
    name: 'model',
});

ComponentInfo

Describes a component in a form.

Name	Type	Required	Description
name	string	Yes	The name of the component.
type	string	Yes	The underlying type of the component. Can be 'string', 'number', 'boolean', 'array', or 'object' for components with children.
component	string	Yes	The UI component used to render the component. Can be any of the built-in UI components.
title	string	No	The display name of the component.
evaluate	boolean	No	Indicates whether changes to the component value should be evaluated. Default: false.
value	string, number, boolean	No	The initial value of the component.
required	boolean	No	Whether the component should be displayed as being required. Default: false.
items	Array<OptionItem>	No	Options for type 'array' when multiple fixed options are available.

OptionItem

One of a series of fixed options available for list och multi-select components.

Name	Type	Required	Description
label	string	Yes	The text label to be displayed for the item.
value	string	Yes	The value associated to the item.

ComponentFactory = (builder: FormBuilder) => void

A factory method for creating nested components such as fieldset.

Built-in UI components

Name	Supported value types	Description
Agreement	boolean	Checkbox with associated link.
CheckboxList	string[]	List of checboxes.
DropDownList	string[]	List of select options.
Email	string	Input with e-mail constraint.
GenericDiv	N/A	Empty div used as placeholder when styling.
Number	number	Input with number constraint.
Password	string	Password input.
RadioButtonList	string[]	List of radio buttons.
Text	string	Input text.
Textarea	string	Input textarea.

Creating simple components

The following example shows construction of a form with two components, one for country and one for city.

const form = builder
    .createComponent({
        component: 'Text',
        type: 'string',
        name: 'country',
        value: 'SE',
    })
    .createComponent({
        component: 'Text',
        type: 'string',
        name: 'city',
        value: 'Stockholm',
    })
    .get();

Creating nested components

The following example shows construction of a form with nested components. The first component is a fieldset holding two child components; first and and last name. The second argument to the fieldset component is a ComponentFactory function that exposes a FormBuilder instance used to create the nested child components.

const form = builder
    .createComponent(
        {
            component: 'Fieldset',
            type: 'object',
            name: 'name',
        },
        (builder: FormBuilder) => {
            builder
                .createComponent({
                    component: 'Text',
                    type: 'string',
                    name: 'first-name',
                    value: 'John',
                })
                .createComponent({
                    component: 'Text',
                    type: 'string',
                    name: 'last-name',
                    value: 'Doe',
                });
        }
    )
    .get();