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

name string (required) Name of the extension

 

identifier string (required) An unique id for this extension (f.e myextension.myname)  
actions List<Actions> (required) A list of available Actions  See Action definition below
icon string name of the icon (f.e. "icon.png") Place icon in same folder
extensionTranslations Dictionary<string, string> Translations for extension name  
requiredAppVersion string Minimum required App version full version required (f.e. 1.5.3.0)
requiredOSVersion string Minimum required Operating System version Definition here (Major version .Minor version )

 

Action definition

Key

Type

Description

Notes

title string (required) Title of the action

 

icon string name of the action (f.e. "icon.png") Place icon in same folder
actionTranslations Dictionary<string, string> Translations for action title  
url string Url to open in default browser  
powershellFile string Powershell file to execute Place powershell file in same folder
keyCombo string Key (combo) to press Definition here
after string An 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

longRunning bool shows a spinning circle to indicate the action takes time  
options List<AppOption> Options available for user to configure action See AppOption definition below
regex string Show action only if the text satisfies this regular expression  
requirements List<string> Show action only if the text satisfies the listed requirements

values:

HAS_URL

IS_URL

EMAIL

FILEPATH

noShowApps List<string> Process names where the action does not show requires app version 1.5.4.0
showOnlyApps List<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

identifier string (required) An unique id for this option  
values Dictionary<string, string> A list of texts, the user can choose from  
powershellFile string name of the powershell option file Place 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"