Web Form Development: Simple Mode

Overview

Simple mode is designed to make web form development easy, and provides the following advantages:

• Requires zero lines of code-behind.

• Everything can be done in design mode.

• All of the supported fields are automatically bound in two directions: from WorkflowGen to the web form and from the web form to WorkflowGen.

• No dataset needs to be created; only the desired fields have to be dragged and dropped and well-named in the web form designer.

Creating the web application

Suggested development tools

• Visual Web Developer Express 2013 or later

• Visual Studio Community or Professional 2013 or later

Web form installation directory

We strongly suggest that you store all of your web forms in the \wfgen\wfapps\webforms directory (e.g.\wfgen\wfapps\webforms\MyWebForm).

Be aware that if you modify your WorkflowGen process and you need to modify the associated MyWebForm because of those changes, you should duplicate MyWebForm beforehand, then create another IIS application. Otherwise, the two versions of the process will use the same modified MyWebForm.

Create the application in IIS

The web form application must be declared as an application in IIS in order to be recognized as a .NET web form application. Follow these instructions to declare your web form directory as an IIS application:

For IIS 7 or later

1. Open IIS Manager.

2. Navigate to your web form's location, which should be located in the Default Web Site node under \wfgen\wfapps\webforms\MyWebForm.

3. Right-click on MyWebForm and choose Convert to Application.

4. Select the application pool used by your site and another specific application pool.

5. Click OK.

Creating the project with Visual Studio

Create the project

1. Open Visual Studio and select File > New Web Site.

2. Choose ASP.NET Web Site.

3. Choose File system in the Location drop-down list.

4. Click Browse, then choose the location of your ASP.NET website.

5. Click OK.

Obtaining detailed error messages

By default, you will have no web.config file in your web project if you are using C# as your development language in the Microsoft Visual Studio IDE. In order to see complete error messages when you want to debug, you must have a web.config file. To add a default web.config file to your project, do the following:

1. Right-click on your project name, then click Add new item...

2. Choose Web configuration file, then click OK.

In order to be able to see complete error messages, change the following properties in the web.config file:

1. Make sure this line is set to "true":

   <compilation debug="true" />

2. Make sure this is not commented and that mode="Off":

   <customErrors mode="Off" defaultRedirect="GenericErrorPage.htm">
       <error statusCode="403" redirect="NoAccess.htm" />
       <error statusCode="404" redirect="FileNotFound.htm" />
   </customErrors>

Basic implementation

Reference

You must add a reference to WorkflowGen.My.dll in your web project and then add this instruction to the beginning of your web form:

using WorkflowGen.My.Web.UI.WebForms;

Class inheritance

Your web form should inherit from the WorkflowPage class contained within the WorfklowGen.My.Web.UI.WebForms namespace:

public partial class Form : WorkflowPage

Submitting to workflow using the SubmitButton

The submission of the web form to WorkflowGen is done by simply adding any type of button to your web form with the ID SubmitButton.

You can only have one SubmitButton in your entire web form. If you want more than one submit button (e.g. for a draft submit button), then you can use the SubmitToWorkflow() method in the Click event of your additional buttons.

The submit button type can be any of the following web controls : Button, LinkButton, or ImageButton.

Field management

Overview

The different fields that you drag and drop into your web form must have their IDs exactly the same as the WorkflowGen parameter names in your actions in order to be automatically bound with the IN or INOUT values.

Supported web controls

The following web controls can be used in simple mode and are bound automatically:

• TextBox

• Label

• RadioButton

• RadioButtonList

• CheckBox

• CheckBoxList

• DropDownList

• ListBox (single or multiple selection mode)

• FileUpload

• HtmlInputFile

• GridView

Field data type

The type of data to be put in the textboxes should be specified in the source of your web form. If you want a certain textbox to contain a date, for example, you should specify the FieldDataType extended attribute as Date. To do this, go to the source of your web form by clicking Source (next to Design) at the bottom of the web form.

The following is an example of the code that should be added to a TextBox in order to contain a Date value:

<asp:TextBox FieldDataType="Date" ID="TEXT_BOX_DATE" runat="server"> </asp:TextBox>

The following formats are supported:

• Date

• DateTime

• Time

• Numeric

• Currency

• Text (default value)

Date, DateTime, Time, Numeric, and Currency values will be automatically formatted using the user's current culture.

You don’t need to specify FieldDataType="Text" for string values.

FieldFormat for FieldDataType="DateTime"

