Simple Form Widget - Example 1

Last published at: May 14th, 2024

This Document will illustrate how to write a new simple Form Widget, configure it using Manage Form Widget, use the widget within the forms designer and render the widget within a form instance.

Form Widgets

Following is the list of standard Form Widgets (html controls) used within 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. A Form Widget  consists of these 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 ‘sum’ where the name of html file should be ‘sum.html’.

Basic structure of Form Widget should be as following

<!--sum UI Start-->

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

        .

        .

        .

</formWidget>

<!--sum UI End-->

<!--sum JS Start -->

<script>

        .

        .

        .

 

</script>

<!--sum 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

<!--sum UI Start-->

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

    <div>

        .

        .

        .

    </div>

</formWidget>

<!--sum 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 the custom Form Widgets within the application.
  • <formWidget> type must have the same name as html file name. For example – we are using sum.html so the type="sum".
  • <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.

 

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

<!--sum UI Start-->

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

 <div>

   <div>

            <label id="formWidget_lblheader" class="formwidget-label">Sum</label>

        </div>

        <div>

            <div class="side-by-side">

                <input type="text" id="formWidget_txtNum1" class="formwidget-text input-mini" onchange="ValidateandCalculate('#formWidget_form')" /> + <br />

                <label id="formWidget_lblNum2" class="formwidget-sub-label">Number1</label>

            </div>

            <div class="side-by-side">

                <input type="text" id="formWidget_txtNum2" class="formwidget-text input-mini" onchange="ValidateandCalculate('#formWidget_form')" /> = <br />

                <label id="formWidget_lblNum2" class="formwidget-sub-label">Number2</label>

            </div>

            <div class="side-by-side">

                <input type="text" id="formWidget_txtTotal" class="formwidget-text input-mini" onchange="ValidateandCalculate('#formWidget_form')" /> <br />

                <label id="formWidget_lblTotal" class="formwidget-sub-label">Total</label>

            </div>

        </div>

        <div>

            <label id="formWidget_lblErrorMsg" class="failure"></label>

      </div>        

 </div>

</formWidget>

<!--sum UI End-->



  • 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

 If a Widget has a Label control and user wants to use the id as "lblheader", the ID inside the formWidget control must be prefixed with "formWidget_...", such that the id would be "formWidget_lblheader".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 "txtNum1"  inside the formWidget, the control must be prefixed with "formWidget_..." similar to example1. Now the id would be "formWidget_ txtNum1" 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 “ValidateandCalculate” function written in JavaScript section. The user wants to call onchange="ValidateandCalculate('#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_txtNum1' as parameter.

 

2. JavaScript Section

Basic structure of JavaScript should be as following

Type of Functions from formWidget JavaScript Section.

  • User can basically add  two types functions as following.  
    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^='sum']").each(function () { . . . .});
      • In this function type must be formWidget type mentioned in the html section in this example we have mentioned formWidget type as ‘sum’ so we are using same in function "…[type^='sum']"
      • We can get the formWidget object by Using   $(this), once we get the object we can use it for further operations

 

  1. Event Handler Function -  
    • Add any valid function which can be called from html controls as shown in above code highlighted in blue box
    • 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


<!--sum UI Start-->

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

         <div>

             <div>

            <label id="formWidget_lblheader" class="formwidget-label">Sum</label>

             </div>

             <div>

            <div class="side-by-side">

                <input type="text" id="formWidget_txtNum1" class="formwidget-text input-mini" onchange="ValidateandCalculate('#formWidget_form')" /> + <br />

                <label id="formWidget_lblNum2" class="formwidget-sub-label">Number1</label>

            </div>

            <div class="side-by-side">

                <input type="text" id="formWidget_txtNum2" class="formwidget-text input-mini" onchange="ValidateandCalculate('#formWidget_form')" /> = <br />

                <label id="formWidget_lblNum2" class="formwidget-sub-label">Number2</label>

            </div>

            <div class="side-by-side">

                <input type="text" id="formWidget_txtTotal" class="formwidget-text input-mini" onchange="ValidateandCalculate('#formWidget_form')" /> <br />

                <label id="formWidget_lblTotal" class="formwidget-sub-label">Total</label>

            </div>

             </div>

             <div>

            <label id="formWidget_lblErrorMsg" class="failure"></label>

             </div>

         </div>

 

</formWidget>

<!--sum UI End-->

<!--sum JS Start -->

<script>

         $(function () {

             $("formWidget[type^='sum']").each(function () {

            var sFormWidget = $(this).attr('id');

            var sSumCtlrID = sFormWidget.substring(0, sFormWidget.length - 4);

 

            var Num1 = '#' + sSumCtlrID + 'txtNum1';

            var Num2 = '#' + sSumCtlrID + 'txtNum2';

            var Total = '#' + sSumCtlrID + 'txtTotal';

 

            $(Num1).val() == "" ? $(Num1).val("0") : $(Num1).val($(Num1).val());

            $(Num2).val() == "" ? $(Num2).val("0") : $(Num2).val($(Num2).val());

            $(Total).val() == "" ? $(Total).val("0") : $(Total).val($(Total).val());

             });

         });

 

         function ValidateandCalculate(WidgetID) {

             sWidgetID = $(WidgetID).attr('id');

             var sSumCtlrID = sWidgetID.substring(0, sWidgetID.length - 4);

             var Num1 = $('#' + sSumCtlrID + 'txtNum1').val();

             var Num2 = $('#' + sSumCtlrID + 'txtNum2').val();

             var Total = '#' + sSumCtlrID + 'txtTotal';

             var errorMsg = '#' + sSumCtlrID + 'lblErrorMsg';

             if ($.isNumeric(Num1) && $.isNumeric(Num2)) {

            $(Total).val(parseInt(Num1) + parseInt(Num2));

             } else {

            $(errorMsg).text('Please Enter a valid number ').fadeIn(50).fadeOut(3000);

             }

         }

</script>

<!--sum JS End -->



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

 

 

3. 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 “sum”.

 

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

Add a reference to FlowWright, 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. Since this Widget will not have any server side operations, it will return empty object of “clsFormWidgetReturn”.

 

 

Add data annotation attribute “formWidgetData” to the class “clsSum”, so that FlowWright is able to auto configure the Form Widget.“formWidgetdata” data annotation have 4 default parameters ,they are as following

  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 “sum”. 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 forms 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: “sum.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”.

 

 

4. 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 “sum”. Copy the file to the following directory “C:\inetpub\wwwroot\cDevWorkflow\images\FormWidgets”.

 

 

5. Configure Form Widget

Navigate to the FlowWright Configuration Manager and select “Form Widgets” menu item. Select “UtilsAuto Detect” menu item.


Select the form widget from table and select “ManageConfigure” menu item. The form widget will be automatically configured within FlowWright.

Once the form widget is successfully configured, Select “UtilsUpdate Master Scripts” menu item as shown below.

Navigate to the FlowWright Configuration Manager and select the “Forms” menu item.  Select “ActionsCreate” menu item.

Enter a name for the form defintion, and click the “Create” button.

Once the forms designer is displayed, search for “sum” form widget within the toolbox.  Click and drag the “Sum” form widget on to the forms designer as shown below:

 

 

Let’s test the form widget control, save the form widget and select “UIPreview” menu item to render for the form:

 

 

Once its rendered, enter numeric values for “Number 1 and 2” textboxes, it should display the sum of the 2 numbers within the “Total” textbox.