Simple Form Widget - Example 2

Last published at: May 2nd, 2023

This Document will illustrate how to write a new custom Form Widget, configure it using Manage Form Widget, use of widget in a forms designer and render the form widget within the form instance. This Form Widget is moderate in complexity, operating at client side as well as server side.

Form Widgets

 Following is a list of standard Form Widgets (html controls) used in the forms designer.

  1. Button
  2. Input
  3. Select
  4. Checkbox
  5. Radio button
  6. Table
  7. Image
  8. Label
  9. Hr
  10. File
  11. iFrame

 

Custom Form Widgets

Custom Form Widget is the combination of single or multiple html controls providing UI functionality.  Form widget is made up of the following components:

  1. HTML section
  2. Script section
  3. Server side dll
  4. Icon file
  5. Configure Form Widget


How to build the custom Form Widget

First create the empty html file with Widget name ex. Create a widget as ‘currency’ where the name of html file should be ‘currency.html’. This Form Widget calculates live currency based on US Dollar.

Basic structure of Form Widget should be as following

<!--currency UI Start-->

<formWidget id="formWidget_form" type="currency">

             .

             .

             .

</formWidget>

<!-- currency UI End-->

<!-- currency JS Start -->

<script>

             .

             .

             .

 

</script>

<!—currency JS Start -->


  • The code should be divided in to two sections Html Section and Script Section 

 

1. Html Section

Basic structure of HTML should be as following

<!-- currency UI Start-->

<formWidget id="formWidget_form" type="currency">

         <div>

             .

             .

             .

         </div>

</formWidget>

<!-- currency UI End-->

Make sure to have UI Start and End comments, comment section should be enclosed with 

               <!--  --> tag.

  • After the first comment tag, the first custom tag must be <formWidget … > … </formWidget>
  • By default, <formWidget> should have two attributes, Id and type. User can add other attributes as per their requirements.
  • <formWidget> id must be id="formWidget_form" which would be the unique id and is used across all custom Form Widgets within the application.
  • <formWidget> type must have the same name as html file name. For example – we are using currency.html so the type="currency".
  • <div> tag must be followed by <formWidget> tag, and all the style="…" attribute properties should be used within this <div> tag. However, the style="…" attribute should not be added within the <formWidget> tag.

 

<!--currency UI Start-->

<formWidget id="formWidget_form" type="currency">

 <div>

<table>

            <tr>

                <td colspan="2"><span class="formwidget-label">Currency Converter</span></td>

            </tr>

            <tr>

                <td><label id="formWidget_lblUSD" class="formwidget-sub-label" style="font-weight:bold">USD</label></td>

                <td><input id="formWidget_txtUSD" type="text" class="formwidget-text input-mini" onchange="GetCurrency('#formWidget_form')" /></td>

            </tr>

            <tr>

                <td><label id="formWidget_lblJYP" class="formwidget-sub-label" style="font-weight:bold">Japanese YEN</label></td>

                <td><label id="formWidget_clblJYP" class="formwidget-sub-label"></label></td>

            </tr>

            <tr>

                <td><label id="formWidget_lblGBP" class="formwidget-sub-label" style="font-weight:bold">Great Britain Pound</label></td>

                <td><label id="formWidget_clblGBP" class="formwidget-sub-label"></label></td>

            </tr>

            <tr>

                <td><label id="formWidget_lblEURO" class="formwidget-sub-label" style="font-weight:bold">EURO </label></td>

                <td><label id="formWidget_clblEURO" class="formwidget-sub-label"></label></td>

            </tr>

            <tr>

                <td><label id="formWidget_lblINR" class="formwidget-sub-label" style="font-weight:bold">Indian Rupees </label></td>

                <td><label id="formWidget_clblINR" class="formwidget-sub-label"></label></td>

            </tr>

             </table>

</div>

</formWidget>

<!--currency UI End-->


HTML controls, id and other attributes within the main div tag

  • Inside <div> tag user can create own html structure.
  • Use input and standard control despite of form and submit tag within main <div> mentioned in the page 1, 
  • Use div and span tag for layout design.
  • Bootstrap style library is also provided for layout design, so user can use bootstrap classes for div, span and html controls.

 

Element IDs inside formWidget

  • All html element IDs within the Form Widget should be prefixed with id="formWidget_..." and followed by user defined name. Only alphanumeric and “_” character is allowed in the ID.


example 1

