Advanced Extension Guide

In this Tutorial I will show how you can create your own extensions. You may need a little technical experience to be able to achive what you want. Also there are some limitations on what you can create given the restrictions of the operating system.

 

Overview

Each extension consists of a folder with files in it. The folder than gets compressed and given file extension ".pbar" so that the compressed folder gets opened in SnipDo. If you want to see how the existing extensions are made of, simply rename the file extension from ".pbar" to ".zip", unpack it and look at the contents.

The folder HAS to have one file containg all the extension properties in it. This file has to be a JSON formatted file with file extension ".json" and it defines the extension. You can generate json files with your favourite Text Editor or an online Editor to check your syntax.

A file defines an object of type extension. An extension can have multiple Actions. An Actions shows up as one button in SnipDo 

The following tables shows the properties in the .json file. 

 

Extension definition

Key

Type

Description

Notes

namestring (required)Name of the extension

 

identifierstring (required)An unique id for this extension (f.e myextension.myname) 
actionsList<Actions> (required)A list of available Actions See Action definition below
iconstringname of the icon (f.e. "icon.png")Place icon in same folder
extensionTranslationsDictionary<string, string>Translations for extension name 
requiredAppVersionstringMinimum required App versionfull version required (f.e. 1.5.3.0)
requiredOSVersionstringMinimum required Operating System versionDefinition here (Major version .Minor version )

 

Action definition

Key

Type

Description

Notes

titlestring (required)Title of the action

 

iconstringname of the action (f.e. "icon.png")Place icon in same folder
actionTranslationsDictionary<string, string>Translations for action title 
urlstringUrl to open in default browser 
powershellFilestringPowershell file to executePlace powershell file in same folder
keyCombostringKey (combo) to pressDefinition here
afterstringAn action can perform an event after it has been executed. This is mainly used by powershell files (see below)

values:

PASTE_RESULT

SHOW_RESULT

SHOW_SUCCESS

COPY_RESULT

longRunningboolshows a spinning circle to indicate the action takes time 
optionsList<AppOption>Options available for user to configure actionSee AppOption definition below
regexstringShow action only if the text satisfies this regular expression 
requirementsList<string>Show action only if the text satisfies the listed requirements

values:

HAS_URL

IS_URL

EMAIL

FILEPATH

noShowAppsList<string>Process names where the action does not show requires app version 1.5.4.0
showOnlyAppsList<string>Process names where the action only shows requires app version 1.5.4.0

Each action is one of several available action types. If one of these keys is set the other action types will be ignored.

These types are:

  • Open Url
  • Press Key(s)
  • Execute Powershell script

 

Open URL action

The URL specified will be opened in the default browser. To pass the text to the URL simply add one of the following string to it (including brackets):

  • {PANTHERBAR_PLAIN_TEXT} 
  • {PANTHERBAR_URLENCODED_TEXT}
  • {PANTHERBAR_URLENCODED_ALT_TEXT}
  • {PANTHERBAR_HTMLENCODED_TEXT}
  • {APPOPTION IDENTIFIER}

 

PANTHERBAR_PLAIN_TEXT passes the text plain, PANTHERBAR_URLENCODED_TEXT passes the text in the URL format, PANTHERBAR_URLENCODED_ALT_TEXT also encodes in URL format but uses %20 for the space character (instead of + sign) PANTHERBAR_HTMLENCODED_TEXT passes the text in the HTML format

APPOPTION IDENTIFIER passes the value the user set for the AppOption (see below for more infos on AppOptions)

 

Press Key(s)

Specify a Keycombination string as specifed in this Microsoft Docs. , The combination will be send to the active window when the action is executed.

 

Execute Powershell script

When defining a Powershell script, SnipDo passes several paramters to the script. The paramters are:

  • PLAIN_TEXT (string)
  • URLENCODED_TEXT (string)
  • HTMLENCODED_TEXT (string)
  • URLS (string[])
  • APPOPTION_IDENTIFIER (string)

 

You can access these paramters in the scripts like this:

param(
[string[]] $URLS
[string] $PLAIN_TEXT 
)

SnipDo uses the Powershell output pipeline to get results from the script. If you want to signal an error to SnipDo use:

Write-Error "Error message"

If one error is seen by SnipDo, it will show a red cross signaling an error to the user. If you want to pass a successfull value to SnipDo use.

Write-Output "This string is passed to SnipDo"

If you want to use external Assemblies in the script place them in the same folder as the script file and add a reference to them using:

Add-Type -Path $PSScriptRoot\assembly.dll

 

 

AppOption definition:

Key

Type

Description

Notes

identifierstring (required)An unique id for this option 
valuesDictionary<string, string>A list of texts, the user can choose from 
powershellFilestringname of the powershell option filePlace file in same folder

 

When defining an option, the user has to set an option before executing the action. An option can either be a

  • list of strings (f.e. www.google.com, www.google.de, www.google.es) wich  the user has to choose from
  • powershellfile

 

List of strings

User is asked to choose one of the specified string. The user will only see the key of the dictionary entry. SnipDo will pass the value of the entry to the Url action respectively the Powershell script file.

 

Powershell File

You can specifiy a Powershell file to set a value that can be used in an action. Use the output pileline to signal SnipDo to save a value using:

Write-Output "This string is saved and passed to the action using the appoption identifier"