Frequently Asked Questions

What is XField Suite?
Who is XField Suite for?
What platform or framework does XField Suite require?
What browsers does XField Suite support?
What is field control?
What is special about XField Suite in contrast to the products of other vendors?
How to install XField Suite to my Web site or Web application?
How to perform pre-defined data validation on a field control?
How to perform custom validation on a field control?
How does the server-side validation work in XField Suite?
What validations does each field control support and what is their order of execution?
Do I need to include any resources such as JavaScript, CSS or images to support XField Suite?
What JavaScript library does XField Suite use and how can I manage it?
How to manage the layout and look and feel of the field controls on a page?
Is XField Suite compatible with the UpdatePanel of ASP.NET Ajax framework?
How to apply localization to XField Suite?
How to change the styles of the calendar popup in Date Field and Date-Time Field?
How to set the date format of Date Field and Date-Time Field?
What's the difference between Time Text Field and Time List Field?
How to choose single-select field?
How to choose multi-select field?
How do LDS Single-Select List and LDS Multi-Select List handle very long list and how to ensure their responsiveness?
How to speed up the initialization of locally auto-suggestable fields?
How to manage the styles of auto-suggestable single-select and multi-select fields?
What's the difference between Number Field and Numeric Field?
How to filter out or reject certain types of characters in Text Field?
What keyboard interface does auto-suggest support?
How to display tooltip for a field?

What is XField Suite?

XField Suite is a package of multiple creative data entry ASP.NET Web controls which implements the concept of field control. Field control encapsulates label, data entry elements and validators into a single control to help developers maximize their productivity when developing data entry Web form.


Go to top
Who is XField Suite for?

XField Suite is for ASP.NET Web development teams and ASP.NET Web developers to build professional and highly interactive data entry Web forms.


Go to top
What platform or framework does XField Suite require?

XField Suite requires ASP.NET 2.0 and above.


Go to top
What browsers does XField Suite support?
XField Suite has been fully tested on the following browsers: IE 8 and above
IE8+
Firefox
Firefox
Chrome
Chrome
Safari
Safari
Opera
Opera


Go to top
What is field control?

A field control is a composite ASP.NET Web control that is used to display or enter certain type of data. For instance, Numeric Field is used to display or enter numeric data; whereas Date Field is used to display or enter date/time value. Typically, a field control includes a label control, one or more data controls, a custom validator, a graphical validation result holder and a validation error message holder. The following diagram illustrates the structure and functionality of each part of a field control.

Field Control
Label: to hold the field label.

Data Control(s): to hold the field data

Custom Validator(Invisible): to perform validations that are relevant to the field type.

Graphical Validation Result Holder: to hold the graphical validation result.

Validation Error Message Holder: to hold the textual validation error message


Go to top
What is special about XField Suite in contrast to the products of other vendors?

Simplicity is the primary focus of XField Suite. All data entry components in XField Suite are built around a core concept - Field Control. A Field Control usually represents a specific data type such as numeric value or date-time value on UI and is self contained with multiple data entry functionalities. Here's a features highlight of XField Suite:

  • Validations:  built-in client and server validations and extensible with custom validation
  • Auto-Suggest:  avaiable in textbox, drop down list, drop down tree and tree view
  • Multi-Select:  auto-suggestable drop down checkbox list and checkbox tree
  • Easy Date & Time Entry:  supports auto-suggest and accepts many date & time formats
  • Rich ToolTip:  supports HTML contents and auto-positioning
  • Rich Validation Result:  supports graphical, textual or even custom validation result style
  • Auto Field Label:  simply declare the label of a field
  • Easy Fields Layout & Styles Management:  supported through the Field Panel control
  • Declarative Syntax:  simply declare what you want and let the component figure out how to do it

These features bring the following benefits:

  • Unparalleled data entry user experiences on Web
  • Significantly reduced development time and cost
  • Free developers to focus more on business problems
  • Greatly simplified development of dynamic (meta data driven) data entry screens
  • Write your application once & have it run anywhere, on web, mobile & tablets

Go to top
How to install XField Suite to my Web site or Web application?

