Creating JavaScript Form Controls
  • Updated on 20 Feb 2017
  • 5 minutes to read
  • Print
  • Dark
    Light

Creating JavaScript Form Controls

  • Print
  • Dark
    Light

This document applies only to 5.0 versions.
You can create custom form controls using JavaScript and load them into Decisions. They have inputs and outputs just like normal form controls. Below is a brief explanation of the different control types.

Action control - This is a Form Control that performs an Action i.e. Button, Link. These are used to exit a form on a particular path.   
Data control - This is a Form Control that allows you to work with Data. i.e. Label, Text box etc. 
Page control - This is a Page Control. These are used in our Dashboard/Page Designer
Scripts - This is a Control that allows you to include your Custom Scripts
Styles - This is a Control that allows you to include your Custom Styles (CSS)

Let's start by creating a very simple control. This example will consist of a single button, and the output of our control will be the number of times the button has been clicked. Our control won't need any input data.
This is the interface that we'll be following in order to create this control. All JavaScript data controls will have these 4 specific functions:

 interface JSBasedComponentInterface {
    initialize(host: JQuery, component: any): void;
    resize(height: number, width: number): void;
    setValue?(data: any): void;
    getValue?(): any;
  }

We'll start with a blank text document. Let's call our control class 'MyControl':

 function MyControl() { };

Note that Decisions supports a wide range of browsers, including Internet Explorer going back to version 10, so for maximum user convenience avoid JS syntax that is incompatible with that minimum version.
The first function we'll add is `initialize` . This function will be called one time, when our control is being created.

 MyControl.prototype.initialize = function(host, component){
    // Here we assign 'host' to a variable on this control,
    //   so that we can access it later:
    this.host = host;
    // Our counter starts at 0:
    this.timesClicked = 0;

    // Create and configure the button:
    var button = document.createElement('button');
    button.type = 'button';
    button.textContent = 'Click me';

    var thisControl = this; // To avoid 'this' problems inside the onclick event.

    // When the button is clicked, increment our counter:
    button.onclick = function(e){
      thisControl.timesClicked++;
    };

    // Add the button to the 'host' jquery object:
    host.append(button);
  };

The next function in our class is `resize` .

 MyControl.prototype.resize = function(height, width) {
    if (this.host && height && width && (height > 0) && (width > 0)) {
      this.host.css({ width: width, height: height });
    }
  };

This function can be used to handle special resizing rules, but most controls won't need to modify it - copying & pasting this `resize` function should be enough.
Next is `setValue` . This function is used when a control takes input data. However, this control doesn't have any inputs, so our `setValue` function will remain empty. (For an example that includes input data, see the advanced documentation for this feature.)

 MyControl.prototype.setValue = function(data){
    // This control has no inputs, so no code is necessary here.
  };

Finally, we come to `getValue` . This is where we return the output from our control. This function will be called once when the form concludes.

 MyControl.prototype.getValue = function() {
    // Output data should be an object with properties that match the
    //   names of our outputs. In this case, our output is named 'TimesClicked'.
    return {
      TimesClicked: this.timesClicked
    };
  };

That's all we need for our .js file. Here's how it looks all together:

 function MyControl() { };

  MyControl.prototype.initialize = function(host, component){
    // Here we assign 'host' to a variable on this control,
    //   so that we can access it later:
    this.host = host;
    // Our counter starts at 0:
    this.timesClicked = 0;

    // Create and configure the button:
    var button = document.createElement('button');
    button.type = 'button';
    button.textContent = 'Click me';

    var thisControl = this; // To avoid 'this' problems inside the onclick event.

    // When the button is clicked, increment our counter:
    button.onclick = function(e){
      thisControl.timesClicked++;
    };

    // Add the button to the 'host' jquery object:
    host.append(button);
  };

  MyControl.prototype.resize = function(height, width) {
    if (this.host && height && width && (height > 0) && (width > 0)) {
      this.host.css({ width: width, height: height });
    }
  };

  MyControl.prototype.setValue = function(data){
    // This control has no inputs, so no code is necessary here.
  };

  MyControl.prototype.getValue = function() {
    // Output data should be an object with properties that match the
    //   names of our outputs. In this case, our output is named 'TimesClicked'.
    return {
      TimesClicked: this.timesClicked
    };
  };

Let's save this as MyJsControl.js, and then we'll lo ad it into Decisions.


Loading a .js file into Decisions as a JS form control

First, navigate to any designer folder. Click the Create Form button, then find the JavaScript Control menu, and click Add Data Control then click Create.
2018-01-09_120503-1024x615.png

Now, in the Add Javascript Control window, we need to supply a name, information about our input/output data, and tell Decisions how to use our .js file.
The name can be anything you want - let's call it 'Our JS Control'.
This control has no input data, so we don't add anything to the Input Data section.
We do need to define some output data, so check the Different Output Data checkbox, and the Output Data section will appear.
Click Add New under the Output Data section. We decided that our control had a numerical output named "TimesClicked", so that's what we enter here: "TimesClicked" in the Name field, and pick Int32 [Number] for the Type field, then click OK .
2018-01-09_120753.png

In the Runtime Information section, the JS Class Name must match the class name inside our .js file. Our class name is 'MyJSControl', so enter MyJSControl here. Click Choose File to upload our MyJsControl.js file. 
Finally, click SAVE CONTROL to create our new form control. That's all you need to do - the control is ready to be used in a form.
2018-01-09_121042.png


Using a JS control in a form

Let's look at how we can access our new control:
Create a new form in this folder. In the Form Controls tab at the upper right, start by dragging a Button onto the form. Call it 'Submit'.
Next, in the Form Controls > JS Controls > [Current Folder] drag Our JS Control to the form.
2018-01-09_121243-1024x540.png

Save and close the form.
Next, create a flow to display the form. Add a Show Form step, and select the form we just created. (There's no need to connect the Show Form step to the endpoint - we can test it without that.)
Click Debug Flow at the top. Click the large 'play' button. The form will appear:
2018-01-09_121356-1024x540.png

Click the 'Click me' button as many times as you want, then click Submit.

Switch to the Execution Dashboard tab (near the top of the screen).

Click on 'Show Form', the 2nd step listed, and then on View Output Data .

jsControl6-2-1-1024x803.png

You can see that the output from the form includes our TimesClicked:
jsControl7-1-1-1024x806.png

Was this article helpful?