LaunchBar 6 is an application launcher that can be extended with actions. In previous versions of LaunchBar, actions were written in AppleScript. With LaunchBar 6, any scripting language can be used, but the preferred language is JavaScript.
In this tutorial, I’ll show you how to create your own actions in JavaScript to extend the functionality of LaunchBar. Therefore, a working knowledge of JavaScript is expected. The article Become a Professional JavaScript Developer With Tuts+ Courses can help you get started with JavaScript.
If you want to learn about the interface with LaunchBar 6, you can read the LaunchBar 6 Action Documentation.
The application that this action will interact with is FoldingText. FoldingText is a great markdown editor with a lot of extensibility. You should check out the tutorial, Customizing FoldingText, to see how to customize FoldingText to fit your needs.
In order to communicate with FoldingText, I’ll show you how to make use of Apple’s new JavaScript for Automation instead of AppleScript. You can read JavaScript for Automation Documentation to help you get started with the language.
Making an Action
To start making an action, you have to create a directory with the .lbaction extension.
In Finder, right click in a directory and select New Folder name the new directory FoldingTextAddToTag.lbaction. It will no longer look like a directory in Finder. LaunchBar registers that extension with OS X to treat it as a special file type. It is still a directory, but you move it around like a file.
To view the contents again, right click on the directory and select Show Package Contents.
Once inside the action package, all of the files and directories that make up an action are viewable.
The basic structure of an action can be seen with the tree command. The tree command is a standard Unix command for graphically displaying a directory structure. You can install it with HomeBrew with the command:
brew install tree
You then view a directory with tree <directory name>.
To create the structure for a new action, create a Contents directory with sub-directories of Resources and Scripts. In the top directory, a Readme.md file needs to be created with a description of the action in Markdown format.
Next, an icon for the action is placed in the Resources directory. Just use the one in the download and place it there.
In the Contents directory, the Info.plist file needs to be created. This file tells LaunchBar how to use the action. In that file, place the following:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>CFBundleIdentifier</key>
<string>com.customct.launchbar.FoldingTextAddToTag</string>
<key>CFBundleName</key>
<string>FT-AddToTag</string>
<key>CFBundleVersion</key>
<string>1.0</string>
<key>CFBundleIconFile</key>
<string>icon</string>
<key>LBDebugLogEnabled</key>
<false />
<!-- Per-action keys -->
<key>LBTextInputTitle</key>
<string>ft:addtag</string>
<key>LBScripts</key>
<dict>
<key>LBDefaultScript</key>
<dict>
<key>LBLiveFeedbackEnabled</key>
<true/>
<key>LBRequiresArgument</key>
<true/>
<key>LBReturnsResult</key>
<true/>
<key>LBRunInBackground</key>
<false/>
<key>LBScriptName</key>
<string>default.js</string>
</dict>
</dict>
<key>LBDescription</key>
<dict>
<key>LBAuthor</key>
<string>Richard Guay</string>
<key>LBWebsite</key>
<string>http://customct.com</string>
<key>LBEmail</key>
<string>raguay@customct.com</string>
<key>LBTwitter</key>
<string>@CustomComputerT</string>
<!-- A short summary about what the action does and how it’s used. -->
<key>LBSummary</key>
<string>This allows the adding of a message to an arbitary tag in the topmost document.</string>
<!-- Describe the arguments that should be passed to the action. For example, if
your action’s default script specifies that it accepts paths via
LBAcceptedArgumentTypes, but then the script itself checks that the user
passed in a PDF file, this would be the right place to document that. -->
<key>LBArgument</key>
<string>It takes a tag name and a note to attach to the tag.</string>
<!-- Describe the action’s result. For example, an action fetching news via RSS
that then shows a list of items representing the single stories in the RSS
feed could document here that the resulting items represent the news
articles. -->
<key>LBResult</key>
<string>Adds a message to a tag in FoldingText.</string>
<!-- Describe any further requirements for your action to work, e.g. if it
requires an active internet connection, iTunes to be playing a song, or
a certain version of an app to be installed. -->
<key>LBRequirements</key>
<string>None</string>
</dict>
</dict>
</plist>
This is a text plist that is editable with any text editor. The different keys tell LaunchBar what to do with the action. The minimum keys are:
CFBundleIdentifier
This key gives a unique identifier for the action. In order to insure uniqueness, I use a reverse DNS of my website with the program name and action name.
CFBundleName
This key gives a name for the action. This is shown in the actions list dialog for enabling/disabling.
CFBundleVersion
This key gives the version number for the action. For this action it will be 1.0.
CFBundleIconFile
This key gives the name of the icon file in the Resources directory of the action. The file type is not given.
LBDebugLogEnabled
This key is a boolean that determines the state of logging. This should be turned off with a false value.
LBTextInputTitle
This key is the name that the user will use to call the action from LaunchBar. It is ft:addtotag. As the user starts to type, LaunchBar will list all actions and files that start to match it. Most often, you just have to type ft:a or addto to get to this action.
LBScripts
This key starts another dictionary of terms for the previous LBTextInputTitle key. The next six keys are in this dictionary to describe how the action works.
LBDefaultScript
This starts the action script definition dictionary. The next five keys are in this dictionary.
LBLiveFeedbackEnabled
This boolean key tells LaunchBar whether or not the script will give live feedback. Live feedback is a list of options to select from in LaunchBar. This action will be providing a list of tag names to select from. Therefore, this should be true.
LBRequiresArgument
This boolean key tells LaunchBar if this action requires an argument. Again, this action needs the message to add to the tag. Therefore, it will be true.
LBReturnsResult
This boolean key tells LaunchBar if this action will be returning any results. Since this action has live feedback, this also needs to be true.
LBRunInBackground
Some actions will simply launch something and can be done in the background so that LaunchBar does not need to wait on it or record it’s output. For this action, this key will be false.
LBScriptName
This key tells LaunchBar the name of the script to execute. The script has to be in the Scripts subdirectory.
LBDescription
This key starts the last dictionary that describes the author of the action and various pieces of information about the action. Some of this is displayed to the user when the action in installed. These keys are very self-explanatory.
With this plist file in place and the icon in the Resources directory, the main part of the action can be created. Open the Scripts sub-directory and create a file named default.js. Place the following in it:
//
// Function: run
//
// Description: This function is called by LaunchBar whenever the action is called without a string.
// It creates a menu that LaunchBar will give to the user. The menu items list
// actual functions to call to cause an action to happen in FoldingText. Simply call
// the runWithString is an empty string.
//
function run() {
runWithString("");
}
//
// Function: runWithString
//
// Description: This function is called by LaunchBar whenever the action is called with a string.
// It creates a menu that LaunchBar will give to the user. The menu items list
// actual functions to call to cause an action to happen in FoldingText.
//
// Inputs:
// string A string given by the user.
//
function runWithString(string) {
//
// Create variables that will be used.
//
var result = [];
string = string.trim();
//
// Get a list of tags from the current document.
//
var tags = getTagsFromDocument().split(",");
//
// This function should be called to produce a new list. Create it.
//
//
// Foreach tag, add an menu entry as a child.
//
tags.forEach(function(item){
//
// This adds to the AddToTag command.
//
result.push({
title: item,
subtitle: "FoldingText: Add to Tag",
icon: "icon",
action: 'addToTag',
actionArgument: item.trim() + "|" + string,
actionRunsInBackground: true,
actionReturnsItems: false
});
});
//
// Return the resulting menu list.
//
return(result);
}
//
// function: getTagsFromDocument
//
// Description: This function will use an osascript to query the topmost FoldingText
// document for a list of tags. This list is returned to the calling
// routine.
//
function getTagsFromDocument() {
var result = LaunchBar.execute("/usr/bin/osascript", "getListOfTags.scpt");
return(result);
}
//
// function: addToTag
//
// Description: This function will use an osascript to add a user supplied string
// to the first tag of the type given to the script. The information
// given to the script is "tag|text" where tag is a tag and text is
// the text to be added.
//
function addToTag(obj) {
LaunchBar.execute("/usr/bin/osascript","notetag.scpt",obj.toString());
}
This script has four functions two are required by LaunchBar and two helper functions. LaunchBar requires all actions to define a run() function that is called when there is no input from the user, and runWithString() function that takes a string argument of what the user types. The run() function simply calls the runWithString() function with an empty string.
The runWithString() function gets a list of tags from the top most FoldingText document by using the helper function getTagsFromDocument(). For each tag, a structure of information is created containing the information LaunchBar needs to display the results. The structure elements are:
title
This gives a unique title to each sub-action. It is the name of the tag to attach the message.
subtitle
This is the subtitle for the sub-action. I have set it to the name of the action that created this sub-action.
icon
Each sub-action can have a different icon, but this action doesn’t need it.
action
This tells LaunchBar the name of the function to call if this sub-action is selected. For this action, all calls go to the addToTag() function.
actionArgument
This defines the argument sent to the function defined in action. The tag name is concatenated with the input from the user. The addToTag() function will this parses this string to get the tag name and the message to add to the tag.
actionRunsInBackground
This boolean field is true so that LaunchBar does not wait for the function to return. That allows the user to go to another task quickly.
actionReturnsItems
This is false so that LaunchBar will not collect the output from the function call.
The last two functions call JavaScript for Automation scripts that are stored in the Scripts directory. Those functions call a command line program by using LaunchBar’s special command LaunchBar.execute().
Create a file called getListOfTags.scpt and open it in Script Editor. In this file, place the following code:
function run(arg) {
app = Application("FoldingText");
doc = app.documents[0];
if( doc != null ) {
return doc.evaluate({ script: "function(editor) { return editor.tree().tags(true).sort(); }" });
}
}
When a JavaScript for Automation file is ran with the osascript interpreter, it will call the run() function with anything that is added to the command line passed as a string to it.
This code will get an Application object for FoldingText program. This is the same as tell application... in AppleScript. It then uses that application object to query about the topmost document. If there is a topmost document, the function gives it a JavaScript program to evaluate that will return all the tags in that document. Those tags are then returned to the command line.
The second script is called notetag.scpt with this code:
function run(arg) {
app = Application("FoldingText");
doc = app.documents[0];
if( doc != null ) {
return doc.evaluate({ script: "function(editor, options) { var tree=editor.tree(), q = options.toString().trim().split('|'), result=''; var tag = q[0], q = q[1]; var tnode=editor.tree().evaluateNodePath('//@'+tag)[0]; if(tnode) { var message = tree.createNode(q); tnode.appendChild(message); } else { result = 'No ' + tag + ' Found.'; } return(result); }", withOptions: arg });
}
}
This is the same as the previous script, except for the JavaScript passed to evaluate command. This JavaScript will parse the input argument to a tag and message. It then tells FoldingText to add the message to that tag in the document.
Loading and Running the Action
Once all these pieces are in place, simply double click on the FoldingTextAddToTag.lbaction file. OS X will automatically load it into LaunchBar.
When you select Install, the action will be added to the actions used by LaunchBar.
To run the action, activate LaunchBar and type addtotag and the action will show up. Selecting it shows a list of tags in the topmost FoldingText document and a text box. Put a message in the textbox and select a tag. The given message will be added to the tag.
Conclusion
This tutorial demonstrates how to write LaunchBar actions using JavaScript and JavaScript for Automation. Now that you know how to do it, start practicing by making more actions.