To install XField Suite to your Web site or Web application:

  • If file "XndSysInc.XField.dll" and "XndSysInc.XField.xml" exist in the "Bin" folder of your Web site or Web application, back them up first.
  • Unzip the downloaded *.zip file to a folder on your computer.
  • Copy file "XndSysInc.XField.dll" and "XndSysInc.XField.xml" from the folder containing the unzipped files to the "Bin" folder of your Web site or Web application. Replace any file with the same name when prompted.
  • If you're building a Web application, add references to file "XndSysInc.XField.dll" in your application's "Bin" folder from Visual Studio. If you're building a Web site, skip this step.
  • In Visual Studio, make sure the "App_Data" folder exists in your Web site or Web application.
  • Backup the contents in the "App_Data" folder if it already exists.
  • Copy file "XndSysInc.XField.lic" from the folder containing the unzipped files to the "App_Data" folder mentioned above. Replace any file with the same name when prompted.
  • Add XField Suite in the "web.config" file located at the root folder of your Web site or Web application as follows:
    <system.web>
      <pages>
        <controls>
          <add tagPrefix="xfd" namespace="XndSysInc.XField.Controls" assembly="XndSysInc.XField"/>
        </controls>
      </pages>
    </system.web>
Go to top
How to perform pre-defined data validation on a field control?

A field control can be configured to have zero to multiple pre-defined validations enabled. The validations can be configured either declaratively by server-side markup through the inner properties of a field control or programmatically by code. Each field control supports pre-defined validations that are relevant to the type of data it holds. If enabled, a pre-defined validation will be executed at both client-side and server-side.

The following markup and code snippet demonstrate how validation can be configured for a field control:

<xfd:DateField ID="fldDateOfBirth" runat="server" Label="Date of Birth">
  <NotNullValidation Enabled="true" ErrorMessage="Please enter Date of Birth." />
  <DataFormatValidation ErrorMessage="Invalid date" />
  <RelativeRangeValidation Enabled="true" LowerBound="-35" UpperBound="-18"
    ErrorMessage="Are you between 18 and 35?" />
</xfd:DateField>

<script type="text/C#" runat="server">
  fldDateOfBirth.NotNullValidation.Enabled = true;
  fldDateOfBirth.NotNullValidation.ErrorMessage = "Please enter Date of Birth.";
  fldDateOfBirth.DataFormatValidation.ErrorMessage = "Invalid date";
  fldDateOfBirth.RelativeRangeValidation.Enabled = true;
  fldDateOfBirth.RelativeRangeValidation.LowerBound = -35;
  fldDateOfBirth.RelativeRangeValidation.UpperBound = -18;
  fldDateOfBirth.RelativeRangeValidation.ErrorMessage = "Are you between 18 and 35?";
</script>


Go to top
How to perform custom validation on a field control?

All field controls in XField Suite use the same mechanisim to allow you to plug-in your custom validation logic. Here's how you can do this in general:

  • To assign validation error message, use the "CustomValidation.ErrorMessage" property.
  • To setup client-side custom validation, use the "CustomValidation.ClientValidator" property.
  • To setup server-side custom validation, handle the server-side CustomValidate event.

For demos and sample code, visit the individual field control page through the navigation menu at the top of the page.


Go to top
How does the server-side validation work in XField Suite?

The server-side validation in XField Suite works the same way as the standard ASP.NET validation control does. When the page is posted back, you can determine whether all field controls in the page pass the validation or not by simply checking whether the "Page.IsValid" property equals to true. Here's an example:

protected void btnSubmit_Click(object sender, EventArgs e)
{
  if (Page.IsValid)
  {
    // All field controls passed the validation.
    // TODO: place your normal postback logic here.
  }
  else
  {
    // Some field control(s) didn't pass the validation.
    // Do nothing here since the field controls will display
    // the validation result automatically. Note that in real
    // world application the entire else block can be omitted.
    // We placed some comments here simply for illustration purpose.
  }
}


Go to top
What validations does each field control support and what is their order of execution?

The following table indicates the types of validation that each field control supports. For each field control, its supported validations are executed from left to right as listed in the table.

Execution Order: left to right
  Not null validation Text length validation Regular expression validation Data format validation Compare to value validation Compare to control validation Range validation Relative Range Validation Selected items count validation Custom validation
Boolean Field         supported supported       supported
Credit Card Field
CVV Code Field
Email Address Filed
Number Field
supported     supported supported supported       supported
Date Field supported     supported supported supported supported supported   supported
Date-Time Field
Numeric Field
Time Text Field
Time List Field
supported     supported supported supported supported     supported
Gross Date Field supported     supported supported supported supported     supported
List Field
Radio Field
LDS Single-Select List
LDS Single-Select Tree
RDS Single-Select List
RDS Single-Select Tree
supported   supported   supported supported       supported
Checklist Field
LDS Multi-Select List
LDS Multi-Select Tree
RDS Multi-Select List
RDS Multi-Select Tree
supported               supported supported
Description Field
Text Field
supported supported supported   supported supported       supported


