Creating Your Own Look-up Service
A data source query look-up service is a web service that responds to requests by returning JSON data in a specified format. There are two types of service:
-
A list service that has a single end point and returns a list of values. The Widget Framework then carries out the actual look-up operation using the returned list.
-
An active service that does the look-up itself and returns a list that matches the characters entered (so far) by the user. An active service has two end points, for performing different types of look-up.
A list service is simpler to implement and is fine if the collection of objects to look up is relatively small. For look-ups involving very large object collections, it is probably better to create an active service that does most of the work on the server.
Defining a list service
A list service has a single endpoint (for example:
https://mycompany.com/webservice/recipes/search
),
and responds by returning a JSON file of the following form:
{"lookUpInfo":[ { "value":"apple-pie-1", "label":"Apple Pie", "summary": "Just like Mom used to make it" }, { "value":"apple-pie-2", "label":"Apple Pie with chili", "summary": "For the jaded palate" }, ... ]}
The Widget Framework retrieves this list from the web service the first time it is needed in a Content Studio session, and caches it. It then uses the cached copy to perform the necessary look-ups when the Content Studio user starts typing in the query form look-up field. The values in the JSON file are used as follows:
value
-
is the value that will actually be stored in the field
label
-
is matched against the characters entered by the user and displayed in the field when the user finally makes a selection
summary
-
is optional. If present, summaries are displayed below the labels in the list of options shown while the user is typing in the field
If the user opens a query form in which a look-up field already contains a value, then the Widget Framework uses the same list to look up the label it needs to display in the field.
Defining an active service
An active service has two endpoints, and the last part of each endpoint URL is used as a look-up string. For example:
https://mycompany.com/webservice/recipes/search/{term}
, andhttps://mycompany.com/webservice/recipes/name/{value}
Each time the user types a character in the look-up field, the
contents of the field are used to replace {term}
,
and the
Widget Framework
sends a GET
request to the resulting URL. Every
time the service receives such a request it is expected to use
submitted term as a look-up string and return a JSON file. This file
has the same structure as the JSON file returned by a list service,
but instead of containing containing only entries where
label
matches the supplied characters. As the
user types more characters, the JSON structure returned will
therefore get shorter. The returned structure is used to display a
list of options from which the user can pick the required value.
The second {value}
endpoint is used when the user
opens a query form in which a look-up field already contains a
value. The
Widget Framework
then replaces {value}
with the field value and
sends a GET
request to the resulting URL. The
service is expected to respond by returning a JSON structure
containing a single record, thereby providing the correct label to
display in the field.
If, for example, the
Widget Framework
sent a request to
https://mycompany.com/webservice/recipes/name/apple-pie-2
,
then the response might be:
{ "value":"apple-pie-2", "label":"Apple Pie with chili", "summary": "For the jaded palate" }
The Widget Framework API includes a LookUpInfoclass that you may find helpful in implementing an active lookup service in Java: it provides various useful methods for manipulating and comparing look-up service JSON structures. If you want to use this class then you should add the following dependency to your service's POM file:
<dependency> <groupId>com.escenic.widget-framework</groupId> <artifactId>wf-webservice</artifactId> <version>4.5.2-2</version> <classifier>lib</classifier> </dependency>