Advertisement
  1. Computer Skills
  2. Launchbar
Computers

Creating LaunchBar 6 Actions

by
Difficulty:AdvancedLength:LongLanguages:

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.

Creating the Actions Directory
Creating the Action's Directory

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.

Showing the Directory Contents
Showing the Directory Contents

To view the contents again, right click on the directory and select Show Package Contents.

Action Contents
Action Contents

Once inside the action package, all of the files and directories that make up an action are viewable.

Tree View of an Action
Tree View of an Action

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:

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:

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:

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:

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.

Loading the Action
Loading the Action

When you select Install, the action will be added to the actions used by LaunchBar.

Running the Action
Running the Action

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.




Advertisement
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.