If you specify the DateTime field data type on any textbox or label, you can also specify the FieldFormat attribute. This attribute is used to tell WorkflowPage how to format the date time for the current culture. For example, if you want to show the date in the format December 10, 2019 10:11:29 PM, you would declare the textbox as follows:

<asp:TextBox FieldDataType="DateTime" FieldFormat="{0:U}" ID="TEXT_BOX_DATE_TIME" runat="server"></asp:TextBox>

The following table provides a list of all the possible DateTime format strings:

String	Type	Example
{0:d}	Short date	10/12/2020
{0:D}	Long date	December 10, 2020
{0:t}	Short time	10:11 PM
{0:T}	Long time	10:11:29 PM
{0:f}	Full date & time	December 10, 2020 10:11 PM
{0:F}	Full date & time (long)	December 10, 2020 10:11:29 PM
{0:g}	Default date & time	10/12/2020 10:11 PM
{0:G}	Default date & time (long)	10/12/2020 10:11:29 PM
{0:M}	Month day pattern	December 10
{0:r}	RFC1123 date string	Thu, 10 Dec 2020 22:11:29 GMT
{0:s}	Sortable date string	2020-12-10T22:11:29
{0:u}	Universal sortable, local time	2020-12-10 22:13:50Z
{0:U}	Universal sortable, GMT	December 10, 2020 3:13:50 AM
{0:Y}	Year month pattern	December, 2020

TimeZoneConversion for FieldDataType="DateTime"

If you specify the DateTime field data type on any textbox or label, you can also specify the TimeZoneConversion attribute. This Boolean attribute is used to tell WorkflowPage to disable the user’s time zone conversion on the current web control.

The default value is True if this attribute is not declared in the web control’s definition. If this attribute is set to False, then the DateTime value is treated as a GMT/UTC DateTime value (without any conversions).

<asp:TextBox FieldDataType="DateTime" TimeZoneConversion="False" ID="TEXT_BOX_DATE_TIME" runat="server"></asp:TextBox>

This is available since WorkflowGen.My version 2.2.3.

FieldDataBind for asp:Label control

This attribute is used to enable or disable automatic data binding between a label control and its associated form data field.

The default value is True if this attribute is not declared in the Label control’s definition. If this attribute is set to False then the Label control will not data bind to the associated form data field.

<asp:Label FieldDataBind="False" ID="MY_LABEL_NOT_BIND" runat="server"></asp:Label>

This is available as of WorkflowGen.My version 2.1.8.

Field validation management

See Field validation management in the Advanced mode section.

Read-only fields

See Read-only fields in the Advanced mode section.

Field colorization management

See Field colorization management in the Advanced mode section.

Form archive management

See Form archive management in the Advanced mode section.

File attachment management

If you add a FileUpload or an HtmlInputFile control to your web form, the file will automatically be saved and the WorkflowGen process data that is associated with this control ID will automatically be updated with the reference to the uploaded file upon form submission.

Resource management

See Resource management in the Advanced mode section.

GridView management

Overview

This section explains how to use a GridView (with some limitations) in Simple mode.

Limitations

• Only BoundFields, CheckBoxFields, CommandFields, and TemplateFields are supported.

• Sorting and paging cannot be used.

Designing the GridView

1. Drag and drop a GridView into the web form.

2. Click Edit columns.

3. Uncheck Auto-generate fields, since you'll choose which fields you want in the GridView and no DataSource will be used.

4. Add BoundFields and CheckBoxFields as needed. The important property to set for each of these fields is DataField, for which you can specify anything you want, as long as there are no special characters or spaces within this name.

5. If you want your field to be any date/time format or any numeric format, you can do this by setting the HtmEncode attribute to "False" and the DataFormatString attribute to the following possible values only:

📌 Date/time formats and examples using the en-US culture

String	Example
{0:d}	3/3/2020
{0:D}	Tuesday, March 03, 2020
{0:g}	3/3/2020 12:00 AM
{0:g}	3/3/2020 12:00:00 AM
{0:t}	12:00 AM
{0:T}	12:00:00 AM
{0:f}	Tuesday, March 03, 2020 12:00 AM
{0:M}	March 03
{0:s}	2020-03-03T00:00:00
{0:u}	2020-03-03 00:00:00Z
{0:U}	Tuesday, March 03, 2020 12:00:00 AM
{0:Y}	March, 2020

📌 Numeric formats and examples using the en-US culture

String	Example
{0:C}	$200.00
{0:N} or {0:F}	200.00
{0:P}	20.00 %
{0:R}	200

