Spotlight Search Prompt
EXAMPLES:
The best way to see how to use the Spotlight Search Prompt is to examine and run the Example macros.
After you've looked at the examples, you can refer to this document for more detailed information.
REQUIRED VARIABLES:
Before calling the Spotlight Search Prompt macro, you must populate two variables:
á sspOptions
á sspData
sspOptions:
Defines the various options. Example:
title: My Title
placeholder: Select an item
helpMacroUUID: 4429D2F8-4663-44A6-A2F6-A531ABE71D93
dataType: json
jsonDisplayField: name
jsonReturnField: value
jsonAdditionalSearchFields: keyword1, keyword2
NOTE: There's a "template" action near the start of the "Spotlight Search Prompt" macro that you can copy and paste as needed.
Option Name |
Description |
--<comment> |
All lines that start with "--" are considered comments and are ignored. Blank lines are ignored also. |
title |
Required. The title that will appear in the Prompt. |
dataType |
Required. The type of data that will be used to populate the pick list. Must be one of the following: |
strings |
The data is plain text, one item per line. |
dict |
The data is in the "dictionary" format of key=value, one item per line. "value" is what gets displayed. "key" is what gets returned when the user selects something. |
json |
The data is in the "dictionary" format of key=value, one item per line. "value" is what gets displayed. "key" is what gets returned when the user selects something. |
jsonDisplayField |
Specifies what field in the JSON data should be displayed in the list. |
jsonReturnField |
Specifies what field in the JSON data should be returned. |
jsonAdditionalSearchFields |
If specified, this can contain the names of one or more fields in the JSON data that will also be searched, although the fields' values won't be displayed. Specify multiple fields by separating their names with commas. Each of these fields in the JSON data can contain a single value, or an array of values. |
jsonStatusLineFields |
Optional. See " jsonStatusLine options, below. |
jsonStatusLineTemplate |
|
jsonStatusLineFunction |
|
placeholder |
Optional. The light-gray text that shows when nothing's been entered. |
helpMacroUUID |
Optional. If you have a macro that displays Help information for this prompt, then specify the macro's UUID here. The prompt will include a Help button, and if the user clicks it, the specified macro will be launched. |
cancelMacroIfCancelClicked |
Optional, default true. Normally, if the user clicks the Cancel button (or presses Escape), the macro terminates. If you want the macro to continue, passing back to you the fact the user pressed Cancel, then specify "true" for this option. |
customButtonText |
Optional. See "Custom Button", below. |
customButtonSubmitResultButton |
|
customButtonTriggerMacroUUID |
|
customButtonEnabledWithoutSelection |
|
customPromptWidth |
Optional. See "Custom Prompt Size", below. |
customPickListSize |
Optional. See "Custom Prompt Size", below. Note that if either jsonStatusLineTemplate or jsonStatusLineFunction is defined, the actual value used is 1 less than what's specified here. |
saveWindowPositionVariableName |
Optional. The name of the variable that should be used to store the prompt window's position. If not specified, sspWindowPosition will be used. |
sspData:
This must contain the data used for the pick list. It can contain 3 different formats of data, depending on the value of dataType in sspOptions.
strings
One item per line. This is what's displayed, it's what is searched, and it's what is returned.
Alan Shaw
Earl Morris
Margaret Jacobs
Joshua King
Pamela Stanley
George Perkins
Steven Ruiz
Anne Gonzalez
Scott Hernandez
Shawn Hernandez
dict
"Dictionary" format of key=value. In the example below, the names are displayed, the numbers are returned.
1=Alan Shaw
2=Earl Morris
3=Margaret Jacobs
4=Joshua King
5=Pamela Stanley
6=George Perkins
7=Steven Ruiz
8=Anne Gonzalez
9=Scott Hernandez
10=Shawn Hernandez
json
Example:
sspOptions (partial):
dataType: json
jsonDisplayField: name
jsonReturnField: value
jsonAdditionalSearchFields: keyword1, keyword2
sspData:
[
{
"value": 1,
"name": "Ashley Harris",
},
{
"value": 2,
"name": "Douglas Vasquez",
"keyword1": "雪丽"
},
{
"value": 3,
"name": "Carlos Anderson",
"keyword2": [
"8/28/2015",
"10/16/2015"
]
},
{
"value": 4,
"name": "Christopher Diaz",
"keyword1": [
"雅芙",
"梓彤"
],
"keyword2": "7/19/2016"
}
]
In the above example, name is displayed, value is returned, and Spotlight searches name, keyword1, and keyword2.
Notice that in the above example for the second item, keyword1 contains a single value. But in the fourth item, it contains multiple values. Spotlight works just fine with data like this.
jsonStatusLine options:
If you want, you can have information about the currently-selected item displayed in a Status Line. Here's an example:
jsonStatusLineFields: city, state
jsonStatusLineTemplate: Location: $1, $2
jsonStatusLineFields contains the names of one or more JSON fields that supply the data for the status line.
Use jsonStatusLineTemplate or jsonStatusLineFunction to indicate how to display the data on the status line.
If you use jsonStatusLineTemplate, use $1, $2, etc. to specify where the field values should be placed. $1 for the first field specified in jsonStatusLineFields, $2 for the next, etc.
If you use jsonStatusLineFunction, you would do something like this:
Set a variable to a JavaScript anonymous function, like this:
1. Set a variable to an anonymous JavaScript function, like this:
function(fieldValues) {
if (!fieldValues)
return "";
return "Location: " +
fieldValues.city + ", " +
fieldValues.state;
}
fieldValues will be null if nothing is selected. Otherwise it will contain the values of the fields specified in jsonStatusLineFields.
2. Modify the variable so there are no newlines. Use a "Search and Replace Variable" action using regular expressions. Specify [\r\n\t]+ for the search value. Replace with a single space.
3. Use the variable in setting sspOptions, like this:
jsonStatusLineFields: city, state
jsonStatusLineFunction: %Variable%sspStatusLineFunction%
Here's an image of the entire process:
The above example is from the macro Spotlight Search Prompt Example 5: json (3).
Custom Button:
If desired, you can specify an additional "custom" button, using these options:
customButtonText: text
-plus-
customButtonSubmitResultButton: text
-or
customButtonTriggerMacroUUID: macro UUID
If you specify customButtonText, then you must specify one and only one of the following options:
á customButtonSubmitResultButton
o The dialog will be submitted, and whatever you place in this option will be returned in sspResultButton.
á customButtonTriggerMacroUUID
o When the custom button is clicked, the macro with this UUID will be triggered.
Additionally, you can set customButtonEnabledWithoutSelection to "true" or "1" if you want to be able to click you custom button even if nothing is selected.
Custom Prompt Size:
If desired, you can specify custom values for the prompt's width and/or height and the list size, in these options:
customPromptWidth: 400
customPickListListSize: 15
Note that if jsonStatusLineTemplate is defined, the actual value used for customPickListListSize is 1 less than what's specified here.
The width value is fairly obvious - it's the width in pixels of the prompt window.
"customPickListListSize" is the number of PickList items that are visible in the window before the PickList starts scrolling.
If you see two vertical Scroll Bars:
If you see two vertical Scroll Bars, like this:
Éthere's an action in the "Spotlight Search Prompt" macro that you can adjust. It looks like this:
If it's only off by a little, increase "Prompt Height without the PickList" (149, above) until it looks right. If it's off by a lot, you probably need to increase "Item Height" (17, above). It's possible you may need to do a combination of both.
RETURNS:
á sspResult: The selection the user made, or blank if they didn't select anything or they canceled.
á sspResultButton: The Button that was clicked. OK, Cancel, or customButtonSubmitResultButton if specified.