Extensions: Documentation And Source Code PopClip Extensions
PopClip extensions add extra actions to PopClip.
This repository contains the documentation for making your individual extensions (this readme file) as well as the source files for the extensions published on the primary PopClip Extensions page.
All extension source files are published under the MIT License (see LICENSE) unless noted otherwise within the readme files of individual extensions.
All the extensions and documentation were created by Nick Moore, except where stated. Contributor credits are are shown within the readme file of each individual extension.
Thanks for contributing! Contributors, please note the following:
– By contributing to this repo, you agree that your contribution could also be published at PopClip Extensions.
– I will choose which extensions to publish at my sole discretion, and that i may make changes to any extension.
– Don’t fret about signing the extension. I’ll take care of that.
For an easy approach to create certain types of extension with no coding necessary, take a look at Brett Terpstra’s PopMaker app.
Listed here are some external “how you can” guides for creating extensions:
Create Your personal Custom Extension for PopClip (Tuts+)
PopClip: Scripting Extensions (Tuts+)
These instructions are designed to help a technically competent person to create their own PopClip extension. Please note that user-created extensions will not be an officially supported a part of PopClip. You should be comfortable with creating and editing plist files, scripts, and so forth.
I reserve the precise to alter or remove features in future versions of PopClip at any time.
By default, PopClip will display a warning dialog once you try to put in your own extension, because it’s not digitally signed by Pilotmoon Software.
If you find this gets annoying while you are testing your work, you can turn off the warning. Run the following command at the Terminal, then Quit and restart PopClip:
Please remember that PopClip extensions can contain arbitrary executable scripts. Watch out in regards to the extensions you create, and be wary about loading extensions you get from another person. Proceed at your own risk.
Extra Debugging Output
That can assist you when debugging Script extensions, PopClip may be configure to jot down script output and debug info to the console. To enable it, run this command in Terminal:
Sorts of Actions
There are five main kinds of actions supported by PopClip extensions.
All extensions have access to the following filtering mechanisms, to help prevent them appearing when they don’t seem to be useful:
– Filter by matching a regular expression.
– Filter by application (either include or exclude).
– Filter by whether cut, copy or paste is accessible.
– Filter by whether the text contains a URL, email address or file path.
Anatomy of a PopClip Extension
About .popclipextz files
For distribution on the PopClip Extensions page, extensions are zipped and renamed with the extension .popclipextz. You’ll be able to examine an existing PopClip extension by renaming it with a .zip extension and unzipping it, to reveal a .popclipext package.
The .popclipext package
A PopClip extension consists of a property list called Config.plist, plus (optional) additional files such as the icon and any required scripts, all contained in a directory whose name ends with .popclipext. Such a directory will probably be treated as a package by Mac OS X. To view the contents of a package, right click it in Finder and choose ‘Show Package Contents’.
For those who double-click a .popclipext package, PopClip will attempt to load and install it. PopClip stores its installed extensions in ~/Library/Application Support/PopClip/Extensions/.
Here is an example package structure, using the ‘Say’ extension:
Every extension must contain a Config.plist file. This must be in Apple Property List format. The plist contains information in regards to the extension, and also defines a number of actions. You possibly can generate a blank plist with Xcode or a dedicated plist editor corresponding to PlistEdit Pro. Alternatively, use certainly one of the existing extensions as a basis and edit with a text editor
Example plist: ExampleConfig.plist.
Here is an example plist for ‘Translate Tab’, as viewed in Xcode:
Extensions may include icons to represent actions. The icon is displayed in the PopClip popup itself, and in addition in the preferences window and on the net site (if published). Icons may be created in any graphics program; I take advantage of Pixelmator.
For best results, the icon should be a square PNG file at the very least 256×256 pixels in size. The image should encompass a black figure on a transparent background. You should utilize opacity to attain ‘shades of grey’.
For instance, here is the full-size icon file for ‘Sort’:
– All key names are case sensitive.
– Make sure that you set each field the proper type. A typical why wont error is to enter a number as a string type.
“String or Dictionary” type
Fields with the sort “String or Dictionary” can take either a String or Dictionary value. For those who supply a string value, that string is always 4pcs/pack Virgin Indian Straight Weave Pure Human Indian Human Hair Natural Color used. Alternatively, you’ll be able to supply a dictionary mapping language code (en, fr, etc.) to a string. PopClip will display the suitable string for the user’s preferred language if possible, with fallback to the en string.
Common reasons for malformed XML are:
– Missing end tags
– Mismatched start and end tags
– Unescaped & characters (& must be endoded as &)
The Config.plist file has the following structure.
Each action dictionary has the following structure. Exactly certainly one of Service Name, AppleScript File, Shell Script File, URL or Key Combo needs to be specified.
These are the values supported by the requirements field. Additionally, you’ll be able to prefix any requirement with ! to negate it. For example, !paste should you only want the action to appear when Paste shouldn’t be available.
Before and After keys
These are the values supported by the Before and After fields.
Options are presented to the user in a preferences window and are saved by PopClip’s preferences on behalf of the extension. Each option dictionary has the next structure.
These strings can be found in Shell Script and AppleScript extensions. Where no value is available, the sector will be set to an empty string.
Only one in every of Bundle Identifier or Bundle Identifiers is required, not both.
Example AppleScript File
Important: AppleScript files have to be in UTF-8 plain text format. (Save as ‘text’ format in AppleScript editor.)
Here is an example of an AppleScript file to be used in an extension (this one is for sending to Evernote):
Example Shell Script File
Here is an example of an shell script to be used in an extension (this one is for ‘Say’):
Script Returning Result
Scripts can return results in the event that they specify one of many *-result or show-status keys in the Action’s After field.
Scripts should indicate success or failure as follows. If the script indicates a failure with settings, it will cause the extension’s options window to seem (if it has one).
Here is an example of a Ruby script that might be utilized in a shell script extension (with the Script Interpreter set to /usr/bin/ruby) and the After key set to paste-result.
See also the Uppercase extension for a working example.
Key Code format
Key presses needs to be expressed as a dictionary with the next keys:
Note: Exactly considered one of keyChar or keyCode must be specified. Not both.