We recommend changing ApplyFormatInEditMode to "true" if you use any of these formats in your fields. This property applies the desired formatting to the data even when the end-user is editing the data.

If you use any of these formats, the field will automatically be validated for a valid date/time or numeric format when updating the row. If invalid, an error message will be thrown to the end-user using the column header text to tell them that this particular field is not in the correct format and that they must correct it.

The default error message for invalid dates in GridViews is You have entered an invalid date in the {0} column, where {0} represents the column header text. You can specify your own message by overriding the InvalidDateGridViewErrorMessage property value in your web form's Page_Load method.

The default error message for invalid numeric values in GridViews is You have entered an invalid number in the {0} column, where {0} represents the column header text. You can specify your own message by overriding the InvalidNumberGridViewErrorMessage property value in your web form's Page_Load method.

The formatting uses the user's current culture.

Enabling insertion, editing, and deletion in the GridView

To enable insertion, editing, and deletion in the GridView, do the following:

1. Add a CommandField to your GridView.

2. Set the CausesValidation property to "False"; otherwise, the Update button will trigger validation of all the fields in the page.

3. Set the ShowEditButton property to "True" if you want to enable insertion and editing.

4. Set the "ShowDeleteButton" property to "True" if you want to enable deletion in the GridView.

Form data

A DataTable node will automatically be added by WorkflowPage in your FORM_DATA DataSet. The name of this table will be the ID of your GridView and each BoundField and CheckBoxField will have its DataColumn automatically created in this table with the DataField as the column name. The DataType of the DataColumn will be determined by the DataFormatString used.

Making the GridView read-only or required

The GridView can be automatically set to read-only or required by using the FORM_FIELDS_READONLY and FORM_FIELDS_REQUIRED parameters of your WorkflowGen actions.

When a GridView is set to required, it forces the end-user to fill in and update at least one row. The default message The {0} list needs to have at least one filled row will be displayed to the user, where {0} will contain the GridView's tooltip, or its ID if no tooltip has been specified. You can change this message by modifying the WorkflowPage RequiredGridViewsErrorMessage property in the Page_Load of your web form.

When a GridView is set to read-only, it automatically hides the CommandField columns and an empty row is not automatically inserted in the GridView.

Making particular columns required in your GridView

You can use the FORM_FIELDS_REQUIRED parameter to set BoundFields or TemplateFields to required in your GridView with the following syntax:

GRIDVIEW_ID.DATAFIELDNAME

You cannot use the * (asterisk) or ^ (caret) characters for these particular fields; instead, you must specify the GridView ID and the data field name for each field you want set to required.

The fields of the required columns will automatically be colorized according to your FieldsColorization property value when you are in edit mode.

The default error message shown to the end-user is The {0} column is required. This message can be modified by changing the RequiredColumnsInGridViewsErrorMessage property.

Using TemplateFields in your GridView

You can use TemplateFields in your GridViews. The IDs of the web controls you use in your template fields will be used as the field names in your form data. Be sure to have the same IDs in your ItemTemplate and in your EditItemTemplate, or else the data won’t be consistent when you switch between edit and listing modes.

The next thing you need to do is to set the web controls' values using the Bind expression according to the example below.

You can also use the FieldDataType attribute on your web controls inserted in your template fields, but make sure to set the same FieldDataType in the ItemTemplate and the EditItemTemplate, or else the data won’t be formatted as you would expect it to be.

You can also use any type of validator in your template fields to validate user input (RangeValidator, RequiredFieldValidator, RegularExpressionValidator, CustomValidator, etc.), the only constraint being that you must set the EnableClientScript property to "False" in all of the validators you use in the template fields.

Here's a simple example of a TemplateField that uses a DropDownList and a RequiredFieldValidator :

<asp:TemplateField HeaderText="Gender">
    <EditItemTemplate>
        <asp:DropDownList ID="Gender" runat="server" SelectedValue='<%# Bind("Gender") %>'>
            <asp:ListItem Selected="True"></asp:ListItem>
            <asp:ListItem>Male</asp:ListItem>
            <asp:ListItem>Female</asp:ListItem>
        </asp:DropDownList>
        <asp:RequiredFieldValidator ID="GenderValidator" runat="server" ControlToValidate="Gender" Display="Dynamic" ErrorMessage="The gender is required" SetFocusOnError="True" EnableClientScript="False">                                    
        </asp:RequiredFieldValidator>
    </EditItemTemplate>
    <ItemTemplate>
        <asp:Label ID="Gender" runat="server" Text='<%# Bind("Gender") %>'></asp:Label>
    </ItemTemplate>
