Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

WebCombo 7 brings a whole new experience for developers and users through full support for the new WebUI Unified Theming. It presents a stylish theme which shows a simple, yet elegant look. WebCombo also integrates well with WebGrid which provides easy input selection.

This page explains the concepts, features, benefits and the best practices when using WebCombo unified theme in your web projects.

Modern note

If you're not familiar with WebUI unified theming, please refer to Unified Theming and WebUI Modern Theme.

Panel

On this page:

Table of Contents
maxLevel1
stylecircle

Introducing WebCombo Modern Theme

In the past versions, WebCombo control is typically styled by specifying the style definition explicitly in the control markup. However, this approach apply their own styles individually and did not support reusing a common style definition. Consequently, you can't easily leverage modern CSS frameworks such as Bootstrap to create a consistent theming around your application.

To address these challenges, WebCombo 7 introduces a brand-new modern theme which was built upon unified theming framework. It's now possible to streamline the WebCombo styles in a unified theme, enabling a consistent look-and-feel across the application.

Here's how the WebCombo controls look like with unified modern theme.

Image Modified

Image Modified

Image Modified

Image Modified

Image Modified

Features

Streamlining the WebCombo styles into a unified theme that promote consistency with the rest of WebUI components, while at the same time supporting all existing features, requires major improvements to the core rendering and foundation of the control. As the result, you can modify the fundamental WebCombo settings through properties as usual, while having the styles applied perfectly.

This section explains WebCombo's features and how they work.

Entry Mode

WebCombo provides you with two entry-mode features which are auto-complete and instant-lookup. This feature allows you to take a peek at the existing data based on what you type in the input box. Here are the figures showing WebCombo's entry-mode features.

Auto-complete feature will show suggestion based on what you type in the input box. Instant-lookup feature allows you to see the existing data by typing the first few letters of the data that you desire and pressing the enter key.

You can specify the LayoutSettings' EntryMode property to apply these features. Look for the code below for examples.

Code Block
titleauto-complete
languagexml
<ISWebCombo:WebCombo runat="server" DataSourceID="AccessDataSource1"
		DataTextField="ContactName" DataValueField="CustomerID">
	<LayoutSettings EntryMode="AutoComplete">
	</LayoutSettings>
</ISWebCombo:WebCombo>
Code Block
titleinstant-lookup
languagexml
<ISWebCombo:WebCombo runat="server" DataSourceID="AccessDataSource1"
		DataTextField="ContactName" DataValueField="CustomerID">
	<LayoutSettings EntryMode="InstantLookup">
	</LayoutSettings>
</ISWebCombo:WebCombo>

WebCombo's DataTextField property is used for the data you want to display in the control while DataValueField property is used for determining the value of the control.

Multiple Selection

WebCombo contains two multiple selection features which are bound and unbound modes. Bound mode allows you to type ahead the data that you desire and WebCombo will show you suggestions based on what you type. Unbound mode sets the WebCombo to ReadOnly mode and enables you to choose the desired data by ticking the check box.

Here's the example on how to apply the multiple selection bound mode feature.

Code Block
titlebound-mode
languagexml
<ISWebCombo:WebCombo runat="server" DataSourceID="ISDataSource1" DataTextField="FullName" DataValueField="Email" DataMember="Customers">
	<MultipleSelectionSettings Enabled="True" />
</ISWebCombo:WebCombo>

To apply the unbound mode feature, first you need to specify the data in the code behind. The next step would be set MultipleSelectionSettings' Enabled property to True and set LayoutSettings' TextBoxMode property to ReadOnly. Take a look at the example below.

Code Block
titleunbound-mode (code behind)
languagec#
DataView view = this.AccessDataSource1.Select( DataSourceSelectArguments.Empty) as DataView;
DataTable table = view.Table;
WebCombo1.PopulateUnboundData(table, true);
Code Block
titleunbound-mode
languagexml
<ISWebCombo:WebCombo ID="WebCombo1" runat="server" Width="100%" DataTextField="ProductName" DataValueField="ProductID">
	<Columns>
		<ISWebCombo:WebComboColumn BaseFieldName="ProductName" Bound="False" HeaderText="Product Name" Name="ProductName" Width="250px" />
		<ISWebCombo:WebComboColumn BaseFieldName="UnitPrice" Bound="False" HeaderText="Price" Name="UnitPrice" Width="150px" />
		<ISWebCombo:WebComboColumn BaseFieldName="UnitsInStock" Bound="False" HeaderText="Stock" Name="UnitsInStock" Width="180px" />
	</Columns>
	<MultipleSelectionSettings Enabled="True" />
	<LayoutSettings AllowFloatingText="false" ComboMode="MultipleColumns" TextBoxMode="ReadOnly">
	</LayoutSettings>
