TypeScript and Omni Automation in BBEdit
With the installation of the TypeScript components, you are ready to set up your development environment and BBEdit.
Setting up your Development Environment
When using TypeScript and TypeScript Server as tools for creating plug-ins, think of yourself as a “Plug-In Developer” who has dedicated some disk space to use as their “Plug-In Workshop.”
This “Plug-In Workshop” folder will contain:
- Any required TypeScript Server support files (tsconfig.json)
- Application TypeScript definition files (“.d.ts”) for each of the Omni applications for which you wish to create plug-ins.
- Any Omni Automation plug-in files you are in the process of developing. NOTE: In order to be checked by the TypeScript Server for errors, these plug-in files must use the file extension of “.ts” instead of the standard Omni plug-in file extensions: omnijs, omnifocusjs, omnigrafflejs, omniplanjs, or omnioutlinerjs
| DO THIS ► | DOWNLOAD the example development folder containing the necessary resources for developing plug-ins for OmniFocus 3. Place the folder in your Documents folder. |
Here are links to download the TypeScript Definition files for each of the Omni applications:
Preparing BBEdit
There are a couple things to do to prepare BBEdit 14 for use with TypeScript and Omni Automation:
1) Allow Sandbox Access to BBEdit so that the provided AppleScript script can write to the various Omni plug-in folders.
If Sandbox Access in the BBEdit application preferences has not previously been enabled, enable it now.
1 Application Preferences • Select “Application” in the preferences categories list.
2 Sandbox Access Settings • The current Sandbox Access settings. If it reads “Sandbox access: allowed” you’re all set, otherwise…
3 Enable Access Button • Press this button to approve Sandbox Access for BBEdit.
2) Install the provided AppleScript script in the BBEdit Scripts folder.
In BBEdit, select the “Open Scripts Folder” option from the Scripts menu. The folder will open on the desktop. Move the provided “OmniFocus Plug-In Install.scpt” file from the downloaded “Omni Automation Plug-In Development” folder into the BBEdit Scripts folder opened on the desktop.
Close the folder, and the script will now be available within BBEdit.
The “OmniFocus Plug-In Install” script is designed to export a copy of the current Omni Automation plug-in that you are editing in BBEdit to the default local OmniFocus plug-ins folder. The export file will automatically be given the file extension of “omnifocusjs” so that it is recognized by OmniFocus as a plug-in.
So the basic concept for plug-in development is that you work on a TypeScript version of the plug-in, that you export to the OmniFocus plug-ins folder.
NOTE: The first run of the script may trigger the following security dialog requiring your approval for BBEdit to run a script controlling the Finder:
Click “OK” to allow the script to proceed.
File Settings in BBEdit
After you’ve opened an Omni Automation plug-in file in BBEdit (after confirming that the file extension of the plug-in file is “.ts”) you may need to set the language type popup at the bottom of the window to TypeScript:
Ready for Use
You are now ready to use TypeScript Server to provide code completion and error checking for your plug-in code in BBEdit!
Open the provided example plug-in file “all-hello-world.ts” in BBEdit.
Dealing with an Error
One of the lines of code in the plug-in is triggering an error warning by highlighting its corresponding line number.
Click once on the highlighted line number to reveal the error message:
NOTE: (see above) the command show() is underlined in the code statement, indicating that it is the cause of the error:
Holding down the Command Key (⌘), double-click on the term: show
The OmniFocus TypeScript dictionary file “omnifocus.d.ts” will be opened, showing the Alert class definition with show highlighted (see below):
(see above) The red-underlined section of the entry indicates that the show() command takes either a Function or null as the value of its callback parameter. The show() in the code is missing this value, thereby triggering the error.
In BBEdit, switch back to displaying the plug-in file. (all-hello-world.ts)
Add “null” (no quotes) as the parameter for show() in the code.
The error will be resolved and no longer be triggered to display:
Install and Run the Plug-In
Run the previously installed AppleScript script “OmniFocus Plug-In Install” and the plug-in code will be written to a new file in the local OmniFocus Plug-Ins folder.
Switch to OmniFocus and run the script from the Automation menu by selecting the menu option “TypeScript Plug-In”:
