Frequently Asked Questions
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 |
Firefox |
Chrome |
Safari |
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?
XField Suite emphasizes on functionality encapsulation by leveraging the concept of
Field Control. A Field Control in XField Suite contains multiple data entry related
functionalities. Here is a highlight:
- Auto Label: automatically associate a label to a field by simply setting the Label property.
- Built-in Validations: declaratively configure pre-defined validations relevant to the field data type.
- Custom Validation: plug-in custom or even asynchronous validation logic.
- Rich Validation Result: graphical, textual or even custom validation result style.
- Interactive Auto-Complete Suggest List: tranforms all textbox fields into powerful searchable textbox.
- Mobile Device Awareness: interactive suggest list automatically adjusts on mobile devices for easy data entry.
- ToolTip: rich tooltip to help user enter data.
- Powerful Searchable Drop Down List: single-select (Dynamic List Field) and multi-select (Multi-Select List Field).
- Highly User Friendly Date Picker: supports both calendar and clearly guided manual entry.
- Intuitive and Easy to Use: one field for one data entry task - no "super" controls requiring tricky settings.
These features bring the following benefits:
- Unparalleled data entry user experiences on desktop and mobile devices.
- Timely delivery of professional data entry Web forms with rich behaviors.
- Quick response to frequently changing user requirements.
- Focusing more on solving business problem such as building the domain layer of your software system.
- Make it easy to build dynamic data entry Web form.
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:
- Unzip the downloaded *.zip file to a folder on your computer.
- Copy file "XNode.Web.XField.dll" and "XNode.Web.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 "XNode.Web.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 "XNode.Web.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="xfield"
namespace="XNode.Web.XField.Controls"
assembly="XNode.Web.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:
<xfield:DateField
ID="fldDateOfBirth"
runat="server"
Label="Date of Birth">
<NotNullValidation
Enabled="true"
Message="Please enter
Date of Birth." />
<DataFormatValidation
Message="Invalid date"
/>
<RelativeRangeValidation
Enabled="true"
LowerBound="-35"
UpperBound="-18"
Message="Are
you between 18 and 35?" />
</xfield:DateField>
<script
type="text/C#"
runat="server">
fldDateOfBirth.NotNullValidation.Enabled =
true;
fldDateOfBirth.NotNullValidation.Message =
"Please enter Date of Birth.";
fldDateOfBirth.DataFormatValidation.Message =
"Invalid date";
fldDateOfBirth.RelativeRangeValidation.Enabled =
true;
fldDateOfBirth.RelativeRangeValidation.LowerBound = -35;
fldDateOfBirth.RelativeRangeValidation.UpperBound = -18;
fldDateOfBirth.RelativeRangeValidation.Message =
"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.Message" 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, please visit the 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)
{
}
else
{
}
}
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: |
|
| |
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 |
|
|
|
|
 |
