Skip to content

Config

Every extension is defined by a configuration dictionary. This can be provided either by a snippet or a package, but in each case the underlying structure is the same.

Key names

PopClip is very flexible about how you name keys. In this documentation you'll mostly see keys named in lowercase with spaces, for example key name. However, PopClip will treat Key Name, keyName, KeyName, key_name, key-name and KEY_NAME as equivalents.

I tend to use key name in YAML, and keyName in JSON, but you can use whatever you prefer.

Example

Before diving in to the details, let's look at an example config dictionary for a published extension. This is based on the Yoink extension:

json
{
  "identifier": "at.EternalStorms.Yoink.PopClipExtension",
  "popclipVersion": 3785,
  "name": "Yoink",
  "icon": "yoink.png",
  "app": {
    "name": "Yoink",
    "link": "https://eternalstorms.at/yoink/mac",
    "checkInstalled": true,
    "bundleIdentifiers": [
      "at.EternalStorms.Yoink",
      "at.EternalStorms.Yoink-setapp",
      "at.EternalStorms.Yoink-demo"
    ]
  },
  "serviceName": "Add Selected Text to Yoink",
  "captureHtml": true,
  "description": "Add the selected text to Yoink."
}
yaml
identifier: at.EternalStorms.Yoink.PopClipExtension
popclip version: 3785
name: Yoink
icon: yoink.png
app:
  name: Yoink
  link: https://eternalstorms.at/yoink/mac
  check installed: true
  bundle identifiers:
    - at.EternalStorms.Yoink
    - at.EternalStorms.Yoink-setapp
    - at.EternalStorms.Yoink-demo
service name: Add Selected Text to Yoink
capture html: true
description: Add the selected text to Yoink.

Not all of those fields are strictly needed. As we have already seen in Snippets, we can also express a similar extension very minimally, at the loss of some of the niceties that the fleshed-out version provides:

json
{
  "name": "Yoink",
  "serviceName": "Add Selected Text to Yoink"
}
yaml
name: Yoink
service name: Add Selected Text to Yoink

Minimal or maximal?

In general, if you're writing an extension for your own use, you can freely omit any fields that you don't need. But if you're preparing an extension for publication, you should flesh out the config as much as possible, to provide the best user experience for your extension.

Top level properties

The following keys are used at the top level of the config to define properties of the extension itself. All properties are optional except name.

KeyTypeDescription
name (Required)String (Localizable)A short, human-readable display name for this extension.
iconStringSee Icons. If you omit this field, the icon for the first action will be used (if any), or else no icon will be displayed.
identifierStringYou may provide a string to uniquely identify this extension. See The identifier field.
descriptionString (Localizable)A short, human readable description of this extension. Appears in the directory but not in the app.
macos versionStringMinimum version number of Mac OS X needed by this extension. For example 10.8.2 or 11.0.
popclip versionIntegerMinimum PopClip version required. This is the integer build number e.g. 4151. Specifying the current PopClip version here can help preserve your extension's functionality in future, because PopClip applies backward-compatibility rules for old extensions.
optionsArrayArray of dictionaries defining the options for this extension, if any. See The options array.
options titleString (Localizable)Title to appear at the top of the options window. Default is Options for <extension name>.
entitlementsArrayOnly applies to JavaScript extensions. The possible values are network (allows use of XMLHttpRequest) and dynamic (allows dynamically generated actions).
action or actionsDictionary or ArrayA dictionary or array of dictionaries defining the action(s) for this extension. See Actions.

The identifier field

An identifier may contain only alphanumeric characters (A-Z, a-z, 0-9), period (.), and hyphen (-).

A good identifier should be globally unique so as not to clash with other creators. Use your own prefix, which could be a reverse DNS-style prefix based on a domain name you control, such as com.example.myextension. Alternatively, just pick something likely to be unique to you.

If you don't provide an identifier, PopClip will identify the extension by the package directory name (e.g. Name.popclipext) if it's a package extension, or the name if it's a snippet.

Reserved identifier

The identifier prefix com.pilotmoon. is reserved for signed extensions published by me. If you try to use it for your own extensions, you'll get an error.

The options array

Options are presented to the user in a preferences user interface window and are saved in PopClip's preferences on behalf of the extension. Options appear in the UI in the order they appear in the options array. An option dictionary has the following structure.

KeyTypeRequired?Description
identifierStringRequiredIdentifying string for this option. This is passed to your script. The identifier will be downcased or upcased for AppleScript and Shell Script targets, respectively — see Script variables.
typeStringRequiredSee Option types.
labelString (Localizable)OptionalThe label to appear in the UI for this option. If omitted, the identifier is displayed.
descriptionString (Localizable)OptionalA longer description to appear in the UI to explain this option.
default valueStringOptionalThis field specifies the default value of the option. If omitted, string options default to the empty string, boolean options default to true, and multiple options default to the top item in the list. A password field may not have a default value.
valuesArrayRequired for multiple typeArray of strings representing the possible values for the multiple choice option.
value labelsArrayOptionalArray of "human friendly" strings corresponding to the multiple choice values. This is used only in the PopClip options UI, and is not passed to the script. If omitted, the option values themselves are shown.
insetBooleanOptionalIf true, the option field will be shown inset to the right of the label, instead of under it. Default is false.
iconStringOptionalFor boolean options only. Specify an icon to appear next to the check box.

Option types

The type field of an option dictionary can be one of the following:

TypeDescription
stringA text field.
booleanA checkbox.
multipleA multiple choice list. The values field must be provided.
secretConcealed text entry. The value persisted in the keychain.
headingActs as a heading to group options together.

Config notes

Localized strings

Fields shown as "String (Localizable)" type may be either a string or a dictionary. If you supply a string, that string is always used. Alternatively, you can supply a dictionary mapping language codes to strings, and PopClip will display the string for the user's preferred language if possible, with fallback to the en string, which is always required.

The following language codes are supported:

Language codes table
Language CodeLanguage Name
enEnglish
en-gbEnglish (UK)
daDanish
deGerman
esSpanish
frFrench
itItalian
jaJapanese
koKorean
nlDutch
plPolish
pt-brPortuguese (BR)
ruRussian
skSlovak
trTurkish
viVietnamese
zh-hansChinese (Simplified)
zh-hantChinese (Traditional)

Example of localized string

yaml
name: 
  en: My Extension
  fr: Mon Extension
  zh-hans: 我的扩展

Null values in Plist

Plist does not have a native way to represent the null value of JSON and YAML. Use <false /> in a Plist where you would use null in JSON or YAML.

Key name mapping

Some field names were different in older versions of PopClip. Others have alternative allowable spellings.

To preserve backwards compatibility, key names in the config are transformed as follows:

  1. First, the naming convention is standardized to lowercase with spaces. For example, RequiredApps becomes required apps.

  2. Then, if the field name has the prefix extension or option (which were expected by older versions of PopClip), it is removed.

  3. Finally, PopClip applies the following mapping:

Key name mapping table
Alternative nameCanonical name
apple scriptapplescript
apple script callapplescript call
apple script fileapplescript file
blocked appsexcluded apps
flip horizontalflip x
flip verticalflip y
ididentifier
image fileicon
java scriptjavascript
java script filejavascript file
jsjavascript
langlanguage
mac os versionmacos version
paramsparameters
pass htmlcapture html
pop clip versionpopclip version
preserve image colorpreserve color
regular expressionregex
required os versionmacos version
required software versionpopclip version
script interpreterinterpreter

Example

An old extension uses the key Extension Image File to define its icon. PopClip will first standardize the case to extension image file. Then it will remove the extension prefix, leaving image file. Then it will map this to icon.