Skip to main content
Version: 2023.1

Your first Form Field Extension JS

Starting from version 2020, you can write your own UI extensions for the modern form based on the WEBCON BPS portal interface. These extensions are supposed to add extra functionality to standard form fields that exist in the WEBCON BPS system by default, and customize them to better match your business needs. The example below describes the process of creating your first Form Field Extension JS step by step, in order to show you that it is not that hard as it may seem at first. The example involves a control which allows you to input and validate a number in the postcode format used in Poland.

Templates and tools

As with other types of plugins, you can use our templates which are designed to make the process of creating your own extensions effortless. There are 2 places from where you can grab the installer and extend your Visual Studio instance:

In addition to the templates, it installs the WEBCON BPS SDK Tool which will help you with the process of building and testing your own Form Field Extension JS, as well as creating the package of all the plugins whose description can be found in the plugin manifest JSON file.

Creating a project

NewProjectJS

After you confirm the selection of your project type, choose a name, location and solution name.

ConfigJsProject

Make sure that the checkbox “Place solution and project in the same directory” is not selected, because it interfere in the process of creating and publishing package with your plugins.

Creating a modern form field extension

In order to develop your own extension of a form field on the modern form, it is recommended to use the item template: BPS 2023 Form Field Extension JS, because it will create the whole structure with all necessary files, along with the example code, and also add appropriate entry in the manifest JSON file which is supposed to exist in the root of the project. We will name the extension PhoneNumberControl because of its intent.

JsActionItem

After choosing a name and clicking the “Add” button, a popup will be appear which will ask you for some additional details about the created plugin. In this example, let’s create an extension for the modern form field that is not connected with the logic class in order to make this really straightforward.

ExtensionJsConfig

Data model

If Form Field Extension JS does not use a logic class, the model by which the extension communicates with the backend depends on the form field on which the extension will be used. Possible options:

  • Single line text - string object
  • Multi line text - object with properties:
{
"comments": [],
"primary": ""
}
  • Integer - object of number type
  • Decimal - object with property "value" of number type:
{
"value": 123
}

When saving data, you also need to match the model of form field. If you need to use your own model, you have to implement the logic part and define the model in it.

Configuration

To configure Form Field Extension JS without logic class, you need to construct a json and pass it in Designer Studio in form field advanced configuration.

FormFieldExtensionJSConfiguration

The configured json is available in the extension code using the sdkConfiguration parameter that is passed to CustomControlComponent.

Assets

In order to use additional assets, they must be placed in the assets directory and for each file name and path must be specified in the assets collection in manifest.json file. An asset configured this way can then be used in the extension code using the predefined name.

Validators

Two types of validators can be implemented in Form Field Extension JS:

  • EmptyValueValidator - A validator used to determine whether a value in a control is empty, the validator will be called when the BPS needs to check whether a field has been completed, e.g. when a field requiredness is enabled. Validator returns true or false.
  • AdditionalValidator - A validator that can be used for additional validation of user-entered data. It is called each time when onChange method is used. The validator returns an object with isValid(bool) and errorMessage(string) which will be displayed to the user on the form.

WEBCON BPS SDK Tools

The VSIX installer which you used to extend Visual Studio with WEBCON BPS Extensions also provides the WEBCON BPS SDK Tools. It tries to find plugins of type Form Field Extension JS which are specified in the manifest file inside the startup project. If your solution contains more than one project, you can switch the controls displayed in the tool by right clicking the project and using the command “Set as startup project”. The tool can be found in View > Other Windows as shown below.

SdkTools-1024x541

Publish-1024x542

The tool does most of the scripting for you so that you do not have to remember all the npm commands that are required for developing form fields in React.

Building Form Field Extension JS

In order to build your Form Field Extension JS you have to select it in the appropriate dropdown in the tool and click the build button. It results in creating the BPSPKG file which contains all necessary files for the control. Please keep in mind that the first time you build the modern form field will take a little bit longer, due to downloading all the npm dependencies the extension needs.

Testing Form Field Extension JS

To help with the process of creating your own Form Field Extension JS, we also equip you with the so-called workbench, which creates an environment that allows you to test the extension. Once you have built your control, you can try it out with the test button – found next to the build button.

Publishing the package

Once you have built your extensions, you can use the WEBCON BPS SDK Tools publish functionality. It will create a package of your plugins which is described in this article. The only new thing here is the existence of the BPSPKG file. The contents of freshly generated package that is ready to be imported into WEBCON BPS Designer Studio are shown below.

PackageContent

Registering the package

You register the package in WEBCON BPS Designer Studio as shown below. It will add all your plugins that exist in the package automatically. You can then verify if everything has been imported correctly.

RegisterPackage

Designing the workflow

For the sake of simplicity, this tutorial we will feature a very straightforward workflow that consists of three steps, but of course you can build any workflow/process/application you want.

SampleWorkflow-1024x691

Then create the form field of the type “Single line of text” and customize it with the created extension.

StudioFieldCustomization

As with any other field, do not forget about positioning it on the Global form template and making it visible via the Field matrix, as shown below:

FieldMatrix

Now save your process and start a new workflow instance inside it. After you start your new instance and progress it to (in this example) the intermediate step, you should be able to see your modern form field extension as in shown on the screen below.

PortalJsField

Congratulations! You have created your first Form Field Extension JS for the modern form.