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 three React components: DWKitAdmin, DWKitForm and FormContent. In fact, you will hardly ever need to adjust the DWKitAdmin component. As for the FormContent component, it, actually, represents a wrapper over the DWKitForm component.

The 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/"
    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.

The DWKitForm component

This component draws a form created in the form builder and fills it in with data. Its application is described in the architecture section. Let's take a closer look at the props of the DWKitForm component. There are two ways to adjust it.

  • The option below is used inside the FormContent component to display dynamic forms.
<DWKitForm
    key = "form unique key"
    formName="FormName"
    model={{model (form markup) object}}
    data={{data object}}
    errors={{error object}}
    dataChanged={(form, {key, value}) => {}}
    eventFunc={(args) => {}}
    getAdditionalDataForControl={this.props.additionalFetch.bind(this, ()=>{return this.props.formName})}
    hideControls={["controlName1","controlName2"]}
    readOnlyControls={["controlName1","controlName2"]}
    readOnly={false}
/>
  • formName - the name of a form, under which it is saved in the admin panel, in your system.
  • model - the object of a layout, by which the form is drawn. This object is saved in the form builder.
  • data - a data object uploaded to the form.
  • errors - an object of the {control1 : "error message", control2: "error message"} type. Control1 and control2 are the Name of a control, set in the form builder. If there is a property with such name in the object, DWKitForm will display a validation error in this control.
  • dataChanged - a function that sends changed data to the application. Form represents a link to the DWKitForm component, {key, value}is the control 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 is a chain of client actions to be called, for example, the "validate, save, exit" line. Parameters are the parameter object. This information can be edited in the [form builder events tab] (/documentation/admin/form/#events-tab). The FormContent component forwards this information to the client actions
  • getAdditionalDataForControl - this event is called by the GridView controls with the enabled server paging and Dictionary to obtain data.
  • hideControls - a list of the names of the controls hidden in the form.
  • readOnlyControls - a list of the names of the controls that are available in the read-only mode.
  • readOnly - a global readonly of a form

This option is used when both model and data are requested not by the DWKitForm component itself, but, for example, supplied from the global state of the application. The 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 concurrent url, while the data are formed manually.

The rule of binding data to a form

DataController is one of the main data suppliers in the DWKit application. It returns the 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. The name of a property in the json data object should coincide with the name of a control, in which this value should be displayed.
  • For the collections. The name of a property - collection (array) should coincide with the name of a control displaying a collection.
  • The names of columns in a control (all controls displaying collections have column settings) should coincide with the names of properties of the collection members.

The FormContent component and lifecycle of a form in it

In the DWKit application, the DWKitForm component is integrated into the application infrustructure. Being wrapped in the FormContent component, this component enables:

  • synchronization of the data from DWKitForm and a global state of the application
  • execution of the chains of user-defined client actions
  • display of modal forms upon editing collections (of any level of nesting)
  • lifecycle of a form: Requesting a model - Requesting data - Initialization - Execution of client actions

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

  • Requesting a model. FormContent analyzes the url or its formName property and uploads a model (layout) of a form via UserInterfaceController. If the Url represents form/{formName}/, the formName will be obtained from the url.
  • Uploading data. FormContent analyzes the url and uploads the data via DataController. If the Url represents form/{formName}/{filter}, the 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 hide.

Then, the conditions set in the form builder are determined.

  • After that, the form constantly sends its changed data via the dataChanged event and calls chains of client actions.