Livesearch

Live Search is a search/auto-complete component for text input fields. The component may be configured for input fields on 3 levels:

JForm element: for fields on a specific form (highest priority)
Application: global, for all matching fields within an Aperio application
Client : global for the Aperio client installation (lowest priority)

On application and client level, the live search is configured via JSON file (livesearch.json), for:

application - in the application folder (/app-name)
client - in the client’s configuration folder (/cfg)

The structure of the configuration file

There are two main properties:

settings: list of attributes that configure the behaviour of the live search component
fields: list of field definitions that will have the live search

Example of ’livesearch.json’ file:

{
  "settings": { "maxItems": 50 },
  "fields": {
    "field1": { "method": "searchMethod.get" }
  }
}

Live Search settings

Here is the list of Live Search attributes

Attribute	Description	Default	Example
startLength	The minimum number of characters a user must type before a search is performed	2	`"startLength": 3`
maxItems	Maximum number of items to search for and to display. If there are more available the last one will show ‘…’	50	`"maxItem": 75`
delay	The delay in millisecond between when a keystroke occurs and when a search is performed	200	`"delay": 500`
labelAutoFields	The number of fields from the search response that will be used to construct a label for each item	3	`"labelAutoFields": 2`
labelSeparator	The separator string that will be used between fields in the label	“ ”	`“labelSeparator”: "

Live Search field declaration

Each field declaration consists of field ID and its attributes like: method name to call, parameters etc. The field ID may contain simple regular expression wildcard characters:

'*' : which will be substituted by a string (may be empty). Example: "*Product" will match all field names such as: demoProduct, testProduct etc.
'?' : which will be substituted by a single character (may be blank). Example: "item?" will match all field names such as: item1, item2 etc.

Here is the list of all Live Search field attributes

Attribute	Description	Default	Example
method	The name of the API method to run the search (mandatory)		`"method": "items.get"`
params	The list of method parameters. Text values (in double quotes) are treated as expressions. This way it is possible to reference form fields. For example `"name":"field1"` will send parameter ’name’ with a value from field ‘field1’ and `"text":"'abcd'"` will send text “abcd” in parameter ’text’		`"params": { "type": 1, "customer": "custField", "text": "'abcd'" }`
searchParam	When provided, the search term will be send as method parameter (given by the attribute) instead of sending it in the controls section of the API request (freeTextSearch)	auto	`"searchParam": "searchText"`
label	An array of field names that will be used to construct item labels. If not provided, the first n-fields from the response will be used (see `labelAutoFields` setting)	auto	`"label": ["code", "name", "addressLine1"]`
value	The name of the response field that will be used as source for the input field when selecting an item. If not provided, then the first field from the response will be used	auto	`"value": "itemCode"`
preload	Under construction	false	`"preload": true`

Example of ’livesearch.json’ file

{
  "settings": {
    "labelSeparator": " | " 
  },

  "fields": {

    "*product*": { 
      "method": "searchMethod.get" 
    },

    "item*": { 
      "method": "items.get",
      "searchParam": "searchText" 
    },

    "businessPartner": { 
      "method": "businessPartners.get",
      "params": { "type": 1 },
      "label": [ "name", "description" ],
      "value": "code" 
    }
  }
}

Live Search field declaration in JForm

Live Search may be enabled directly on the JForm input element. Use livesearch attribute to describe the properties of the search field. The properties are the same as described in “Live Search field declaration” section.

Example of a form input element with Live Search

{ "id": "businessPartner", "text": "Customer", "length": 30, "type": "text", 
    "livesearch":{
      "method": "businessPartners.get",            
      "params": { "type": 1 }
    }
}