Skip to main content

Syncfusion Data Controls

The Xomega.Syncfusion.Blazor package includes a number of data control components based on the standard Syncfusion components to allow binding them to the data properties of your data objects by setting the Property parameter, e.g., Property="@VM.MainObj.StatusProperty".

The data controls reflect the current value(s) and visibility and editability states of the bound data property. They use the configuration of the data property to provide validation, value formatting, and selection from the list of possible values while adding other rich features provided by the Syncfusion components.

Most data controls include a label placed above the control, where the label text comes from the localized property label. You can hide the label by setting the ShowLabel parameter to false. You can also make the label displayed as a placeholder in the empty fields by setting the FloatLabel parameter to true, which would look as shown below.

Label placeholder

When such a control gets a focus, the label will float above it like this.

Label focus

To use custom label text, you can set the Placeholder parameter of the control, but you need to localize it as required.

The labels of editable data controls bound to a required property will show a red asterisk in front. An editable data control will set the user-entered or selected value(s) directly to the data property. If the value is invalid, it will highlight it in red and show the validation errors from the property under the control, as shown below.

Field validation

Note: you can also configure Syncfusion components to display the validation errors in a tooltip instead.

You can do that by setting the static flag UseTooltipForValidationErrors during the app initialization as follows.

XSfComponent.UseTooltipForValidationErrors = true;

The invalid control will be highlighted in red, but the error message will be shown only when the user hovers over the control, as shown below.

Field validation tooltip

Base components​

The Xomega.Syncfusion.Blazor package defines a couple of base components for Syncfusion components, which in turn are based on the Xomega Framework's base components.

XSfComponent​

The XSfComponent component extends the XComponent class and serves as a base class for standard Syncfusion data controls that don't allow selection from a list of possible values. The functionality this control provides on top of its base class includes the following.

  • Static constants and methods for styling error messages and conditionally showing them as a tooltip.
  • TooltipPosition parameter and methods to show the error tooltip as needed.
  • FloatLabel parameter to display the label as a placeholder on empty controls that floats above the control on focus.
  • FloatLabelType property that determines how to show the label on Syncfusion controls.

XSfOptionsComponent​

The XSfOptionsComponent component extends the XOptionsComponent class and serves as a base class for Syncfusion selection controls that provide a selection from a list of possible values. It is a generic class that usually takes the Header class as a type parameter. In addition to its base class functionality, this base component provides the following functionality.

  • FloatLabel parameter to display the label as a placeholder on empty controls that floats above the control on focus.
  • FloatLabelType property that determines whether or not to show the label on Syncfusion controls.
  • TooltipPosition parameter and methods to show the error tooltip as needed.
  • AllowFiltering parameter for Syncfusion controls that allow additional filtering of the selection list.
  • AllowCustom parameter for Syncfusion controls that allow custom values to be entered.
  • GroupByAttribute parameter for Syncfusion controls that allow grouping items in the selection list.
  • GroupTemplate parameter for a custom template to use for group headers when grouping is enabled.
  • ValueDisplayTemplate parameter for a custom template to use for values, where supported.
  • Configuration of the default item, value, and group templates to display the value using ValueFormat.DisplayString.
  • Implementation of some typical Syncfusion callback methods and helper methods.

Readonly controls​

If you need to output a read-only value of a data property as part of some text or in other places that don't require the property label, such as in a grid cell, then you can use the standard Xomega Blazor control XDataText and style it as needed using CSS classes.

XSfDataLabel​

The XSfDataLabel control is used to display read-only fields with a label on top. The value is displayed in a read-only input element, which allows you to tab to that field via the keyboard and copy the value, as shown below.

Data label

All you need for the XSfDataLabel is to bind it to your data property and optionally set the CSS Class as follows.

<XSfDataLabel Class="mb-3" Property="@VM.MainObj.SalesOrderNumberProperty"></XSfDataLabel>
<XSfDataLabel Class="mb-3" Property="@VM.MainObj.OrderDateProperty"></XSfDataLabel>

Standard controls​

The Xomega.Syncfusion.Blazor package defines a basic set of standard data controls, as described below.

XSfCheckBox​

The XSfCheckBox control is typically bound to a BooleanProperty and provides a way to edit a single option with a dedicated label, as illustrated below.

Checkbox

You just need to bind your XSfCheckBox to your data property and optionally set the CSS Class as follows.

<XSfCheckBox Class="mb-3" Property="@VM.MainObj.OnlineOrderFlagProperty"></XSfCheckBox>

Indeterminate state​

If the value of the property is null, the checkbox will show an indeterminate state, as shown below.

Checkbox

If your data property is marked as not required, meaning that the users should be able to set the null value, the bound XSfCheckBox control will cycle through three states and set the indeterminate state after you click on a checked checkbox.

warning

The label of a required checkbox will not show a red asterisk in front of it, but you can customize its CSS class if you want to highlight required (or optional) checkboxes in some way.

