Package Exports

@humany/widget-forms

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@humany/widget-forms) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@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'`, 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.

`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`	`ListComponentOption[]`	List of checboxes.
`DropDownList`	`ListComponentOption[]`	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`	`ListComponentOption[]`	List of radio buttons.
`Text`	`string`	Input text.
`Textarea`	`string`	Input textarea.

ListComponentOption

Definitions for items in list-based components, such as CheckboxList. RadioButtonList and DropDownList.

Name	Value type	Description
`label`	`string`	Display text
`value`	`string`, `number`, `boolean`	Value returned in `formData`

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();