Skip to main content

Introducing Formengine - The New Formbuilder, try for FREE formengine.io.

Client React components

You can find a brief description of the client architecture in the architecture section. For proper operation, you need to work with following React components: <DWKitAdmin/>, <DWKitForm/>, <StateBindedForm/>, <FormContent/> and <FlowContent/>. In fact, you will hardly ever need to adjust the <DWKitAdmin/> component. As for the <FormContent/>, <FlowContent/> and <StateBindedForm/> components, they, actually, represents a wrapper over the <DWKitForm/> component.

DWKitAdmin component​

This component displays the entire admin panel. It is adjusted by default in the starter application.

<DWKitAdmin
    apiUrl="/configapi"
    workflowApi="/workflow/designerapi"
    imageFolder="/images/"
    localizationFolder="/localization/"
    themesFolder="/themes/"
    deltaWidth={0}
    deltaHeight={0}
    controlActions={globalActions}
    returnToAppUrl="/"
/>

The settings have already been described in the architecture section. As a rule, you won't have to change them.

DWKitForm component​

This component renders a form created in the Form Builder and fills it in with data. Its usage is described in the architecture section. Let's take a closer look at the props of the <DWKitForm/> component. There are two ways to use it.

Firstly, you can use this component just as it is used inside <FormContent/> and <FlowContent/>, i.e. to display dynamic forms. This option is used when both model and data props are requested not by the <DWKitForm/> component itself, but, for example, transferred from the global state of the application.

<DWKitForm
    key="form unique key"
    formName="FormName"
    model={{model (form markup) object}}
    data={{data object}}
    extendedData={{
        filters: {{collection controls filter object}},
        schemes: {["schemeCode1", "schemeCode2"]},
        selectedScheme: "schemeCode1"
    }}
    errors={{error object}}
    dataChanged={(form, {key, value, additionalValues}) => {}}
    eventFunc={(args) => {}}
    getAdditionalDataForControl={(control, {startIndex, pageSize, filters, sort, model}, callback) => {}}
    hideControls={["controlName1", "controlName2"]}
    readOnlyControls={["controlName1", "controlName2"]}
    readOnly={false}
    uploadUrl={'/data/upload/'}
    downloadUrl={'/data/download/'}
/>
  • formName - name of a form, under which it was saved in the admin panel.
  • model - the object of a layout, by which the form is drawn. This object is saved in the Form Builder.
  • data - data object uploaded to the form. Read more about mapping form and data.
  • extendedData - here we transfer various data required for certain form components to fulfil different tasks.
  • errors - an object of the {control1 : "error message", control2: "error message"} type. 'control1' and 'control2' are control (component) Name properties, set in Form Builder. If there is a property with such name in errors object, <DWKitForm/> will display validation error in this component. See Tooltip Tab description to get more info about errors appearance in DWKit.
  • dataChanged - function that sends changed data to the application. form represents a reference to the <DWKitForm/> component, {key, value, additionalValues} is the control (component) Name + its new value.
  • eventFunc - this function will be called if a control event is associated with a chain of client actions in the Form Builder. args is the object of the {key, controlRef, formName, component, eventName, actions, parameters} type.
    • actions property is a chain of client actions to be called, for example, the 'validate, save, exit' string.
    • parameters property are the parameter object. This information can be edited in the form builder events tab. The <FormContent/> (<FlowContent/>) component forwards this information to the client actions.
  • getAdditionalDataForControl - this function is called by GridView, Dictionary, TreePicker, Repeater components to get data with server paging, and by WorkflowBar component to get a list of available commands and states.
  • hideControls - a list of components names hidden in the form.
  • readOnlyControls - a list of components names that are available in the read-only mode.
  • readOnly - a global readonly of a form.
  • uploadUrl - url to upload files.
  • uploadUrl - url to download files.

Second option is used when <DWKitForm/> itself requests data. In this case, you should specify modelUrl and dataUrl, not model and data. At the same time, you should necessarily specify only modelUrl, other parameters can be specified if required. For example:

<DWKitForm formName="header" data={{currentUser: user.name}} modelurl="/ui/form/header" />

A form is requested by the specified url, while data is formed manually.

The rule of binding data to a form​

DataController is one of main data suppliers in the DWKit application. It returns JSON objects of the following type:

{
...
    property1: value1,
    property2: value2,
    __id: '90fb3531-808f-43d9-be92-d3c5e8b70ebd',
    collection1: [
        {
        ...
           property1: value1,
           property2: value2,
            __id: 'cd8ebe54-2a33-4b3a-b318-0bbc1d13af87'
        ...
        },
        {
        ...
            property1: value1,
            property2: value2,
            __id: 'f47d6f0e-81a2-4fbd-b6e2-8083b518e547'
        ...
        },
    ]
...
}

The following rules should be applied in order for the data to be displayed in a proper control (binding):

  • For the main record. Property name in JSON data object should match control (component) name, in which this value should be displayed.
  • For the collections. Property name - collection (array) should match control name displaying the collection.
  • Columns name in the collection control (all controls displaying collections have column settings) should match properties names of the collection members.

Learn more about mapping form and data.

FormContent component and form life cycle​

In DWKit application, <DWKitForm/> component is integrated into the application infrastructure. Being wrapped in <FormContent/> (or <FlowContent/>) component, this component enables:

Life cycle of a form (inside component) includes the following stages:

  • Requesting a model. <FormContent/> (or <FlowContent/>) analyzes the url or its formName property and uploads a model (layout) of a form via UserInterfaceController. If the Url represents form/{formName}/, formName will be obtained from the url.
  • Uploading data. FormContent analyzes the url and uploads data via DataController. If the Url represents form/{formName}/{filter}, filter will be obtained from the url.
  • Initialization. When the inner <DWKitForm/> finds out it has both model and data, it sends a client action with the init name via eventFunc. It determines what controls should become readonly and hidden. Then, conditions set in the form builder are determined.
  • After that, form constantly sends its changed data via the dataChanged event and calls chains of client actions.

FlowContent component​

<FlowContent/> component is used in the Business flow mechanism.

StateBindedForm component​

<StateBindedForm/> component is a wrapper over the <DWKitForm/> component, bound to the custom part of the global state of the client application. Its usage and settings are described in the SignalR section.