A Widget has a Label control and user wants to use the id as "lblUSD", then the ID inside the formWidget control must be prefixed with "formWidget_...", such that the id would be: "formWidget_lblUSD".This id should be unique within the same widget control.

example 2

If a widget has another text control and user wants to use ID as "txtUSD" inside the formWidget, then the control must be prefixed with "formWidget_..." similar to example1. The id would be "formWidget_ txtUSD" and this  id should be unique in the same Widget.

 

Following code contains highlighted sample element IDs from formWidget as explained in examples.

 

Event handlers for formWidget controls

  • Use any valid JavaScript event in html element.
  • Event calling function must exist in the JavaScript section of the same formWidget html.

Example 1 -  

There is “GetCurrency” function written in JavaScript section. The user wants to call onchange="GetCurrency('#formWidget_form')" event, from textbox and access more than one element in JavaScript such that the user can send formWidget id 'formWidget_form' or  '#formWidget_form' as parameter . This way the User can access all child elements from the formWidget. If the user wants to access only  one element in JavaScript from formWidget, the user can send ‘this’ or formWidget id 'formWidget_txtUSD' as parameter.

 

JavaScript Section

Basic structure of JavaScript should be as followingType of Functions from formWidget JavaScript Section.

  • Add two types of functions which are as follows.  
    1. Init Function
      • Init function means initialize function which will work only on page load.
      • Init function as shown in above code highlighted in red box.
      • Init function must be written within $(function () {. . .});
      • Init function must be start with $("formWidget[type^='currency']").each(function () { . . . .});
      • In this function type must be formWidget type mentioned in the html section in this example we have mentioned formWidget type as ‘currency’ so we are using same in function "…[type^='currency']"
      • We can get the formWidget object by Using   $(this), once we get the object we can use it for further operations
      • In this example, we don’t need init function, so we are not going to use this here.

 

  1. Event Handler Function -  
    • User can add any valid function which can be called from html controls as shown in above code highlighted in blue box
    • User can write simple or parameterized function 
    • Parameters may be any control id or formWidget id as discussed in page 5. 
    • If formWidget id used as parameter, then user can get all the controls within the formWidget

 

 

 

Form Widget Example


<!--currency UI Start-->

<formWidget id="formWidget_form" type="currency">

         <div>

             <table>

            <tr><td colspan="2"><span class="formwidget-label">Currency Converter</span></td></tr>

            <tr><td><label id="formWidget_lblUSD" class="formwidget-sub-label" style="font-weight:bold">USD</label></td>

                <td><input id="formWidget_txtUSD" type="text" class="formwidget-text input-mini" onchange="GetCurrency('#formWidget_form')" /></td></tr>

            <tr><td><label id="formWidget_lblJYP" class="formwidget-sub-label" style="font-weight:bold">Japanese YEN</label></td>

                <td><label id="formWidget_clblJYP" class="formwidget-sub-label"></label></td></tr>

            <tr><td><label id="formWidget_lblGBP" class="formwidget-sub-label" style="font-weight:bold">Great Britain Pound</label></td>

                <td><label id="formWidget_clblGBP" class="formwidget-sub-label"></label></td></tr>

            <tr><td><label id="formWidget_lblEURO" class="formwidget-sub-label" style="font-weight:bold">EURO </label></td>

                <td><label id="formWidget_clblEURO" class="formwidget-sub-label"></label></td></tr>

            <tr><td><label id="formWidget_lblINR" class="formwidget-sub-label" style="font-weight:bold">Indian Rupees </label></td>

                <td><label id="formWidget_clblINR" class="formwidget-sub-label"></label></td></tr>

             </table>

         </div>

</formWidget>

<!--currency UI End-->

<!--currency JS Start -->

<script>

         function GetCurrency(currencyWidget) {

             var sFormWidgetID = currencyWidget.substring(0, currencyWidget.length - 4);

             var usdTxt = sFormWidgetID + 'txtUSD';

             var jpyLbl = sFormWidgetID + 'clblJYP';

             var gbpLbl = sFormWidgetID + 'clblGBP';

             var euroLbl = sFormWidgetID + 'clblEURO';

             var inrLbl = sFormWidgetID + 'clblINR';

 

             var tblData;

             var oData = {};

             $.ajax({

                 type: "POST",

            url: 'deFormWidgetService.asmx/getData',

            data: '{"sFormWidgetType":"currency","oData" :' + JSON.stringify(oData) + '}',

            contentType: "application/json; charset=utf-8",

            dataType: "json",

                 async: false,

            success: function (r) {

                if (r.d) {

                    tblData = r.d;

                }

            },

            error: function (r) {

                alert("Server Error");

            }

             });

             tblData = $.parseJSON(tblData);

             tblData = $.parseJSON(tblData.oData.currencyData);

             var amount = parseInt($(usdTxt).val());

 

             $(jpyLbl).text(tblData.rates.JPY * amount)

             $(gbpLbl).text(tblData.rates.GBP * amount)

             $(euroLbl).text(tblData.rates.EUR * amount)

             $(inrLbl).text(tblData.rates.INR * amount)

         }

