SuggestBox

SuggestBox is a highly configurable element that can be used to provide the users with, as the name implies, suggest functionality. What can be understood from the suggest functionality is offering users a set of options retrieved from data sources as the user types into the input field.

The whole outlook of the Drop-down Box and the number of the columns and which data fields they are bind to can be customized according to the needs. The element is used together with a data source.

The element can be seen as a combo box whose options are filled in automatically as the user types in. Similar to a combo box, this element has also an "option" data which user types or selects and a "value" data which is associated with the selected option. The value is maintained as a hidden input element which is assigned a value automatically as the user navigates on the displayed options with arrow keys or with mouse.

When a form that contains a SuggestBox is submitted the selected option and its associated value become request parameters. The name of the value parameter is the same as the element name and the name of the option parameter is what is specified in the "Associated-Value-Field Name" property.

ESC key can be used to enable or disable the refresh functionality of the SuggestBox for the focused input element on the page.

The initial value for the SuggestBox value. Please note that this is not the option that appears on the input field itself. To assign an initial value for the current option use "Value" property in the Functional Tab.

The name of the data source that will provide data for the SuggestBox. In the data source properties, i.e. in the Query property if it is a RelDB data source, you should evaluate the request parameters defined in the "Request Parameters" property.

Query:

select ID, NAME, PRICE from products where NAME LIKE '@vof(SSTR)%'

The number of the items to be displayed in the drop-down box is specified using this property.

The names of the data nodes returned from the data source (separated with commas) whose values to be encrypted.

If the value of this property is set to true, then the option focused on the Drop-Down Box is transferred to the input field automatically.

The request parameters that will be used in the data source should be specified in this property.

The element does not send the request as soon as the user pressed a key, but waits for a time specified with this property. If a new key stoke is received from the user before this time expires the clock is reset. After the time specified here expires the request is sent to the server. This value should be set carefully by considering the latency and the server performance where the application is hosted.

If true is assigned to this property, the SuggestBox is activated when it is clicked with the mouse. Additionally the records shown on the drop-down box can be scrolled forward and backward using the mouse wheel.

You can use this property to differentiate the outlook of the SuggestBox editbox and the drop-down box. If a name other than "default" is used here then new CSS definitions that contains this name in their class names should also be provided. The easiest way to do that is to copy
{INSTALL_DIR}lib\sys\moremotion\ROOT\moremotion\face\Ajax\SuggestBox\default\0.css file, change it and link to the page.

The Drop-Down box is a box that opens automatically as the user types in to the input field and displays the options

Defines how the Drop-Down Box is aligned according to the input field. Options are "left", "right" and "center".

The width of the Drop-Down Box. Initial value %vof(rect.width) means it will be the same as the width of the input field.
Horizontal Offset. In this property, optionally, the horizontal offset of the SmartBox can be specified, in case the default offset is not convenient.
Example: 500,200. In the example, the value 500 is the width and the value 200 is the horizonal offset. There has to be a comma between these two values.

The name of the field name whose content will be used as the value of the suggested option.

The captions of the header columns. If this property is not defined, no header is rendered for the Drop-Down Box.

The name of the data source fields or the symbols (created with setSymbolValue() function) whose values will be used as the column contents.

SuggestBox element supports event handlers to give the developers better control. The Javascript handler functions that are defined in Event Handles properties are called when the related event occurs and the SuggestBox object is passed to them.

It is called just before the Ajax request is sent to the server. If the event handler returns false the the sending the request is canceled.

After the response is received from the server, it is started to build the options of the Drop-Down Box. If a handler is defined in this property it is called before building each option.

If we want to display different images depending of the values of the data nodes, we can define a handler function in this property as follows

function ArrangeImage(sbox) {

var icon = sbox.getFieldValue("ICON");

sbox.setSymbolValue("ICON",'<img src="images/'+icon+'.gif"/>');

}

The user can navigate on the options of the Drop-Down Box either with arrow keys or with mouse. If a handler is defined with this property it is called whenever an option of the Drop-Down Box gains focus.

function OnChange(sbox) {

var price = document.getElementById("PRICE");

price.value = sbox.getFieldValue("PRICE");

}

3. Value and the Associated Value. A value must be given into the input field and there has to be an associated value with the entered value.

4. Associated Value. It is not obligatory to enter a value to the input field. However if a value is entered into the input field there has to be an associated value with it.

5. Value without and Associated Value. A value must be given into the input field and there must not be an associated value with it.

In order to perform more specialized validations on the value entered into the SuggestBox, you can prepare a Custom Validation function and enter its name in this property.

The custom validation function receives only one parameter which is the SuggestBox object.

function CustomValidation(sbox) {
  var elm = sbox.elm;
  if (elm.value.indexOf("'") > -1) {
    alert("Apostrophes not allowed...");
    elm.focus();
    elm.select();
    return false;
  }

  var elm_S = sbox.selm; // (*)
  if (elm_S.value < 5) {
    alert("The associated value cannot be lower than 5...");
    elm.focus();
    elm.select();
    return false;
  }
  return true;
}

As it is seen in the example, if the validation fails the function should return false. Additionally the function may focus on the input field and select the value of the field to help user to recognize where the error on the page is.

(*) The hidden element of the SuggestBox that keeps the associated value can be accessed as it's shown in the example.

If defined, the validation error handler Javascript function will be called when a validation error occurs. The function receives an Exception object that provides information about the error occurred. See MoreMotion API documentation for more about Exception class.

The handler should return normally if it handles the error or throw the Exception object.

   function MyErrorHandler(ex) {
    if (ex.code == "CANNOT_BE_BLANK") return;
    throw ex;
  }