Difference between revisions of "RAP/Incubator/DropDown"

Revision as of 07:27, 14 January 2014

The DropDown incubator project aims to provide a simple and efficient text input assist for RAP, also known as "type ahead", "auto suggest", "auto complete" or "field assist" in various frameworks. The current git master is only compatible to RAP master, but there is also a RAP 2.1 compatible branch that has the same features and API. P2 repositories for both versions can be found here.

The DropDown Widget

The org.eclipse.rap.addons.dropdown.DropDown widget can be found in the org.eclipse.rap.addons.dropdown bundle and is basically a free-floating List (including setItems and Selection event support) that can be attached to a Text widget or any other control. When made visible (DropDown.show()), the DropDown will be placed below the widget. It will hide automatically if the parent (Text) looses focus, ESC is pressed or an item in the DropDown is clicked. While it is visible (and the parent is focused), the selection can be changed using the "Up" and "Down" keys. This is the full extend of its functionality.

AutoSuggest

The org.eclipse.rap.addons.autosuggest.AutoSuggest component aims to provide a complete solution for text input assistance. It wraps the DropDown widget and requires only the Text widget and a data source to work properly. It can be found in the org.eclipse.rap.addons.autosuggest bundle, which has a dependency to the RAP/ClientScripting project if you use the RAP 2.1 version. (It has no special dependencies in RAP 2.2+ since these RAP versions already include ClientScripting.)

DataSource

A minimal setup of a AutoSuggest requires an instance of DataSource, which in turn requires a DataProvider.

Example:

   Text text = new Text( parent, SWT.BORDER );
   DataSource dataSource = new DataSource();
   dataSource.setDataProvider( new ArrayDataProvider( "text1", "text2", "text3" ) );
   AutoSuggest autoSuggest = new AutoSuggest( text );
   autoSuggest.setDataSource( dataSource );

The AutoSuggest will be disposed automatically with the Text widget. Please be aware that currently (as of August 2013) DataSources live on the client as long as the session does. Equal DataSources should therefore be re-used instead of re-created to not waste client memory.

Templates

Unless set up differently, the suggestions that are presented to the user are simple strings that are identical to the string that will be inserted when a suggestion is selected. To allow different forms of presentation a template can be set on the data source. Currently the only available template is ColumnTemplate, which allows prestenting the suggestions as table with multiple columns. When using ColumnTemplate a matching data provider needs to be implemented, ColumnDataProvider. This provider allows defining a column text for each suggestion (getTexts), as well as the text that is actually inserted (getValue).

Example:

   Text text = new Text( parent, SWT.BORDER );
   DataSource dataSource = new DataSource();
   dataSource.setTemplate( new ColumnTemplate( 50, 150, 150 ) ); // the column widths
   ColumnDataProvider dataProvider = new ColumnDataProvider() {
     public Iterable<?> getSuggestions() {
       return Arrays.asList( someArray ); // for example an array of string arrays (String[][])
     }
     public String getValue( Object element ) {
       String[] value = ( String[] )element;
       return value[ 0 ];
     }
     public String[] getTexts( Object element ) {
       String[] value = ( String[] )element;
       return new String[] { value[ 0 ], value[ 2 ], value[ 3 ] };
     }
   } );
   dataSource.setDataProvider( dataProvider );
   AutoSuggest autoSuggest = new AutoSuggest( text );
   autoSuggest.setDataSource( dataSource );

Adanced Customization

The AutoSuggest class can be extended to modify it's behavior and/or add new features/API. This is not 100% future-proof as some of the JavaScript API that is used is considered internal, but there are currently no fundamental changes planned for Autosuggest/DropDown. (This may change if these Components are migrated from the Incubator to RAP core.)

Attaching a Custom a JavaScript File

To make any signficant changes to AutoSuggest it is necessary to load your own JavaScript implementation of the AutoSuggest logic. To do so, extend the AutoSuggest class like this:

public class CustomAutoSuggest extends AutoSuggest {

  public CustomAutoSuggest( Text text ) {
    super( text );
  }

  @Override
  protected ClientListener getAutoSuggestListener() {
    return CustomAutoSuggestClientListener.getInstance();
  }

}

Copy the files ResourceLoaderUtil.java and AutoSuggest.js from the org.eclipse.rap.addons.autosuggest source bundle to an internal package that is accessible by CustomAutoSuggest. Rename AutoSuggest.js to CustomAutoSuggest.js. Then add the implementation for CustomAutoSuggestClientListener to the same package:

public class CustomAutoSuggestClientListener extends ClientListener {

  public static CustomAutoSuggestClientListener getInstance() {
    return SingletonUtil.getSessionInstance( CustomAutoSuggestClientListener.class );
  }

  private CustomAutoSuggestClientListener() {
    super( getText() );
  }

  private static String getText() {
    String path = "path/to/your/CustomAutoSuggest.js";
    return ResourceLoaderUtil.readTextContent( path );
  }

}

Now you should be able to use CustomAutoSuggest like the normal AutoSuggest class.

Understanding and Customizing AutoSuggest.js

The AutoSuggest instance is represented on the client by a simple model object (API is below), however this is not what AutoSuggest.js is. AutoSuggest.js contains the client logic that manages the interaction between DropDown, Text and the data model. It's handleEvent function gets all important events from the client representations of DropDown, Text and Autosuggest(model) and delegates them. First, all important properties of Text and DropDown are synchronized with the model in the "sync"/"forward" functions. Usually you don't have to touch those. The logic itself is implemented within the functions starting with "on", which are called whenever a significant event (usually a value change) occurs on the model. They all have one parameter (the event object) and have the model object as their context ("this").

The model is a simple container of key/value pairs that fires a change event whenever a value is modified. The implementation can be found in Model.js in AutoSuggest bundle. The API consists of the following methods:

A change event object fired by a "set" call on the model has the following fields:

Adding new properties to AutoSuggest

Accessing Text and DropDown client widgets

The client Text widget API is documented here: http://download.eclipse.org/rt/rap/doc/2.2/guide/reference/jsdoc/symbols/Text.html
The client DropDown widget API consists of the following methods:

DropDown and Text fire events according to http://download.eclipse.org/rt/rap/doc/2.2/guide/reference/jsdoc/symbols/Event.html