XSfTextBox​

The XSfTextBox data control is used for editing data properties using the standard text box. You would typically bind it to a TextProperty by setting the standard Property parameter as follows.

<XSfTextBox Class="mb-3" Property="@VM.MainObj.PurchaseOrderNumberProperty"></XSfTextBox>

Here is what it will look like.

Text box

note

The XSfTextBox data control will update the bound data property on each keystroke and set the Editing flag to false when you leave the field, which will trigger the property validation.

If the property is multi-valued, the users will be able to enter multiple values separated by a comma or any other of the ParseListSeparators configured for the property.

If the property is not multi-valued, the text field will automatically limit the text input to the Size of the property.

If the property value allows line breaks, then you can set the Multiline parameter to true. If you want to hide the Clear button (X) in the text box, you can set the ShowClearButton parameter to false.

Specialized input types​

You can set the additional Type parameter on the XSfTextBox control for specialized input types, such as email. For example, the following is a configuration for a password field.

<XSfTextBox Class="mb-3" Property="@VM.MainObj.PasswordProperty"
            Type="InputType.Password"></XSfTextBox>

This will mask the input characters, as shown below.

Password text

XSfDatePicker​

The XSfDatePicker control is designed to be bound to a DateTimeProperty using the standard Property parameter as follows.

<XSfDatePicker Class="mb-3" Property="@VM.MainObj.PaymentObject.DueDateProperty"></XSfDatePicker>

The XSfDatePicker control will render differently based on the specific type of data property it is bound to, as well as whether or not the property is multi-valued, as described under each tab below.

If the bound data property is an instance of a DateProperty, the control will allow only a date selection. The values will be formatted using the value of the Format property of the bound DateProperty, but you can override it by setting the Format parameter on the XSfDatePicker.

Date picker

By default, the X button to clear the value is not shown in the XSfDatePicker, but you can enable it by setting the ShowClearButton parameter to true.

XSfNumericTextBox​

XSfNumericTextBox is a special control for editing integer data properties or decimal data properties that you bind via the Property parameter.

<XSfNumericTextBox Class="mb-3" Property="@VM.MainObj.OrderQtyProperty"></XSfNumericTextBox>

It displays a text box with a numeric scroller, which allows you to increment or decrement the current value using a mouse or the up/down arrow keys, as shown below.

Numeric box

The value selection will be limited by the MinimumValue and MaximumValue values defined for the data property. You can control the increment step by setting the Step parameter on the control.

You can hide the Clear button (X) by setting the ShowClearButton parameter to false. You can also customize the value format by setting the Format parameter on the XSfNumericTextBox.

Selection controls​

Selection controls extend the XSfOptionsComponent and are bound to an EnumProperty, which allows them to display a list of items to select the value(s) from using the property's ItemsProvider.

XSfAutoComplete​

XSfAutoComplete control can be bound to an EnumProperty that is not multi-valued and shows a text box that allows you to type a partial string and select the value from a dropdown list of matching items.

warning

By default, the selection items in the dropdown list are rendered using the value format DisplayString. However, the selected item in the text box is displayed using the DefaultFormat of that Header, which is normally its Text field.

For example, let's consider that our data property for sales territories is configured to display the value using the "ID - Text" format, as follows.

TerritoryProperty.DisplayFormat = $"{Header.FieldId} - {Header.FieldText}";

If we bind an XSfAutoComplete control to this data property using

<XSfAutoComplete Property="@VM.MainObj.SalesObject.TerritoryProperty"></XSfAutoComplete>

then the dropdown list will show a combination of ID and Text, but the text box will only show the Text of the selected item, as illustrated below.

Auto complete

For additional features provided by the control, please click on one of the tabs below.

The auto-suggest mode allows you to enter custom text into the field in addition to selecting it from a list of the suggested values. Since the custom value is specified as a string, your property should be a string-based EnumProperty, where the ID is the same as the Text. It should not be based on any of the typed enum properties, such as EnumIntProperty.

To enable the auto-suggest mode, you need to relax the property validation rules to allow custom values that are not in the lookup table, as shown below.

TerritoryProperty.LookupValidation = LookupValidationType.None;

This will configure the XSfAutoComplete control to allow custom values, as illustrated below.

Auto-suggest custom

tip

You can also explicitly force the XSfAutoComplete control to allow or disallow custom values by setting its AllowCustom attribute as needed.

XSfDropDownList​

XSfDropDownList control can be bound to an EnumProperty that is not multi-valued and allows you to select the value from a dropdown list.

note

By default, the selection items both in the dropdown list and in the field are rendered using the value format DisplayString.

For example, let's consider that our data property for sales territories is configured to display the value using the "ID - Text" format, as follows.

TerritoryProperty.DisplayFormat = $"{Header.FieldId} - {Header.FieldText}";

If we bind an XSfDropDownList control to this data property as follows,

