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.