</ISWebCombo:WebCombo>

ValidationState API

WebCombo 7 supports built-in validation styles available in the WebUI unified theme and also adds integration to ASP.NET validators. When the associated validator returns an invalid result, WebCombo automatically updates its styles with an error style. Likewise, the styles will be updated accordingly when the input satisfies the validators. In addition, WebCombo also introduces OnValidate client-side event which will be invoked whenever the validator is performing validation on the WebCombo control. WebCombo also provides a new SetValidationState API allowing you to change the contextual color programmatically.

These new API allows you to implement custom validation process. For instance, you might want to update the WebCombo with success contextual color when the validation returns a valid value. You can easily achieve this scenario by handling the OnValidate event to intercept the validation process, then call the SetValidationState method accordingly. Take a look at the example below.

Code Block
languagexml
<ISWebCombo:WebCombo runat="server">
	...
	<LayoutSettings>
		<ClientSideEvents OnValidate="WebCombo_OnValidate" />
	</LayoutSettings>
</ISWebCombo:WebCombo>
Code Block
languagejs
// OnValidate client-side event provides three parameters: 
// the control ID, the validator object, and the validator result
 
function WebCombo_OnValidate(controlId, val, isValid) {
	var control = ISGetObject(controlId);
	if (isValid) {
		control.SetValidationState("success");
	}
}

Size Class Variants

WebCombo's size can be set depending on your needs. See the following figure for example.

To apply a specific size class, see the example below.

Code Block
languagexml
<ISWebCombo:WebCombo runat="server" >
	<LayoutSettings>
		<FrameStyle MergeCssClass="true">
			<Normal CssClass=", small"></Normal>
		</FrameStyle>
	</LayoutSettings>
</ISWebCombo:WebCombo>


Modern note

It's important to specify the comma prefix in the CssClass property which will add the specified classes along with the default class instead of overriding the default class.

Form Group Variants

Depending on the usage, you can also apply form group size. Look at the figure below.

To apply a specific form group size, see the example below.

Code Block
languagexml
<div class="form-horizontal">
	<div class="form-group form-group-lg">
		<label class="col-sm-4">
			Large group
		</label>
		<div class="col-sm-8">
			<ISWebCombo:WebCombo runat="server">
			</ISWebCombo:WebCombo>
		</div>
	</div>
</div>

Input Group

WebCombo also supports Bootstrap's input-group class. To use this feature, you need to put the WebCombo inside webui-control class, see below for example.

Image Added

Code Block
languagexml
<div class="input-group">
	<div class="input-group-btn">
		<ISWebDesktop:WebButton runat="server" Text="WebButton">
		</ISWebDesktop:WebButton>
	</div>
 
	<div class="webui-control">
		<ISWebCombo:WebCombo runat="server">
		</ISWebCombo:WebCombo>
	</div>
</div>

Contextual Classes

WebCombo 7 has the same contextual classes as the Bootstrap's which are success, info, warning, and danger. To apply the form group styles, add the style class along with the default class. There are three types of styling that you can add, has-success class, has-warning class, and has-error class. Look for the example below for adding the success state class.

Code Block
titlecontextual form-group
languagexml
<div class="form-horizontal">
	<div class="form-group has-success">
		<label class="col-sm-4 control-label">
			Has Success
		</label>
 
		<div class="col-sm-8">
				<ISWebCombo:WebCombo runat="server">
				</ISWebCombo:WebCombo>
		</div>
	</div>
</div>

WebCombo 7 also integrates well with ASP.NET built-in validator controls. To apply these styles, add the style class in validator's CssClass property along with common-control-message class and set the Display property with the value of Dynamic. You can use three types of styling: error, warning, and info. Here's the example for the validator style.

