Step 2. Widget configuration and display

Widgets have various configuration and behaviour options that can be specified when creating them. In this step we will adjust some of the parameters of the keyword-search widget.

Documentation

A list of the configuration options and other properties of the keyword-search widget are at:

API - keyword-search

Setting configuration options

A configuration structure can be passed when creating the widget.

There are currently two options that can be configured to change the keyword-search widget's appearance:

  • showLabel

    (boolean) Specifies that a label (prompt) should be added before the text box. Defaults to true.

  • showSubmit

    (boolean) Specifies that a button should be added after the text box. Defaults to false.

To set configuration options you would pass a structure to the widget creation call. For example:

{
    showLabel: false,
    showSubmit: true
}

In practice

As an example, make a new page copied from the one we made earlier and modify the widget creation call to now look like:

<script>
IMu.ready(function()
{
   var keySearch = $('#example-keyword-search').IMu('keyword-search',
   {
      showLabel: false,
      showSubmit: true
   }
  );
});
</script>

Notice how the configuration structure is passed in the IMu plugin method after the widget name.

This is typical of how IMu widgets are passed configuration parameters.

Example page

example 2

What it does

Not much more than before but in this case the widget will not display the 'search' label and it will now have a Submit button displayed, although the button won't do much (yet).

Things to try

Try changing the showLabel and showSubmit properties and see how the display changes.

Calling widget methods

The keyword-search widget at the moment doesn't really do much so let's start adding some more functionality.

Widgets may have methods. The keyword-search widget has a setTerms method that will add text to the input element.

(see API - keyword-search)

To use the setTerms method, following the creation of the widget, you can do something like:

var keySearch = $('#example-keyword-search').IMu('keyword-search');
// ...
keySearch.setTerms('red');

This would place the text 'red' into the keyword-search widget.

Try adding something like this to your page.

Adding Callback functionality

Another parameter that can be added in the configuration is an onSearch callback. The configuration parameter onSearch can be given a function as a value.

onSearch: function(terms)
{
   do_Something_When_We_Press_Enter(terms);
}

Take the page we have been working with and try adjusting the javascript as follows:

var keySearch = $('#example-keyword-search').IMu('keyword-search',
   {
      showLabel: true,
      showSubmit: true,
      onSearch: function(terms)
      {
         alert('search for ' + terms);
      }
   }
);
keySearch.setTerms('red');

This page should now have the word 'red' in the input box of the widget. In addition if you click the Go button it should display an alert dialog with the text entered in the widget displayed.

Example page

example 3

Again the widget is not particularly useful (yet). We will soon however use the onSearch callback to actually contact the EMu database and request that it runs a search. Before that step, let's look at the use of CSS to change the appearance of the widget.

Adjusting the Widget appearance using CSS

To the existing page try adding something like the following CSS to the head section:

<style>
   #example-keyword-search
   {
       background-color: red;
       border: 1px solid gray;
       font: italic bold 12px/30px Georgia, serif;
       height: 3.5em;
       width: 20%;
   }

   #example-keyword-search input
   {
       font: italic bold 12px/30px Georgia, serif;
   }

   #example-keyword-search button
   {
       font:italic bold 12px/30px Georgia, serif;
   }
</style>

Notice how this changes the display of the page.

Example page

example 4

Things to try

  1. Try changing the CSS properties of the elements in the example CSS.
  2. Using the appropriate browser developer tools, investigate the structure of the widget. Use this to add other CSS entries to change the look of the widget.
  3. Change the onSearch callback to change the terms in the widget (by calling the setTerms method).
  4. If you are familiar with jQuery, try changing the onSearch callback to change the page somehow when the user clicks the Go button.

Next we will actually start using the widget to talk to the database.