|
|
|
|
|
| Credit Card Field |
|
|
|
|
|
|
|
|
|
|
| CVV Code Field |
|
|
|
|
|
|
|
|
|
|
| Date Field |
|
|
|
|
|
|
|
|
|
|
| Description Field |
|
|
|
|
|
|
|
|
|
|
| Dynamic List Field |
|
|
|
|
|
|
|
|
|
|
| Email Address Filed |
|
|
|
|
|
|
|
|
|
|
| Gross Date Field |
|
|
|
|
|
|
|
|
|
|
| List Field |
|
|
|
|
|
|
|
|
|
|
| Multi-Select List Field |
|
|
|
|
|
|
|
|
|
|
| Number Field |
|
|
|
|
|
|
|
|
|
|
| Numeric Field |
|
|
|
|
|
|
|
|
|
|
| Text Field |
|
|
|
|
|
|
|
|
|
|
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.
For details of how to use XField Suite's Script Manager control, please
visit the Script Manager page.
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. Please 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?
Please use the "CalendarIcon" and "CalendarStyle" property in the Date Field to change the styles
of the calendar popup.
Go to top
How to hide the calendar popup in Date Field?
Please use the "HideCalendar" property in the Date Field to hide the calendar popup.
Go to top
How to change the order of the date elements (year, month, day) in Date Field?
Please use the "DateFormat" property in the Date Field to change the order of the date elements
(year, month, day).
Go to top
What's the difference between List Field and Dynamic List Field?
List Field uses ASP.NET DropDownList control (HTML select tag at client-side) to display
and accept data input - it doesn't have the auto-complete searching capability.
Dynamic List Field transforms an ASP.NET DropDownList control into a searchable drop down list.
When you type a charater in the search box, it uses auto-complete technique to find and display
the matching items to help you quickly spot the item you want to select.
Go to top
How to manage the styles of the suggest list in Dynamic List Field?
Dynamic List Field exposes the following properties to help user manage the styles of the suggest list.
| Property Name |
Property Type |
Default Value |
Description |
| DataControlsFontFamily |
System.String |
"" |
Gets or sets the font family for the data controls (e.g. "Arial"). |
| DataControlsFontSize |
System.String |
"" |
Gets or sets the font size for the data controls (e.g. "12px"). |
| SuggestList |
SuggestListStyles |
- SuggestList.BackgroundColor = ""
- SuggestList.BorderColor = ""
- SuggestList.BorderWidth = ""
- SuggestList.CloseButtonFontSize = "11pt"
- SuggestList.ForeColor = ""
- SuggestList.HighlightBackgroundColor = ""
- SuggestList.HighlightForeColor = ""
- SuggestList.MaxRows = 1000
- SuggestList.MaxVisibleRows = 20
- SuggestList.PageInfoKeyword = "/"
|
Gets the settings that mangages the styles of the suggest list. |
Go to top
How to manage the styles or skin of Multi-Select List Field?
Multi-Select List Field exposes the following properties to allow client to manage its styles or skin.
| Property Name |
Property Type |
Default Value |
Description |
| DataControlsFontFamily |
System.String |
"" |
Gets or sets the font family for the data controls (e.g. "Arial"). |
| DataControlsFontSize |
System.String |
"" |
Gets or sets the font size for the data controls (e.g. "12px"). |
| HideSummary |
System.Boolean |
false |
Gets or sets a value indicating whether the selection summary should be hidden. |
| RemoveButtonText |
System.String |
"Remove" |
Gets or sets the remove button text. |
| SearchBoxWidth |
System.String |
"60px" |
Gets or sets the width of the search box (e.g. "60px"). |
| SelectAllText |
System.String |
"Select All" |
Gets or sets the select all text. |
| SelectedItemsList |
SelectedItemsListStyles |
- SelectedItemsList.BackgroundColor = ""
- SelectedItemsList.DisabledTextColor = "gray"
- SelectedItemsList.ForeColor = ""
- SelectedItemsList.Height = "94px"
- SelectedItemsList.HighlightBackgroundColor = ""
- SelectedItemsList.HighlightForeColor = ""
- SelectedItemsList.MaxWidth = 300
|
Gets the settings that mangages the styles of the selected items list. |
| SelectionPromptText |
System.String |
"Select" |
Gets or sets the selection prompt text. |
| SuggestList |
SuggestListStyles |
- SuggestList.BackgroundColor = ""
- SuggestList.BorderColor = ""
- SuggestList.BorderWidth = ""
- SuggestList.CloseButtonFontSize = "11pt"
- SuggestList.ForeColor = ""
- SuggestList.HighlightBackgroundColor = ""
- SuggestList.HighlightForeColor = ""
- SuggestList.MaxRows = 1000
- SuggestList.MaxVisibleRows = 20
- SuggestList.PageInfoKeyword = "/"
|
Gets the settings that mangages the styles of the suggest list. |
| SummaryPrefix |
System.String |
"" |
Gets or sets the prefix of the selection summary that indicates how many items are selected. |
| SummarySuffix |
System.String |
" selected" |
Gets or sets the suffix of the selection summary that indicates how many items are selected. |
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
How do Dynamic List Field and Multi-Select List Field handle very long list
and how to ensure their responsiveness?
Dynamic List Field and Multi-Select List Field use pagination to ensure their responsiveness
when handling very long list. Specifically, the SuggestList.MaxRows property defines the
maximum number of items the suggest list 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 SuggestList.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 SuggestList.MaxRows property to a lower value such as 100. Also note that the
SuggestList.MaxRows property should not be smaller than the SuggestList.MaxVisibleRows
(default to 20) property.
Go to top
What keyboard interface do Dynamic List Field and Multi-Select List Field Support?
Dynamic List Field and Multi-Select List Field support the following keyboard interface:
| Key Name |
Action in Dynamic List Field |
Action in Multi-Select List Field |
| Enter |
Select the highlighted item in the suggest list. |
Toggle the selection of the highlighted item in the suggest list. |
| Tab |
Close the suggest list if it is visible and move focus to the next tab stop. |
Close the suggest list if it is visible and move focus to the next tab stop. |
| Up Arrow, Down Arrow |
Move the highlight in the suggest list up or down by one item. |
Move the highlight in the suggest list up or down by one item. |
| Page Up, Page Down |
If the suggest list can hold all search result, move the highlight in the suggest list
up or down by the number of items specified by the SuggestList.MaxVisibleRows property;
otherwise navigate to the previous or next page of the search result. |
If the suggest list can hold all search result, move the highlight in the suggest list
up or down by the number of items specified by the SuggestList.MaxVisibleRows property;
otherwise navigate to the previous or next page of the search result. |
| Esc |
Close the suggest list if it is visible. |
Close the suggest list if it is visible. |
Go to top
How to display tooltip for a field?
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