Code Block
titlerequiredvalidator
languagexml
<ISWebCombo:WebCombo ID="WebCombo1" runat="server">
</ISWebCombo:WebCombo>
 
<asp:RequiredFieldValidator ID="RequiredFieldValidator1" runat="server"
		Display="Dynamic" CssClass="common-control-message error"
		ControlToValidate="WebCombo1" ErrorMessage="Please fill this WebCombo.">
</asp:RequiredFieldValidator>

Applying Theme

Building on unified theming concept, the WebCombo modern theme is designed as part of the WebUI modern theme. This means that once you applied the WebUI modern theme, it will automatically theme the WebCombo control without additional code. To learn more how to apply the WebUI modern theme, please see Applying Unified Modern Theme in WebUI Application and Creating a New WebUI Application with Unified Modern Theme.

Modern note

If you're new to the unified theming concept or unfamiliar with WebUI modern theme, please visit Unified Theming and New WebUI Modern Theme respectively. These two pages provide comprehensive details you need to know to understand how WebUI modern theme works.

Best Practices

If you're applying the modern theme to an existing web projects, please review your existing code to comply with the following best practices:

  • Remove appearance settings that are defined explicitly in the control. For instances, UseDefaultStyle and DefaultStyleMode are examples of settings that might affect appearance.
  • Remove style settings that are defined explicitly in the control. Most style settings have Style suffix and are type of either WebStyle or DynamicStyle, such as FrameStyle, FooterStyle, HeaderStyle, and so on.
  • If you applied a WebCombo layout file (.isl) from code behind, the code should be no longer necessary and can be safely removed.

Modern note

In conclusion, you should avoid defining settings that might affect appearance such as explicit styles, since all styles are defined externally and streamlined in the CSS stylesheets. Defining appearance-related settings might introduce conflict with the theme definition and produce unexpected results.

As the result, your WebCombo control definition should look much cleaner and simpler. The following example shows a simple WebCombo control that should be themed perfectly.

Code Block
languagexml
<ISWebCombo:WebCombo ID="WebCombo1" runat="server" DataSourceID="AccessDataSource1"
	DataTextField="ContactName" DataValueField="CustomerID" Width="100%">
	<Columns>
		<ISWebCombo:WebComboColumn BaseFieldName="ContactName" Name="ContactName" Width="150px" />
		<ISWebCombo:WebComboColumn BaseFieldName="ContactTitle" Name="ContactTitle" Width="150px" />
		<ISWebCombo:WebComboColumn BaseFieldName="CompanyName" Name="CompanyName" Width="150px" />
		<ISWebCombo:WebComboColumn BaseFieldName="Address" Name="Address" Width="250px" />
	</Columns>
	<LayoutSettings ComboMode="MultipleColumns" EntryMode="InstantLookup">
	</LayoutSettings>
</ISWebCombo:WebCombo>

Customizing Theme

With unified theming concept, you no longer specify any style settings explicitly in the control markup. Written completely in developer-friendly SCSS language, all WebCombo styles are now streamlined in CSS classes contained in the theme source. This makes it easier for you to review the overall style definitions and make necessary changes to the styles.

Modern note

Customizing the WebCombo theme source requires you to copy the source to your projects and configure a SCSS compiler. For more information how to customize WebUI theme source, please see Customizing WebUI Modern Theme.

WebCombo SCSS Variables

For easy customization, the WebCombo modern theme has provided a number of variables relating to common appearance settings. The following list shows the available SCSS variables for WebCombo.

