Create Your Own Custom Extension for PopClip

PopClip is one of our favourite apps on Mactuts+ and one of the reasons why is its support for extensions. You can perform actions on selected text using PopClip that makes it extremely versatile, whether you want to open a link in another browser, search for the selected text in Google or add it as a to-do to Things, PopClip provides an iOS-style pop-up menu that makes doing these tasks easy.

In this tutorial, I’ll be demonstrating just how easy it is to create your own extension for PopClip to perform a custom action.

What Is PopClip?

PopClip provides an iOS-style menu that can be further customised with extensions

PopClip ($4.99) is an app for OS X that provides an iOS-like pop-up menu when selecting text. It’s main use is for cut, copy and paste - again, very similar to iOS. Where it really gets interesting is the ability to install extensions to do more than just add to the clipboard.

At time of writing, there were over 92 extensions available to download for free. These extensions range from opening a link in a Google Chrome, post selected text to Facebook, add quotation marks around selected text and more.

Tip: There are many extensions and I encourage you to take a look, all of which can be found at the PopClip extension page.

I use PopClip regularly and use an extension for adding selected text to Things, my to-do app of choice.

How They’re Built

PopClip supports extensions written in a number of different ways:

Mac OS X Service
AppleScript
Shell Script
URL
Keypress

Both URL and Keypress require no programming knowledge to create them. As long as you know a site’s URL that can include some text or to press a certain combination of keys, then you can create your own extension.

The remaining three are created using scripting languages. They can manipulate text in a more advanced way. For the purposes of this tutorial, I’ll be creating an extension using the URL method.

A URL extension requires only two files, our extension configuration file and an icon to display within the pop-up menu when we select some text.

Building Our Own

There’s a great selection of extensions that we can use but there may not be one that exactly suits our needs. As an example, I’m going to show you how to build a PopClip extension that can search Mactuts+ for the selected text.

To do this, I won’t be showing you how to build one from scratch but, instead, we’ll be using some of the sample code provided by the developer and making changes to it to suit our needs. This will give you a good idea of how the extension works and what changes we’d need to make to start creating our own extensions.

Tip: We’re only going to need a text editor to make changes. TextEdit isn’t ideal for editing code so I’d recommend something like TextWrangler which is not only a great app but it’s free, too!

1. Create a Folder

You can create this folder anywhere as it will just be somewhere to work from for now

On your desktop (or wherever you’d like), create a folder called mactuts. This is where we will store our extension files before we turn it into a proper PopClip extension.

2. Download Source Code

At the PopClip Extension developer site, we’re able to download some example source code. Under the heading General Overview, you’ll see the types of actions that PopClip supports. We want to download the example code for the URL action, which is the source code for the Google Translate extension.

You’ll see two files within the view, the Config.plist and TranslationIcon.png. We’re only interested in the Config file.

Here is what the code looks like when it's opened/pasted into a text editor (in this case, TextMate)

The main configuration file of an extension is what’s known as a Property List file, otherwise known as a Plist. You may have heard of them before as it’s the same file type that OS X uses to store preferences for applications. It is based upon a format known as XML. Take a few minutes to familiarise yourself with the format.

Look familiar? XML is designed to work in a similar way to HTML, the markup language used to build web pages.

Tip: If you’d like to know more about Property Lists, Apple’s Developer Library has a great introductory article you can read

If you’re unfamiliar with GitHub, you can download the extension directly. (Right-click the link and select Download File As…, saving it to the mactuts folder we created earlier).

3. Let’s Edit!

By now you should have saved the Config.plist file to your mactuts folder. Let’s edit that file within a text editor.

As you've seen, this file has a number of different configurable options. You’ll notice than an option is called a Key. These tell PopClip that the extension is able to provide certain information. We won’t be changing any keys, but instead we’ll be modifying the information within.

Step 1

The first thing we'll change is the name of the extension — The first thing we'll change is the name and description of the extension

First of all, we need to change our Extension Name and Extension Description. Find the line that has the key for this and change the name that’s in the string below, currently written as “Google Translate” accordingly. Remember, don’t change the key.

Now that you’ve changed the name of the extension, let’s change the description to better reflect what it does. Using the same steps as above, change the description to better describe what our Mactuts+ search extension will do. I’ll leave it to you to decide what to write.