</script>

<!--currency JS End -->

 



Copy “currency.html” file to “C:\inetpub\wwwroot\cDevWorkflow\Forms\FormWidgetUITemplates

 

 2. Server Side DLL

Start Microsoft Visual Studio and select “New Project”. Select “Visual C#” as the language and select “Class Library” as the project type. Also, select .Net Framework 4.5.2 from the top dropdown. This example will use C# as the development language. This same example can also be written using Visual Basic .Net. Provide Project name as “currency”

 


Once the Project is created, rename “Class1.cs” to “clsCurrency.cs”, it will automatically change the class name too.

 

Add a reference to cDevWorkflow, navigate to the following directory “C:\inetpub\wwwroot\cDevWorkflow\bin”. Select the file “cDevDecisionEngine.dll

Add a “using” statement: cDevWorkflow.cDevDecisoinEngine

 

Let’s start building the class, first implement the interface called: “deIFormWidget”. To implement the interface, we have to implement the “deIFormWidegt.getData” method. Which returns “clsFormWidgetReturn” object.

 

 


This example collects latest currency data from external REST API sources. To get the information “HTTPWebRequest” is used for API web request, which returns JSON in http stream(string). Pass this string result to oData. oData is “Hashtable” attribute of “clsFormwidgetReturn” class.  Return the “clsFormwidgetReturn’s” object, which will referred at client side javascript. “HTTPWebRequest” requires System.Net and System.IO dependencies. 

 

 

Add data annotation “formWidgetData” to the class “clsCurrency”, so that cDevWorkflow is able to auto configure the Form Widget.“formWidgetdata” data annotation have 4 default parameters ,they are as follows

  1. formWidgetName :  This parameter type must be string. Form Widget name should be same as type mentioned in the Form Widget html file, so the Form Widget name would be “currency”. This parameter value is case sensitive.
  2. formWidgetDesc : This parameter type must be string, Form Widget description should be the short description for the Form Widget.
  3. formWidgetCat : This parameter type must be string, category should be one of the category defined in the system for the Form Widget.
  4. formWidgetDisplayName: This parameter type must be string, Form Widget display should be the short name for the Form Widget which will be displayed at Form Widget menu in form designer.

 

Now the Form Widget is complete, compile the Form Widget to build the DLL.

Navigate to the bin/Debug directory where the DLL was compiled, select the DLL: “currency.dll”. Right click on the file and select “Copy” from the context menu

 


Copy the Form Widget dll to the following directory: “C:\inetpub\wwwroot\cDevWorkflow\bin”.

 

 

3. Icon file

First let’s setup an icon for the new Form Widget. Create any icon having 40 x 40 pixels in size and PNG format, name the icon same as the Form Widget name “currency”. Copy the file to the following directory “C:\inetpub\wwwroot\cDevWorkflow\images\FormWidgets”.

 

Configure Form Widget

Navigate to the FlowWright Configuration Manager and select the “Form Widgets” menu item. 

Once select  “Auto Detect” menu item, the auto detect UI should display the custom Form Widget in a table as shown below.

Select the Form Widget from table and click on configure from menu bar. The Form Widget will be automatically configured within FlowWright.

 

 

 

Once the Form Widget is successfully configured, select “UtilsUpdate Master Script” menu item as shown below.

 

Navigate to the FlowWright Configuration Manager and select the “Forms”, select the “Form Definitions” option from submenu. Select the “ActionsCreate” menu item to create a new form definition.

 

 

Once clicked on the “Create” menu item, a pop-up window will be displayed 

 

Enter Definition Name, Check Open Designer checkbox and Click on the “Create” button.

Once form Designer is displayed, search for “currency” Form Widget in side bar menu, click and drag the “Currency” Form Widget on designer section as shown below: