ThingWorx AutoComplete Widget Extension User Guide

Transcription

1 ThingWorx AutoComplete Widget Extension User Guide Version 1.1

2 Table of Contents Introduction and Installation... 3 About the Autocomplete Widget Extension... 3 Extension Changelog:... 3 Installing the Autocomplete Widget Extension... 4 Autocomplete Widget Extension: Configuration and Use... 5 Configuration... 5 Usage... 7 Known Limitations and Compatibility Document Revision History... 10

3 Introduction and Installation Extensibility is a core aspect of the architecture and design of ThingWorx. Partners, third parties, and users, as well as ThingWorx can easily add new functionality into the system in a seamless manner. Extensions can be Service (function/method) libraries, Connector Templates, Widgets, and more. This document provides installation and usage instructions for the Autocomplete Widget Extension. About the Autocomplete Widget Extension The Autocomplete Widget provides a Mashup Widget which allows a user to view a list of suggestions in a textbox, which updates continuously while typing. The search is performed on the Server side, based on the input provided. This extension utilizes the jquery UI Core JavaScript library. For more information, visit the following link Extension Changelog: Version Changes 1.0 Initial Release 1.1 Resolved the following bugs: 1. Autocomplete extension appears underneath the modal mashup on the parent mashup 2. Date and navigation arrows on the date pop-up disappear after importing the autocomplete widget 3

4 Installing the Autocomplete Widget Extension 1. From a web browser, launch ThingWorx. 2. Log into ThingWorx as an administrator. 3. Go to Import/Export > Import. 4. Click Choose File and select Autocomplete.zip 5. Click Import. Note: If an Import Successful message does not display, contact your ThingWorx System Administrator. Note: 6. Click Yes to refresh Composer after importing the final extension. 4

5 Autocomplete Widget Extension: Configuration and Use Usage of the Autocomplete Widget Extension requires dropping the widget in the page and setting the necessary bindings. Configuration The AutoComplete has a Properties page in the ThingWorx Mashup Builder when an AutoComplete widget is placed in a layout. The properties section will appear similar to the image below: The available properties are the following: MinimumLength: sets the minimum number of characters after which the widget will fire the TextChanged event. Default is 3, can be modified as desired, but specific testing should be done in order to ensure that the widget is responsive, considering it relies on a search Service on the server side. You want to avoid setting this property to 1. Doing so will make the search service take a long time, because there will always be a lot of matches for a single character.

6 Changed Text: this is an output-type property, which should be used to send the currently typed text from the search box to the input of the Search service. This property is read-only and is used in conjunction with the TextChanged event. SelectedText: this is an output-type property, which sends the text that was selected from the suggestion list to the server. Note that depending on the SendValueAsSelected checkbox, this text can be the DisplayField column OR the ValueField column. AutoFocus: automatically focuses the selection box on the first item on the suggestion list. Data: The returned Search Suggestions (autocomplete suggestions) from the SearchThings (or similar) service. This is the main requirement for AutoComplete. Data should be in the form of an Infotable containing the data that will be used as a source for the suggestion list. This list should be a result of the search Service running on the server, as the widget does not perform any local (client-side) search. A diagram better explaining this will be shown on the Usage section, below. DisplayField: the column from the Data Infotable which will be displayed to the user in the suggestion list. ValueField: the column from the Data Infotable which will be used as the SelectedText. ONLY used when the SendValueAsSelected is checked. SendValueAsSelected: whenever this checkbox is checked, the SelectedText property will take the value of the column which is set in the ValueField. 6

7 Usage The AutoComplete Widget can be added to any mashup. There are three pieces to its connection that need to be completed: 1. The Widget s Data input needs to be bound to the output of the service which performs your search (see example code below). 2. The Widget s TextChanged event needs to be bound to the execution of the service which performs your search. 3. The Widget s ChangedText binding target needs to be bound to the input of the service which performs your search. In addition to these connections, your service which performs the actual search needs to have its output data set as an INFOTABLE, and assigned a DataShape as well. The DataShape you use should be one created from the resultant output of your service. (In other words, test run your search service with the output set to Infotable, and then click Create DataShape from Result. Save this newly created DataShape, and then assign it to your service as shown below: Note: Please see the sample code on page 4 to get started writing your service. 7

8 The end result, in your mashup, will look like this as you type: You can set maxitems in the service to limit the amount of items which are displayed. A diagram representing a typical usage scenario is presented on page 4. In this scenario, when we select a result from the Suggestion List, that text will be used by the LogWrite service to write a log entry in the platform, for the purpose of demonstrating how it works. The user may use that term as an input for any kind of logic he desires. You can see that there is a Service called SearchThings, which expects one input parameter, called searchterm. Make sure that your service also returns data of type infotable (see the sample service below for more information). In the mashup, the searchterm is bound to the TextChanged event. The TextChanged event triggers the SearchThings service (this will happen each time the user inputs a character in the search box). This service will be triggered many times during a normal session, so special care should be taken in order for it to see it the search service does not stress the server too much. 8

9 The content of the SearchThings service used in order to generate the above output is: if (!searchterm) searchterm=""; var query = { "filters": { "fieldname": "name", "type": "LIKE", "value": "*"+searchterm+"*" } }; var params = { maxitems: 10 /* NUMBER */, namemask: undefined /* STRING */, query: query /* QUERY */, thingtemplate: "GenericThing" /* THINGTEMPLATENAME */, tags: undefined /* TAGS */ }; // result: INFOTABLE datashape: RootEntityList var result = Resources["SearchFunctions"].SearchThingsByTemplate(params); Please note that a wildcard type search is implemented in the Service, not on the widget. You may use this service as a starting point for modifying the AutoComplete widget to suit your needs. 9

10 Known Limitations and Compatibility The current version of the Autocomplete Widget Extension has a known limitation that is summarized below. ThingWorx is currently addressing this limitation. Known Limitations Item No Resizing Description Even if the Control is marked as responsive, it will not fill its container. This Extension has been tested for compatibility with the following: ThingWorx Platform Version ThingWorx OS Windows 7, Service Pack 1 Java Java JRE 8, Update 45 ` Document Revision History Revision Date Version Description of Change September Initial Release September 16, Updated document template, added information concerning bug fixes and proper usage 10