Go to top
Do I need to include any resources such as JavaScript, CSS or images to support XField Suite?

No. XField Suite includes all resources it needs automatically.


Go to top
What JavaScript library does XField Suite use and how can I manage it?

XField Suite uses jQuery 1.3.2 to help it perform client-side functionality. When one or more field controls are used on a page, one copy of jQuery 1.3.2 will be automatically injected as script include file in the head section of the page.

If you need to include jQuery explicitly on your page rather than letting XField Suite include it automatically for you, you can achieve this by using the XField Suite's Script Manager control. The sole purpose of the Script Manager is to allow user to prevent XField Suite from including the jQuery library so that user can include it explicitly by themselves.

See Script Manager demo for details of how to use Script Manager.


Go to top
How to manage the layout and look and feel of the field controls on a page?

Field control exposes properties to allow you to manage its layout as well its look and feel. More importantly, you can also use Field Panel to manage most of these properties globally. A field control can either inherit or override the field manangement settings of its containing Field Panel.

The following table lists the properties that each field control exposes to allow you manage its layout as well as its look and feel.

Property Name Property Type Applies To Default Value Inheritable from Field Panel Description
DataCssClass System.String Field Control "" No Gets or sets the CSS class of data controls.
DataCssClassOnError System.String "" Yes Gets or sets the CSS class to be applied to data controls when validation error occurs.
EnableGraphicalResult DefaultableBoolean Default (true or inherit) Yes Gets or sets a value indicating whether a graphical hint should be displayed to indicate the validation result.
ErrorCssClass System.String "" Yes Gets or sets the CSS class of the error message control.
ErrorInNewLine DefaultableBoolean Default (false or inherit) Yes Gets or sets a value indicating whether the validation error message should be rendered in new line.
InvalidImageUrl System.String "" Yes Gets or sets the location of the image to be displayed when the field data fails validation. This property allows client to display a custom image when the field data fails validation. This property only takes effect when property EnableGraphicalResult is set to true.
LabelCssClass System.String "" Yes Gets or sets the CSS class of the label.
LabelCssClassOnError System.String "" Yes Gets or sets the CSS class to be applied to the label when validation error occurs.
ValidImageUrl System.String "" Yes Gets or sets the location of a image to be displayed when the field data passes validation. This property allows client to display a custom image when the field data passes validation. This property only takes effect when property EnableGraphicalResult is set to true.
DataInNewLine DefaultableBoolean Nullable Field Default (false or inherit) Yes Gets or sets a value indicating if data controls should be rendered in new line.
FixedLabelWidth DefaultableBoolean Default (false or inherit) Yes Gets or sets a value indicating whether the width of the label should be fixed and based on LabelWidth property.
LabelAlignRight DefaultableBoolean Default (false or inherit) Yes Gets or sets a value indicating whether the label text should be aligned to right.
LabelWidth System.Web.UI.WebControls.Unit Unit.Empty Yes Gets or sets the width of the label. This property only takes effect when property FixedLabelWidth is set to true and property DataInNewLine is set to false.
NotNullSymbolColor System.String "" Yes Gets or sets the color (e.g., #D8D8D8 or red) of the not null symbol.


Go to top
Is XField Suite compatible with the UpdatePanel of ASP.NET Ajax framework?

Yes, XField Suite is fully compatible with the UpdatePanel control that comes with ASP.NET Ajax framework. You can safely place any field control of XField Suite inside the UpdatePanel.


Go to top
How to apply localization to XField Suite?

For all field controls except the Date Field, you can use the standard ASP.NET localization mechanism to localize them. Check the following MSDN document for details: Localizing ASP.NET Web Pages By Using Resources

For the Date Field, in addition to the standard ASP.NET localization mechanism, the Date Field also exposes the "CalendarLanguage" property to help you localize the calendar popup. Currently, the calendar popup supports 46 languages.


Go to top
How to change the styles of the calendar popup in Date Field and Date-Time Field?

Use the "CalendarIcon" and "CalendarStyle" property.


Go to top
How to set the date format of Date Field and Date-Time Field?

Use the "DateFormat" and "DatePartsDelimiter" property.


Go to top
What's the difference between Time Text Field and Time List Field?

Both Time Text Field and Time List Field are for time-of-day value input and display. They both have the auto-suggest capability and support the same set of validations.

Time Text Field does not limit user input to its auto-suggest. Time List Field limits user input to its auto-suggest.


Go to top
How to choose single-select field?

Use the following table to choose single-select fields.

Single-Select Field Usage Auto-Suggest Type Auto-Suggest Responsiveness Initial Page Load Time Applicable Data Size Requires Custom Coding
List Field Select single item from a non-auto-suggestable drop down list. None N/A Medium Small No
Radio Field Select single item from a radio buttons list. N/A N/A Short Small No
LDS Single-Select List Select single item from a locally auto-suggestable drop down list. Local (non-ajaxed) Fast Long Medium No
LDS Single-Select Tree Select single item from a locally auto-suggestable drop down Tree. Local (non-ajaxed) Fast Long Medium No
RDS Single-Select List Select single item from a remotely (ajaxed) auto-suggestable drop down list. Remote (ajaxed) Slow Short Large Yes
RDS Single-Select Tree Select single item from a remotely (ajaxed) auto-suggestable drop down tree. Remote (ajaxed) Slow Short Large Yes


Go to top
How to choose multi-select field?

Use the following table to choose multi-select field.

Multi-Select Field Usage Auto-Suggest Type Auto-Suggest Responsiveness Initial Page Load Time Applicable Data Size Requires Custom Coding
Checklist Field Select multiple items from an always visible checkboxes list. N/A N/A Short Small No
LDS Multi-Select List Select multiple items from a locally auto-suggestable drop down list. Local (non-ajaxed) Fast Long Medium No
LDS Multi-Select Tree Select multiple items from a locally auto-suggestable drop down tree. Local (non-ajaxed) Fast Long Medium No
RDS Multi-Select List Select multiple items from a remotely (ajaxed) auto-suggestable drop down list. Remote (ajaxed) Slow Short Large Yes
RDS Multi-Select Tree Select multiple items from a remotely (ajaxed) auto-suggestable drop down tree. Remote (ajaxed) Slow Short Large Yes


Go to top
How do LDS Single-Select List and LDS Multi-Select List handle very long list and how to ensure their responsiveness?

LDS Single-Select List and LDS Multi-Select List use pagination to ensure their responsiveness when handling very long list. Specifically, the AutoSuggest.MaxRows property defines the maximum number of items the auto-suggest can hold. When the number of items contained in the search result exceeds this limit, a page navigation bar automatically appears to allow easy page navigation. By default, the AutoSuggest.MaxRows property is set to 1000. If your list is very long, for example contains thousands of items, you can ensure the responsiveness by setting the AutoSuggest.MaxRows property to a lower value such as 100. Also note that the AutoSuggest.MaxRows property should not be smaller than the AutoSuggest.MaxVisibleRows (default to 20) property.


Go to top
How to speed up the initialization of locally auto-suggestable fields?

Locally auto-suggestable fields (e.g., LDS Single-Select List, LDS Multi-Select Lists and Text Field) by default automatically infer the width of the auto-suggest and selected items holder (in case of LDS Multi-Select List) by measuring each list item during initialization. This can be very time consuming if the list is rather long. To speed up the initialization, explicitly set the width of the auto-suggest and selected items holder (if applicable) to prevent the initialization process from measuring each list item. Use the following properties to achieve this: AutoSuggest.Width and SelectedItemsHolder.Width.



Go to top
How to manage the styles of auto-suggestable single-select and multi-select fields?

Use the following table to manage the styles of single-select and multi-select fields.

Field Type Field Name Manage Styles
Single-Select LDS Single-Select List See details
LDS Single-Select Tree See details
RDS Single-Select List See details
RDS Single-Select Tree See details
Multi-Select LDS Multi-Select List See details
LDS Multi-Select Tree See details
RDS Multi-Select List See details
RDS Multi-Select Tree See details


Go to top
What's the difference between Number Field and Numeric Field?

Number Field only accepts number as its input but at server-side the data is treated as text. Number Field can be used to display and enter any textual data that contains number only.

Numeric Field accepts numeric data as its input and at server-side the data is treated as decimal value. In another word, fractional numeric value (numeric value with decimal places) is accepted as its input. Numeric Field can be used to display and enter any numeric value that may contain decimal places such as monetary value.


Go to top
How to filter out or reject certain types of characters in Text Field?

Text Field exposes the "CharFilterRegex" property to allow user to filter out or reject certain types of characters at client-side by using JavaScript's regular expression. Here are some examples:

  • To accept number only: CharFilterRegex = "/^[0-9]$/"
  • To accept alpha-numeric characters only: CharFilterRegex = "/^[a-zA-Z0-9]$/"

Go to top
What keyboard interface does auto-suggest support?

The auto-suggest supports the following keyboard interface:

  Enter Tab Up Arrow
Down Arrow
Page Up
Page Down
Left Arrow
Right Arrow
Esc
LDS Single-Select List
RDS Single-Select List
Text Box Field
Select the highlighted item in the auto-suggest. Select the highlighted item in the auto-suggest and move focus to the next tab stop. Move the highlight in the auto-suggest up or down by one item. If the auto-suggest can hold all search result, move the highlight in the auto-suggest up or down by the number of items specified by the AutoSuggest.MaxVisibleRows property; otherwise navigate to the previous or next page of the search result. N/A Close the auto-suggest if it is visible.
LDS Multi-Select List
RDS Multi-Select List
Toggle the selection of the highlighted item in the auto-suggest. Close the auto-suggest if it is visible and move focus to the next tab stop. Move the highlight in the auto-suggest up or down by one item. If the auto-suggest can hold all search result, move the highlight in the auto-suggest up or down by the number of items specified by the AutoSuggest.MaxVisibleRows property; otherwise navigate to the previous or next page of the search result. N/A Close the auto-suggest if it is visible.
LDS Single-Select Tree
RDS Single-Select Tree
Select the highlighted item in the auto-suggest. Select the highlighted item in the auto-suggest and move focus to the next tab stop. Move the highlight in the auto-suggest up or down. N/A If possible, collapse or expand the highlighted node; otherwise move the highlight to the parent or the first child node. Close the auto-suggest if it is visible.
LDS Multi-Select Tree
RDS Multi-Select Tree
Toggle the selection of the highlighted node in the auto-suggest. Close the auto-suggest if it is visible and move focus to the next tab stop. Move the highlight in the auto-suggest up or down. N/A If possible, collapse or expand the highlighted node; otherwise move the highlight to the parent or the first child node. Close the auto-suggest if it is visible.

Go to top
How to display tooltip for a field?

See tooltip demo.

Each field control in XField Suite exposes the RichTip inner custom property to allow you to display rich tooltip to help user enter data. The RichTip property contains the following sub-properties for fine tuning the look and feel of the tooltip:

Property Name Property Type Default Value Description
Anchor ToolTipAnchor Auto Gets or sets the anchoring position of the tooltip. Anchor controls where on the tooltip target that the tooltip points to.
BackgroundColor ToolTipBackgroundColor Yellow Gets or sets the background color of the tooltip.
ContentHtml System.String "" Gets or sets the content HTML of the tooltip.
Enabled System.Boolean false Gets or sets a value indicating whether the containing FieldControl should enable the tooltip that is represented by this instance of ToolTipSettings.
FixPosition System.Boolean false Gets or sets a value indicating whether the tooltip's position should be fixed relative to the target it points to.
FontFamily System.String "Tahoma" Gets or sets the font family of the tooltip content (e.g. "Tahoma").
FontSize System.String "10pt" Gets or sets the font size of the tooltip content (e.g. "11pt").
FontWeight System.String "normal" Gets or sets the font weight of the tooltip content (e.g. "normal", "bold", "bolder").
ForeColor System.String "#000000" Gets or sets the text color of the tooltip (e.g. "#000000").
MaxWidth int 200 Gets or sets the maximum pixel width of the tooltip.
MouseOverDelay int 500 Gets or sets the number of milliseconds that the mouse cursor must hover over the triggering element before the tooltip is displayed. 0 represents no delay. If negative value is assigned, 0 is assumed.
OffsetX int 0 Gets or sets the number pixels the tooltip positions horizontally away from its desired anchoring point. Negative value - move leftward; positive value - move rightward; 0 - no move.
OffsetY int 0 Gets or sets the number pixels the tooltip positions vertically away from its desired anchoring point. Negative value - move upward; positive value - move downward; 0 - no move.
PaddingBottom int 5 Gets or sets the bottom padding in pixels.
PaddingLeft int 5 Gets or sets the left padding in pixels.
PaddingRight int 5 Gets or sets the right padding in pixels.
PaddingTop int 5 Gets or sets the top padding in pixels.
Shadow System.Boolean true Gets or sets a value to enable or disable the shadow effect of the tooltip. The shadow effect works only on browsers that support CSS3 styles.
Timeout int 0 Gets or sets the number of milliseconds that the tooltip remains visible sinces it is displayed but before it disappears automatically. 0 represents no timeout. If negative value is assigned, 0 is assumed.
Trigger ToolTipTrigger MouseOver Gets or sets the trigger of the tooltip.
Go to top