HoudahSpot icon

How-to: Customize the HoudahSpot LaunchBar Action

Objective Development’s LaunchBar is an adaptive app launcher, document browser, and much more.

HoudahSpot is a powerful file search tool. It takes the guesswork out of Spotlight searches and helps you find files hidden deep in the “haystack” of files accumulated over the years.

HoudahSpot 5 includes a LaunchBar action that provides an elegant way to start a HoudahSpot search using LaunchBar. You can install this action from HoudahSpot > Preferences > Extensions.

Screenshot: LaunchBar in action
Start a file search from LaunchBar 6

The action is selected by typing the hs abbreviation in LaunchBar.

The action accepts text input. Select the action in LaunchBar and press the space key to start entering text. The action will start a HoudahSpot search with the text.

The action alternatively accepts a folder location. Select the action in LaunchBar and press the return key. You will be asked to select a folder. The action will open a new HoudahSpot search focussed on the selected location.

The LaunchBar action installed by HoudahSpot uses your default search setup: the search criteria, location, result columns, and sort order that you have defined as the default for new windows.

Custom Action: Search Apple Mail Messages

You can create versions of the action that instead use one of your search templates. For this post, we will adapt the LaunchBar action search Apple Mail messages.

Start by opening the LaunchBar Action Editor. In LaunchBar, select Launch Bar > Action Editor… from the menu.

Select the Search HoudahSpot action that you have previously installed from HoudahSpot > Preferences > Extensions.

Use the File > Duplicate Action command to create a copy of the action. Name the new action: Search Mail Messages.

Screenshot: File > Duplicate Action
Create a copy of the HoudahSpot LaunchBar action: Search Apple Mail Messages

Assign a new abbreviation. We will use: hms. Typing this abbreviation in LaunchBar will bring up the action.

You may also want to update the summary, version, and other information in the General tab.

Switch to the Scripts tab. Here you configure the script that will run when you invoke the action.

A Bit of AppleScript

Click the Edit button. We will modify the AppleScript that was copied from the original action.

Searching for files – in this case, Apple Mail messages – uses the handle_string portion of the script. The script builds a URL that includes the text entered in LaunchBar. It then opens that URL. This makes HoudahSpot open a new window with the text inserted in the main search field.

HoudahSpot then searches for files matching the text you have entered. With the factory default setup, this searches any text attribute (e.g. name, text content, author, tags, etc.) of files. You may have customized your default setup to search only names or text content.

The URL currently uses only one parameter: q or query. We will add a t or template parameter to make HoudahSpot use a search template instead of the default setup. The value of this parameter is the path of the template we want to use.

HoudahSpot includes a sample template to search Apple Mail messages. We will point our script at that template. The script conveniently already includes a way of URL-encoding parameter values. This encodes spaces and other special characters in a form that is safe to include in URLs.

Our script now reads:

on handle_string(theString)
	open location "houdahspot4://search?q=" & urlEncode(theString) & "&t=" & urlEncode("~/Library/Application Support/com.houdah.HoudahSpot4/Sample Templates HS5/Apple Mail Messages.hstemplate")
end handle_string

When we later use the action and type “Steve Jobs” in LaunchBar, the script will build and open the following URL:

houdahspot4://search?q=Steve%20Jobs&t=~/Library/Application%20Support/com.houdah.HoudahSpot4/Sample%20Templates%20HS5/Apple%20Mail%20Messages.hstemplate

Ready to Use

Close the Action Editor and give your new action a try:

  1. Invoke LaunchBar
  2. Type your abbreviation: hms
  3. Press the Space bar
  4. Type your search text
  5. Press the Return key

Not working? Download the Search Mail Messages action and compare it to your version.

Power Users

Ready for more? Refer to the HoudahSpot User Guide for more details on the different parameters supported by the houdahspot4:// URL scheme.

The user guide also describes advanced uses of the main search field. Since the text passed by the query parameter is inserted into that search field, you can have the script build a URL that creates such an advanced search from text you will enter in LaunchBar.

The following, for example, can start a case sensitive search:

on handle_string(theString)
 open location "houdahspot4://search?q=" & urlEncode("*:\"" & theString & "\"dwt")
end handle_string