Adding typeahead pickers

Typeahead pickers are control objects that provide users with an accessible and forgiving incremental search method.

Typeahead pickers consist of a text field and a drop-down menu. As keywords are entered in the text field, matching search results are displayed below in a drop-down menu. Typeahead pickers do not require users to enter keywords in a specific format or to explicitly send a request to receive results.

NexJ framework analyzes search terms in real-time to retrieve and display returned results. Suggested results can be generated from a class in your NexJ Business Model or an external web service.

Typeahead pickers are created using NexJ Studio. They can be added to forms in the Presentation layer.
To add a typeahead picker to your NexJ application:

Create a picker control.
Configure typeahead functionality.
Add the picker to a form.

Info

A toolbar button for a typeahead picker is contained within its own toolbox therefore the source control for UIEvents from a toolbox button for a typeahead picker is not the same as the view name. The source control is the view's name with "toolbox" appended to it with no spaces or separators. For example, if the ID for a typeahead ispickOpportunity, the source for the button is:

source=(pickOpportunitytoolbox)

Creating picker controls

Create a new picker control file in the NexJ Studio Presentation layer. Control files specify how control objects will function when added to a NexJ application.

To create a new picker control:

In the NexJ Studio Presentation layer, click the Controls tab.
Right-click the model view sidebar and select New Control.
The New Control dialog opens.
In the Name field, enter the name of your new picker.
Note: As a development best practice, controls follow a naming convention. Pickers should be named in the following format: Name<Picker>.
Click Finish to create your new picker.
The picker control opens in the NexJ Studio editor and is added to the model view sidebar.

Your picker control has been created.

Configure the properties and attributes of the picker to define its functionality.

Typeahead picker configuration

Configure typeahead pickers in the Source tab of a control file.

A typeahead picker control file uses the following structure:

SCHEME

<Control
    implementation="nexj.core.view.flat.custom.FlatWebM1CustomPickerView"
    supportedClientTypes="flat"
    base="Picker"
>

   <Configuration>
      ...
   </Configuration>

   <Overrides
        promptsOnDelete="false"
   />
</Control>

Within the <Configuration> tag, specify all of the following properties to define the functionality of your picker.

Typeahead picker <Configuration> properties

Property	Value	Description
<type value=" "/>	M1, MM	The type of picker you are creating. Can be either Many-to-one (`M1`) or Many-to-many (`MM`).
<lines value=" "/>	Decimal	Number of lines each result in the drop-down menu will use.
<keystrokeDelay value=" "/>	Decimal	Minimum number of characters a user must enter before the typeahead search results are shown.
<timeDelay value=" "/>	Decimal	The delay between the last keystroke and the firing of the typeahead search in milliseconds.
<addAssociationImmediately value=" "/>	True, False	If set to True, each time a character is added or removed from the text field, the server will be re-queried to revise the list of suggested results in the drop-down menu and update the association class.
<searchClass value=" "/>	ClassName	The source class that will be queried by the picker.
<searchOrderBy value=" "/>	Attribute	Sorts of the drop-down menu for the specified attribute. The application will issue a query against this attribute in the associated class. For example, using termName lists results in alphabetical order. Alternatively, using `((firstName . #t) (lastName . #t) ((@) . #t))` sorts results by first and last names.
<searchCustomEvent value=" "/>	UI Event	The custom read event used on the source class. Omit to use normal read behavior.
<searchResultCaption value=" "/>	String	Source class caption shown in typeahead drop-down.
<searchTerm value=" "/>	String	The search term used on source class. For example, fullTextSearch will query all entered keywords.
<searchResultCount value=" "/>	Decimal	Maximum number of entries shown in the typeahead drop-down.
<selectPopupQueryControl value=" "/>	Form, String	The view path to query control on the MM picker popup screen.
<isInFallbackMode value=" "/>	True, False	If set to True, the picker requires the user to press Enter to confirm their selection.
<quickResolveShortCut ctrl=" " alt=" " shift=" " keyCode=" "/>	True, False, keyCode value	The keyboard shortcut used to search. For each of the CTRL, ALT, and Shift attributes, specify either True or False. For keyCode, specify a single key on the keyboard using a key code value.
<m1PickerEvent value=" "/>	UI Event	The UI Event that is fired when an item is selected in an M1 typeahead picker.
<dropDownWidth value=" "/>	Decimal	Width of the typeahead drop-down in pixels. -1 for 100% width.
<showMore value=" "/>	True, False	Enable (True) or disable (False) the More... menu when the amount of search results exceed the value defined in searchResultCount.
<m1ShowMoreEvent value=" "/>	UI Event	The UI Event that is fired when the user selects the More... menu when there are more than SearchResultCount items in the typeahead menu.

The following is an example <Configuration> tag from a typeahead picker:

SCHEME

<Configuration>      
      <type value="M1"/>
      <lines value="2"/>
      <keystrokeDelay value="3"/>
      <timeDelay value="200"/>
      <addAssociationImmediately value="false"/>
      <searchClass value="VOCIndexTerm"/>
      <searchOrderBy value="()"/>
      <searchCustomEvent value="customRead"/>
      <searchResultCaption value="termName"/>
      <searchTerm value="fullTextSearch"/>
      <searchResultCount value="5"/>
      <selectPopupQueryControl value="frmEntitySearch txtFullTextSearch"/>
      <isInFallbackMode value="false"/>
      <quickResolveShortCut ctrl="true" alt="false" shift="false" keyCode="75"/>
      <m1PickerEvent value="selectPossibleCause"/>
      <dropDownWidth value="-1"/>
      <showMore value="false"/>
      <m1ShowMoreEvent value="sysPick"/>
   </Configuration>

Adding typeahead pickers to forms

Add a typeahead picker to your NexJ application by inserting it into a form.

To add a typeahead picker to a form:

In the NexJ Studio Presentation layer, click the Forms tab.
Double-click the form you want to add a typeahead picker to.
The form opens in the NexJ Studio editor.
In the Layout view, right-click where you want to add the picker and select Insert Picker.
The picker appears in the Layout view.
Select the newly inserted picker and define the following properties using the Properties view:
control
Name of the picker control file.
name
A unique identifier for the control.
Press Enter to confirm your selections.
Click the Save button
to save your changes.

The typeahead picker is added to the form. Users can use this control when the form is used as a portlet in a NexJ application.