</asp:TemplateField>

Filling your GridView with an external data source for initialization

If you want to fill a GridView with an external data source, you'll have to write some code. The basic steps to do this are as follows:

1. Fill your FormData using the FillFormData(FormData) method.

2. Get your external data into a DataSet.

3. For each row of the resulting DataTable, create a clone of the row and insert this row at the beginning of your GridView's associated DataTable (the DataTable name in your FormData is always the ID of your GridView).

4. Save your FormData using the SaveFormData(FormData) method.

5. If the GridView is not in ReadOnly mode, set the edit index of your GridView to the last row.

6. Rebind your GridView.

Here's a simple example filling a GridView whose ID is PeopleList with some first names and last names of a SQL DataSource:

// 1. Fill your `FormData` using the `FillFormData(FormData)` method.
            FillFormData(FormData);         

// 2. Get your external data into a DataSetSqlDataSourceSample.SelectCommand = "SELECT FIRST_NAME, LAST_NAME FROM PEOPLE_LIST";

      DataSet myData = new DataSet();
      SqlDataAdapter adapter = new
SqlDataAdapter(SqlDataSourceSample.SelectCommand,
   SqlDataSourceSample.ConnectionString);
      adapter.Fill(myData, "PEOPLE_LIST");

// 3. For each row of the resulting DataTable, create a clone of the row and insert this
//    row at the beginning of your GridView associated DataTable
            foreach (DataRow row in myData.Tables["PEOPLE_LIST"].Rows)
            {

                DataRow rowToAdd = FormData.Tables["PEOPLE_LIST"].NewRow();
                rowToAdd["FirstName"] = row["FIRST_NAME"];
                rowToAdd["LastName"] = row["LAST_NAME"];

                FormData.Tables["PeopleList"].Rows.InsertAt(rowToAdd, 0);
            }

// 4. Save your FormData using the “SaveFormData(FormData)” method           
SaveFormData(FormData);

// 5. If the GridView is not in ReadOnly mode, set the edit index of your GridView to the last row
PeopleList.EditIndex = FormData.Tables["PeopleList"].Rows.Count - 1;

// 6. Rebind the GridView
PeopleList.DataBind();

Creating an advanced GridView in Simple mode

If you want to manage your GridView without using Simple mode, you can follow the steps in the Advanced mode GridView management section.

In order to put your GridView data into the FormData managed by Simple mode, you need to insert your GridView's associated DataTable into the WorkflowPage FormData dataset in your Page_Load method.

After implementing the example above, you'll have to put the following code into your Page_Load method:

// Add the people list datatable if it is not in the simple mode FormData already
if (!FormData.Tables.Contains(peopleListDataTable.TableName))
{

// Add the peopleList table in the simple mode FormData
FormData.Tables.Add(peopleListDataTable);

  // Refill the form data
  FillFormData(FormData);
}

Using web UserControls in web forms

See Using web UserControls in web forms in the Advanced mode section.

Using custom controls

When working on workflow-enabled web forms, developers are often asked to implement parts of web forms that could have been already used in other web forms.

Sometimes, the developer spends a considerable amount of time just to reproduce and adapt existing code from an existing web form to another. Custom controls are the solution to such problems.

A custom control can be defined as a composite control composed of regular controls and embedding some business logic.

Simple examples of custom controls could be approval zone or advanced upload control. Visual Studio allows the user to insert this kind of control by a simple drag-and-drop from the toolbar.

Installing custom controls in Visual Studio

Custom controls must be installed in the Visual Studio development environment. The developer only needs to run an installation assistant embedded in a VSI file (Visual Studio Installer with the .vsi extension).

VSI packs work in all versions of Visual Studio.

We recommend closing Visual studio before starting any VSI installation. Then, double-click on your .vsi file to proceed to the custom control installation assistant. During the installation, you will be asked to trust the component; answer YES.

Once installed, custom controls are available in the Visual Studio toolbox.

Using custom controls with web forms

Developers that have installed a custom control should be able to drag and drop it onto the web form while in Design view. Visual Studio then adds any required references to the assembly of the custom control being inserted to the project. Visual Studio copies the assembly into the \bin directory of your application from the common Visual Studio settings storage path.

If the control assembly is not found, the Visual Studio designer will display a rendering error on your control.

You can then adjust various control settings (such as dimensions, style, and other specific properties) by changing property values in the Properties window.