Skip to content

Latest commit

 

History

History
112 lines (91 loc) · 8.11 KB

form-rendering.service.md

File metadata and controls

112 lines (91 loc) · 8.11 KB
Title Added Status Last reviewed
Form Rendering service
v2.0.0
Active
2018-11-20

Form Rendering service

Maps a form field type string onto the corresponding form widget component type.

Class members

Methods

  • getComponentTypeResolver(type: string, defaultValue: Type<any> = this.defaultValue): DynamicComponentResolveFunction
    Gets the currently active DynamicComponentResolveFunction for a field type.
    • type: string - The type whose resolver you want
    • defaultValue: Type<any> - Default type returned for types that are not yet mapped
    • Returns DynamicComponentResolveFunction - Resolver function
  • register(components: Function, override: boolean = false)
    Register multiple components
    • components: Function -
    • override: boolean -
  • resolveComponentType(model: DynamicComponentModel, defaultValue: Type<any> = this.defaultValue): Type<any>
    Finds the component type that is needed to render a form field.
    • model: DynamicComponentModel - Form field model for the field to render
    • defaultValue: Type<any> - Default type returned for field types that are not yet mapped.
    • Returns Type<any> - Component type
  • setComponentTypeResolver(type: string, resolver: DynamicComponentResolveFunction, override: boolean = true)
    Sets or optionally replaces a DynamicComponentResolveFunction for a field type.
    • type: string - The type whose resolver you want to set
    • resolver: DynamicComponentResolveFunction - The new resolver function
    • override: boolean - The new resolver will only replace an existing one if this parameter is true

Details

The Form Field component uses this service to choose which widget to use to render an instance of a form field. The Form Field model stores the field type name as a string (see the table below). The Form Rendering service maintains a mapping between each type name and a corresponding DynamicComponentResolveFunction. The function takes a FormFieldModel object as its argument and uses the data from the object to determine which widget should be used to render the field.

In some cases, the field type string alone is enough to determine the widget type and so the function just returns the type directly:

let customResolver: DynamicComponentResolveFunction = () => CustomWidgetComponent;
formRenderingService.setComponentTypeResolver('text', customResolver, true);

In other cases, the function may need to choose the widget dynamically based on specific values in the form data:

let customResolver: DynamicComponentResolveFunction = (field: FormFieldModel): Type<{}> => {
    if (field) {
        let params = field.params;
    }
    return UnknownWidgetComponent;
};
formRenderingService.setComponentTypeResolver('text', customResolver, true);

Default type mapping

The Form Rendering service is initialized with the mapping shown in the table below:

Stencil name Field type string Component type
Amount "amount" AmountWidgetComponent
Attach "upload" AttachWidgetComponent or UploadWidgetComponent (based on metadata)
Checkbox "boolean" CheckboxWidgetComponent
Date "date" DateWidgetComponent
Display text "readonly-text" DisplayTextWidgetComponentComponent
Display Rich text "display-rich-text" DisplayRichTextWidgetComponent
Display value "readonly" DisplayValueWidgetComponent
Dropdown "dropdown" DropdownWidgetComponent
Dynamic table "dynamic-table" DynamicTableWidgetComponent
Group of people "functional-group" FunctionalGroupWidgetComponent
Header "group" ContainerWidgetComponent
Hyperlink "hyperlink" HyperlinkWidgetComponent
Multi-line text "multi-line-text" MultilineTextWidgetComponentComponent
Number "integer" NumberWidgetComponent
People "people" PeopleWidgetComponent
Radio buttons "radio-buttons" RadioButtonsWidgetComponent
Text "text" TextWidgetComponent
Typeahead "typeahead" TypeaheadWidgetComponent

You can add new items to the mapping or replace existing items in order to customize the way fields are rendered.

Adding new or replacement items to the mapping

You can use the setComponentTypeResolver method to add a new ComponentTypeResolver function for a particular type string. You can also replace the resolver for a type that already exists in the mapping if you set the override parameter to 'true':

formRenderingService.setComponentTypeResolver('text', newResolver, true);

You would typically use this to replace an existing widget with your own custom version that implements a modified layout or responds differently when the data is entered. See the Form Extensibility and Customisation guide for further details and examples of this technique.

See also