<XSfDropDownList Property="@VM.MainObj.SalesObject.TerritoryProperty"></XSfDropDownList>

then both the dropdown list and the selected item will show a combination of ID and Text, as illustrated below.

Dropdown list optional

If the property is not required, then the control will also have an X button to clear the value, as shown above. For required properties, there will be no clear button, and the label will have an asterisk.

Dropdown list

For additional features provided by the control, please click on one of the tabs below.

If your property has a long list of possible values to select from, you can enable filtering of your XSfDropDownList by setting the AllowFiltering parameter to true, as follows.

<XSfDropDownList Property="@VM.MainObj.SalesObject.TerritoryProperty"
                 AllowFiltering="true">
</XSfDropDownList>

In this case, the dropdown list will display a text box where you can start typing to filter down the list to only the matching items, as shown below.

Dropdown list filter

XSfComboBox​

XSfComboBox control can be bound to an EnumProperty that is not multi-valued and shows a text box that allows you to type a partial string and jump to the matching value in the dropdown list. You can also open up the dropdown list by clicking on the down arrow on the right or by pressing Alt+Down and then selecting the value from that list.

warning

By default, the selection items in the dropdown list are rendered using the value format DisplayString. However, the selected item in the text box is displayed using the DefaultFormat of that Header, which is normally its Text field.

For example, let's consider that our data property for sales territories is configured to display the value using the "ID - Text" format, as follows.

TerritoryProperty.DisplayFormat = $"{Header.FieldId} - {Header.FieldText}";

If we bind an XSfComboBox control to this data property using

<XSfComboBox Property="@VM.MainObj.SalesObject.TerritoryProperty"></XSfComboBox>

then the dropdown list will show a combination of ID and Text, but the field will only show the Text of the selected item, as illustrated below.

Combo box

XSfComboBox bound to a required property will have a label with a red asterisk, while for non-required properties, it will display the X clear button that allows you to clear the value.

For additional features provided by the control, please click on one of the tabs below.

Similar to the XSfAutoComplete control, you can allow filtering the dropdown list when typing in the XSfComboBox by setting the AllowFiltering parameter to true, as follows.

<XSfComboBox Property="@VM.MainObj.SalesObject.TerritoryProperty"
             AllowFiltering="true"></XSfComboBox>

The list will be filtered using the property's AsyncItemsProvider, which, by default, uses case-insensitive search anywhere in the value converted to a string format. In this case, the control will look as shown below.

Combo box filter

XSfMultiSelect​

XSfMultiSelect control can be bound to a multi-valued EnumProperty and provides a text box where you can type the part of the value and a dropdown list for you to select the matching values.

note

By default, the selection items both in the dropdown list and in the field are rendered using the value format DisplayString.

Here is how you can bind an XSfMultiSelect control to a data property containing a list of selected sales reasons.

<XSfMultiSelect Class="mb-3" Property="@VM.MainObj.SalesObject.SalesReasonProperty"></XSfMultiSelect>

Selection of multiple values for the sales reason is illustrated below.

Multi-select

When you are not entering values, and the control has no focus, it will show the values delimited by the data property's DisplayListSeparator, as shown below.

Multi-select unfocused

tip

To still show the values as chips when the field is not in focus, you can set the Mode parameter to VisualMode.Box.

For additional features provided by the control, please click on one of the tabs below.

Similar to other controls, you can allow filtering the dropdown list when typing in the XSfMultiSelect by setting the AllowFiltering parameter to true, as follows.

<XSfMultiSelect Class="mb-3" Property="@VM.MainObj.SalesObject.SalesReasonProperty"
                AllowFiltering="true"></XSfMultiSelect>

The list will be filtered using the property's AsyncItemsProvider, which, by default, uses case-insensitive search anywhere in the value converted to a string format. In this case, the control will look as shown below.

Multi-select filter

Action controls​

Action controls are bound to a special ActionProperty in the view model or any of its data objects. This allows them to use the action's localized text as a label and set up the access key configured for the ActionProperty to provide a keyboard shortcut for that action and underscore that key in the label, where possible.

The action will maintain its visibility or enabled state based on the state of the action property, including when the state of the action property is computed using specific visibility or enabling conditions.

warning

You still need to provide a callback function for the click handler, which is not part of the bound action property.

XSfActionButton​

The XSfActionButton control inherits from the XActionComponent and represents a button that you can bind to an action property using the Action parameter and supply the click handler in the OnClick parameter as follows.

<XSfActionButton OnClick="OnCloseAsync"
                 Action="@VM.CloseAction"></XSfActionButton>

The tabs below describe additional configurations for the XSfActionButton control.

For a primary action on the view, you can set the IsPrimary="true" parameter on the button as follows.

<XSfActionButton OnClick="OnSaveAsync" Action="@VM.MainObj.SaveAction"
                 IsPrimary="true"></XSfActionButton>

The button will be displayed as shown below.

Primary button