Code Block
languagesass
$webcombo-arrow-icon:                       $icon-arrow-down !default;
$webcombo-more-icon:                        wf wf-angle-double-down !default;
$webcombo-help-icon:                        wf wf-ios-help-outline !default;
$webcombo-dropdown-btn-separator:           $control-dropdown-separator !default;
$webcombo-dropdown-btn-width:               $control-dropdown-width !default;
$webcombo-dropdown-btn-color:               $control-dropdown-color !default;
$webcombo-dropdown-btn-bg:                  $control-dropdown-bg !default;
$webcombo-dropdown-btn-hover-bg:            $webcombo-dropdown-btn-bg !default;
$webcombo-header-padding-vertical:          $table-cell-padding !default;
$webcombo-status-font-size:            		$control-header-font-size !default;
$webcombo-status-color:                		$control-header-color !default;
$webcombo-status-bg:                   		$control-header-bg !default;
$webcombo-help-color:                  		$color-primary !default;
$webcombo-help-hover-color:            		$color-info !default;
$webcombo-morebar-color:               		$text-color !default;
$webcombo-morebar-bg:                  		transparent !default;
$webcombo-morebar-hover-color:         		$input-border-focus !default;
$webcombo-morebar-hover-bg:            		darken($color-gray-lightest,5%)  !default;
$webcombo-header  :                   		$control-header-color !default;
$webcombo-header-bg:                  		$control-header-bg !default;
$webcombo-header-separator-color:     		$control-header-separator-color !default;
$webcombo-list-bg:                    		transparent !default;
$webcombo-list-color:                 		$dropdown-link-color !default;
$webcombo-list-hover-color:           		$dropdown-link-hover-color !default;
$webcombo-list-hover-bg:              		$color-gray-lightest !default;
$webcombo-list-active-color:          		$dropdown-link-active-color !default;
$webcombo-list-active-bg:             		$dropdown-link-active-bg !default;

The complete SCSS variables can be found in _variables.scss, while the WebCombo theme source can be found in the _webcombo.scss file located in the theme source folder.

Modern note

For more information how to customize SCSS variables and ensure the output is properly generated, see Customizing SCSS Variables.

WebCombo Layout Definition

In addition to the styles defined in the SCSS, one of the main component in a theme source is the component layout definition. The layout definition contains the contracts between the control and the CSS classes. The connection between the layout definition and the corresponding controls are automatically taken care by the WebUI Theme Framework at runtime.

To get a better understanding of the WebCombo styles, see its layout definition below.

Code Block
titlewebcombo.isl
languagexml
<ISWebCombo:WebCombo runat="server" UseDefaultStyle="False">
  <LayoutSettings SearchIconMode="Graphic" ResultBoxWindowType="Normal" EnableSlidingAnimation="true" AllowFloatingText="false" RoundCorner="false" ResultBoxShadow="false">
    <FrameStyle>
      <Normal CssClass="combo-frame">
      </Normal>
      <Over CssClass="combo-frame hover">
      </Over>
      <Active CssClass="combo-frame active">
      </Active>
    </FrameStyle>
    <DropDownStyle>
      <Normal CssClass="combo-dropdown">
      </Normal>
      <Over CssClass="combo-dropdown hover">
      </Over>
      <Active CssClass="combo-dropdown active">
      </Active>
    </DropDownStyle>
    <TextBoxStyle>
      <Normal CssClass="combo-textbox">
      </Normal>
      <Over CssClass="combo-textbox hover">
      </Over>
      <Active CssClass="combo-textbox active">
      </Active>
    </TextBoxStyle>
    <MoreButtonStyle>
      <Normal CssClass="combo-morebutton">
      </Normal>
      <Over CssClass="combo-morebutton hover">
      </Over>
      <Active CssClass="combo-morebutton active">
      </Active>
    </MoreButtonStyle>
    <ResultFrameStyle CssClass="combo-result"></ResultFrameStyle>
    <ResultBoxStyle CssClass="combo-resultbox"></ResultBoxStyle>
    <RowStyle>
      <Normal CssClass="combo-row">
      </Normal>
      <Over CssClass="combo-row hover">
      </Over>
      <Active CssClass="combo-row active">
      </Active>
    </RowStyle>
    <SelectedRowStyle CssClass="combo-row selected"></SelectedRowStyle>
    <ColumnStyle CssClass="combo-column"></ColumnStyle>
    <StatusBoxStyle CssClass="combo-statusbox"></StatusBoxStyle>
    <HeaderStyle CssClass="combo-header"></HeaderStyle>
  </LayoutSettings>
</ISWebCombo:WebCombo>

Modern note

For complete visualization details of WebCombo modern theme, please refer to WebCombo Modern Theme Style Reference.


Related Topics

Content by Label
spaces@self
reversetrue
showLabelsfalse
max5
sortmodified
labelswebcombo-features -webcombo-theming-overview theme-architecture
showSpacefalse
typepage