Step 2

We'll also need to update the version as this is the first Mactuts extension ever!

Now, since this is the first time we’ll be creating this extension, let’s make it version 1. Location the version number near the top of the file and change this from 2 to 1.

You may have noticed that, unlike the name of the extension, this is something called an Integer and not String. Integer just means you’re only specifying a number, so no letters or special characters.

Step 3

The identifier needs to be changed as it is unique to each extension and developer

Each extension needs a unique way of being identified. Rather than using it’s name, it uses a special identifier which looks like a domain name written in reverse. In this source code, you’ll see it written as follows:

com.pilotmoon.popclip.extension.google-translate

Change this to the following:

com.mactuts.extension.mactuts-search

Even if we changed the name of the extension, PopClip would still get this confused if we had our extension and the Google Translate extension installed at the same time.

Step 4

Now it’s time to control how the extension actually works. Our extension will search Mactuts+ for the text that you’ve selected. To do this, we need to know what our search address is.

Open a new tab or window with Mactuts+ loaded and search for the keyword “TEST”. Once the search is complete, take a look at the address bar. You should see the following address:

https://computers.tutsplus.com

From this, we can see that we the search address is:

https://computers.tutsplus.com

You can test this out by entering the above address and then any keyword you’d like into your browser’s address bar. Once the page loads, you’ll see the search you wanted.

PopClip uses the text {popclip text} as a placeholder for the text you’ve selected. What this means is that the search address for our extension will be:

https://computers.tutsplus.com{popclip text}

We'll now change the URL that PopClip opens (with the selected text) to search Mactuts+

This search address is what will power our extension. In the Config file, change the String that’s under the section for URL to the above.

Step 5

Our icon that PopClip uses needs to be a 256px square with a transparent background and a solid area in black

With the main search feature configured, we need to add an icon. The icon needs to be a square 256px transparent PNG. To save time, I’ve included one with the source file that you can download and use.

Add this (or your own) icon to your mactuts folder. I’ve named the icon I’ve provided MactutsIcon.png.

Once we've added a new image, we need to update the Config file with the new name

Back to the Config file, we need to change the name of the Image File to the one we’re now using.

Step 6

Finally, change the title of the extension and remove the "key" and "string" for "Regular Expression"

Change the title of the pop-up from “Translate” to “Mactuts+”. Additionally, remove the Key and String related to Regular Expression. This is an optional extra that we do not require.

Step 7

Our extension is now ready to go. In order to begin using it, we need to convert it into a PopClip extension. All PopClip extensions are actually just specially named folders. There’s no conversion tool or command-line trickery to do.

Duplicate the folder we've been working with and rename it, adding ".popclipext" to the end

First of all duplicate the folder. With the newly duplicated folder, rename it to mactuts.popclipext. The Finder will prompt you to confirm you’d like to rename it.

You'll be asked if you're sure you want to add a file extension to the duplicated folder

4. Install and Test The Extension

PopClip will warn that this extension isn't signed, meaning it wasn't approved by the developer. As it's brand new, that's ok

Once converted, double-click the newly created extension file to install. You’ll receive a warning from PopClip explaining that this isn’t an approved extension. Don’t worry, this just means that we’re wanting to install an extension that wasn’t from the developer’s website. Confirm you’d like to install it and then the extension will install. Once installed, you’ll see it in the list of extensions that PopClip has active. At the bottom of the list will be our newly developed Mactuts+ extension!

Once installed, PopClip will display our new extension in the menu

Now to test it out. Highlight some text anywhere and when PopClip appears, you should now see our Mactuts+ search button display.

Selecting text will display the PopClip menu... along with our new extension!

Clicking it will open a new tab or window (or even launch) your default browser and open directly to the search results page for the what you selected.

When selected, PopClip will open a new tab with the selected text searched on Mactuts+

Wrapping Up

By the end of this tutorial, I’d hope that you’ve been able to learn a lot from it and begin to start building more advanced extensions. The PopClip extension developer page on GitHub provides you with source code for all types of extensions so you can see exactly how they work.

Since building an extension for PopClip can be incredibly easy, you might not need to wait for someone to develop an extension you’ve been waiting for, you may be able to build it for yourself!