Lookup Call

A Lookup Call is used to lookup a single or multiple Lookup Rows. Several widgets like Smart Field, List Box or Tree Box take advantage of that concept in order to provide their proposals.

The most important parts of a Lookup Row are the key and the value. The key can be of any type, the text must be of type String. In addition to the key and the text a Lookup Row can also define an icon, a tooltip text, CSS classes and more.

Each Smart Field in Scout references a LookupCall class. The lookup call is in charge of querying a data source and returning results for that query. Example: when you type "f" into a Smart Field, a lookup call could return a result which contains lookup rows starting with "F", like "Faz" and "Foo".

Scout JS

The lookup call may return static (hard-coded) data which is already available in the browser, or may fetch an external data-source via HTTP, typically some kind of REST API. Depending on how your Smart Field is configured and used, the Smart Field will call different methods on the LookupCall instance and pass data to that method, like the search text the user has typed into the field. These methods are: getAll, getByText, getByKey and getByRec.

  • getByKey(): Retrieves a single lookup row for a specific key value. Used by Smart Fields and Smart Columns to get the display text for a given key value.

  • getByText(): Retrieve multiple lookup rows which match a certain String. Used by Smart Fields when the user starts to enter some text in the field.

  • getAll(): Retrieves all available lookup rows. Used by Smart Fields when the user clicks on the field.

  • getByRec(): This can only be used for hierarchical lookup calls. It retrieves all available sub-tree lookup rows for a given parent.

You must implement these methods. Start with creating a sub class of LookupCall(.js). Sub class StaticLookupCall(.js) when you need a simple lookup call that operates on data that is available locally. Sub class RemoteLookupCall(.js) when you must fetch lookup data from a remote server. This class is also used in Scout Classic to start a lookup on the Scout UI Server.

Note that the lookup call works with Deferreds. This means the lookup call runs in the background and does not block the UI. When the lookup call is done eventually the Deferred is resolved and the Smart Field will process the result returned by the lookup call.

Scout Classic

Lookup calls provide different method to compute the set of LookupRows :

  • getDataByKey(): Retrieves a single lookup row for a specific key value. Used by SmartFields and SmartColumns to get the display text for a given key value.

  • getDataByText(): Retrieve multiple lookup rows which match a certain String. Used by SmartFields when the user starts to enter some text in the field.

  • getDataByAll(): Retrieves all available lookup rows. Used by SmartFields when the user clicks on the browse icon.

  • getDataByRec(): This can only be used for hierarchical lookup calls. It retrieves all available sub-tree lookup rows for a given parent.

Members

The Lookup call contains attributes (accessible with getter and setter) that can be used to compute the list of lookups rows. Out of the box you have:

  • key: contains the key value when the lookup is queried by key.

  • text: contains the text input in case of a text lookup (typically this is the text entered by the user smart field).

  • all: contains the browse hint in case of a lookup by all (typically when a user click on the button to see all proposal in a smart field).

  • rec: contains the key of the parent entry, in when the children of a node are loaded.

  • master: contains the value of the master field (if a master field is associated to the field using the lookup call).

It is possible to add you own additional attributes, for example validityFrom, validityTo as date parameter. Just add them as field with getter and setter:

@ClassId("6154090e-86ac-4c08-9769-bf3ef61c1b4b")
public class LanguageLookupCall extends LookupCall<String> {
  // other stuff like serialVersionUID, Lookup Service definition...

  private static final long serialVersionUID = 1L;

  private Date m_validityFrom;
  private Date m_validityTo;

  @Override
  protected Class<? extends ILookupService<String>> getConfiguredService() {
    return ILanguageLookupService.class;
  }

  public Date getValidityFrom() {
    return m_validityFrom;
  }

  public void setValidityFrom(Date validityFrom) {
    this.m_validityFrom = validityFrom;
  }

  public Date getValidityTo() {
    return m_validityTo;
  }

  public void setValidityTo(Date validityTo) {
    this.m_validityTo = validityTo;
  }
}

In this case, you might want to set your properties before the lookup call query is sent. This can be done with the PrepareLookup event of the SmartField or the ListBox:

    @Override
    protected void execPrepareLookup(ILookupCall<String> call) {
      LanguageLookupCall c = (LanguageLookupCall) call;
      c.setValidityFrom(DateUtility.parse("2012-02-26", "yyyy-mm-dd"));
      c.setValidityTo(DateUtility.parse("2013-02-27", "yyyy-mm-dd"));
    }

If you follow this pattern, you will consume the values on the server by casting the call:

  @Override
  public List<? extends ILookupRow<String>> getDataByAll(ILookupCall<String> call) {
    LanguageLookupCall c = (LanguageLookupCall) call;
    Date validityFrom = c.getValidityFrom();
    Date validityTo = c.getValidityTo();

    List<? extends ILookupRow<String>> result = new ArrayList<>();
    //compute result: corresponding lookup rows (depending on validityFrom and validityTo).
    return result;
  }

Type of Lookup Calls

With a Lookup Service

Delegation to the Lookup Service on server side.

They are not necessarily restricted to a fix number of records. Instead, they should be favoured if the set of records is rather large.

Local Lookup Call

Such a LookupCall is used if the data can be provided directly without the need to make a backend call.

An example of this approach is when a SmartField or a SmartColumn is configured to be used with a CodeType. The code types are cached, so it is not necessary to fetch them using a lookup service. Instead, a LocalLookupCall, in that case the CodeLookupCall, may be used to load the data. It creates the LookupRows corresponding to the codes in the CodeType.

Overview

LookupCall

Properties

Defined with getConfiguredXxxxxx() methods.

  • Service: Defines which service is used to retrieve lookup rows

  • MasterRequired: Defines whether a master value must be set in order to query for multiple lookup rows

Code examples

Using a LookupCall in a SmartField:

    @Override
    protected Class<? extends ILookupCall<String>> getConfiguredLookupCall() {
      return LanguageLookupCall.class;
    }

Accessing a LookupRow directly:

It is possible to access a LookupRow directly. In this example the input is a key (thisKey) and the method getDataByKey() is used. Before accessing the text, we ensure that a LookupRow has been retrieved.

    //Execute the LookupCall (using DataByKey)
    LookupCall<String> call = new LanguageLookupCall();
    call.setKey(thisKey);
    List<? extends ILookupRow<String>> rows = call.getDataByKey();

    //Get the text (with a null check)
    String text = null;
    if (rows != null && !rows.isEmpty()) {
      text = rows.get(0).getText();
    }