Search Bar

Purpose

Provides support for the search bar construct.

The search bar consists of three parts laid out in the following order.

An optional logo, represented using the object element.
A text input control, represented using the xforms:input element.
A submit button, represented using the xforms:submit element.

There are three rendering strategies of the search bar construct. The following strategies are listed in the order of preference, i.e. the first rendering that the device can support is the one that should be used for that device.

Exported Features

Note:

The cf2:ui.SearchBar#FixedWrap feature always returns false and is reserved for future product enhancements.

Imported Features: n/a

The cf2:ui.SearchBar feature is the union of the features for each strategy, and it is assumed to be supported if any of the sub features are supported. The sub features are mutually exclusive, i.e. a device that supports cf2:ui.SearchBar#Flexible cannot also support one of the other sub features. The set of devices that support cf2:ui.SearchBar is the union of the sets of devices that support each of the strategy specific features.

Markup

This component is provided by the ui:search-bar element.

The Flexible rendering strategy

This is the ideal representation of the search bar construct. Each part of the bar is centered vertically within the line. The bar occupies a single line, and fills the width of the page but does not overflow its edge, i.e. the text input field expands or contracts depending upon the width of the device screen.

The use of this strategy places a number of restrictions on the search bar elements. Refer to the section entitled Constraints for more information.

The Fixed No Wrap rendering strategy

The Fixed No Wrap and Fixed Wrap strategies are capable of handling the search bar construct on devices that do not support the Flexible rendering strategy. However, the search bar may no longer occupy the full width of the screen, and the search bar logo is ignored. The use of this strategy places a number of restrictions on the search bar elements. Please refer to the section entitled Constraints for more information.

The following table explains the relationship between the value of the text-align property set on the ui:search-bar element and the layout of the search bar.

text-align	Search bar layout
left
right
center
justify

The Fixed Wrap rendering strategy

This strategy is used when the device supports the Fixed No Wrap strategy but the calculated width of the input field is less than the width defined by the min-width property. Again, the search bar may no longer occupy the full width of the screen, the logo is ignored, and the use of this strategy places a number of constraints on the search bar elements. Refer to the section entitled Constraints for details.

The following table explains the relationship between the value of the text-align property set on the ui:search-bar element and the layout of the search bar.

text-align	Search bar layout
left
right
center

Constraints

There are a number of constraints that apply to the search bar elements.

The following styles are common to all strategies. If the page author violates these constraints, then it is a non fatal error, in other words, an error message will be logged to explain which constraint has been violated and how, and then it will behave as if the constraint was not violated, i.e. the value of the property will be set to the default value.

ui|search-bar {
  width: auto;
  height: auto;
}

ui|search-bar > xforms|input {
  width: auto;
  height: auto;
  mcs-columns: 0;
  mcs-box-sizing: border-box;
}

ui|search-bar > xforms|submit {
  width: auto;
  height: auto;
}

In addition to the common styles the following restrictions apply to the Flexible strategy.

ui|search-bar {
  display: mcs-box;
  overflow: hidden;
  mcs-box-align: center;
}

ui|search-bar > xhtml2|object {
  width: auto;
  height: auto;
  mcs-box-flex: 0;
}

ui|search-bar > xforms|input {
  mcs-box-flex: 1;
}

ui|search-bar > xforms|submit {
  mcs-box-flex: 0;
}

The use of the Fixed No Wrap and Fixed Wrap strategies imposes additional constraints on the search bar elements. Again, it is an error if the page author tries to override any of the properties to different values.

The following constraints apply to the ui:search-bar element and all its children:

font-size: normal;
font-weight: normal;
font-style: normal;
font-variant: normal;
font-family: monospace;
line-height: normal;
font-size-adjust: none;
font-stretch: normal;
width: auto;
height: auto;
margin: 0;
text-align: <any>;         /* optional, defaults to center */
color: <any>;              /* optional */
background: <any>;         /* optional */

Please note that he ::mcs-outside pseudo-element is not supported.

The following restrictions apply to the ui:search-bar element:
```
display: block;
border: none;
padding: 0;
border-spacing: 0 | 1em;   /* optional, defaults to 1em */
```
Although the border-spacing property is usually related to tables, it is used here to define the space between the input field and the button. If the value of the property is '0', then no separator is added; if it is '1em', a single non breaking space is added.

Please note that the search bar is supposed to fill the full width of the screen and therefore the ui:search-bar element must be targeted at a single column layout.

The following constraints apply to the xforms:input element:

display: inline;
border: <any>;             /* defaults to 2px inset */
padding: <any>;            /* defaults to 2px */
vertical-align: <any>;     /* defaults to middle */
text-align: <any>;         /* optional, defaults to left */
min-width: <any>;

In addition, the xforms:label element must be empty.

The following constraints apply to the xforms:submit element:
```
display: inline;
border: <any>;             /* defaults to 2px outset */
padding: <any>;            /* defaults to 2px */
vertical-align: <any>;     /* defaults to middle */
text-align: <any>;         /* optional, defaults to inherit from ui:search-bar */
mcs-form-action-style: <any>;
mcs-form-action-image: <any mimg policy, not transcodable>;
```
Please note that the mcs-form-action-image property requires the width of the image to be specified in the meta data for all variants as that is used in the calculation of the input field width.

In addition, the xforms:label element must not be empty. If it is empty, then the default value of 'ERROR' will be used.

Several general restrictions apply:

The object element defining the search bar logo is ignored.
Any lengths, e.g. padding, border and min-width must be specified in pixels; if they are not, then they all default to '0'.
Most devices will automatically add a border around and a padding inside the input field and the button, but they will differ from device to device. Therefore, the border and padding properties are set to the default values but can be overridden by the page author if necessary.

Customizing styles

Page authors may not want to restrict devices that support the Flexible strategy to using only those styles that are allowed in the fixed strategy. However, authors cannot just set the styles for all strategies as that will cause the constraints to be violated and will result in errors being logged. Therefore, page authors need to create a separate theme for styling the search bar. That theme must contain one variant for styling the Flexible strategy and use the selection by expression mechanism to target it at those devices that support the cf2:ui.SearchBar#Flexible feature. If authors want to customize the styling of the fixed strategies, then they can add another variant and use selection by expression to target it at devices that support one of the fixed strategies.