Extensions

Version : 2.0.0
Modification Date : 13.10.2020

Please Note: The extension-system of MarkMyWords relies on the scripting-languages Perl, PHP, Python and Ruby. These scripting-languages are currently included by default in the macOS-installation. However, Apple stated that future versions of macOS won't include scripting-languages and it is unclear if future versions of macOS will provide any reliable options for applications, like MarkMyWords, to interact with scripting languages.

With extensions you can enhance the feature-set of MarkMyWords to your very own needs. To activate an extension you can either select the specific extension from the main-menu under the item Extensions or from the Toolbar using the popup-button Extensions.

To manage your installed extensions call up the Extension Manager from the main-menu under Window > Extension Manager. The Extension Manager allows you to install, create new extensions and to remove existing extensions.

Developing extensions for MarkMyWords

Advice

The Extension Manager should be used to create extensions, as it considerably simplifies the creation of new extensions and minimizes errors.

Note: The following descriptions are assuming you're using PHP as the programming-language for developing your extension. However, MarkMyWords also supports Perl, Python and Ruby.

The package

Every extension for MarkMyWords is a simple folder with the extension mmwxtz. An ordinary extension contains three files:

The script

The main-script for the extension must be named script.php. You can add additional scripts to the main-script by simply including them in the main-script.
Handling output: The output is a simple string-output, an example for PHP:

<?php
// your cool code
echo "The result is correct";
?>

In this case the returned value of this extension would be : The result is correct.

Handling errors: MarkMyWords can catch error-messages from your extension. To display the error messages is as easy as displaying the result, just prepend Error: before your message. An example for PHP:

<?php
if($result == true){
	// Your cool code here
}
else{
	$message = "Error: This didn't work, try again!";
}
echo $message;
?>

The Plist

The script.plist-file is the heart of the extension and is it important to set the values correctly. Therefore it is suggested to use the Extension Manager, which takes care of the correct values.
To create the plist by hand, the easiest way is to use the Apple Property List Editor from the Developer Package, but you can also edit the plist-file with a normal text-editor (for example MarkMyWords). Just take an existing script-plist-file and change its values to your needs. Following values are available:

Plist-Properties

Property Description Required Values
MMWCreator name of the developer NO Text
MMWCreatorHomepage developer website NO Text
MMWExtensionName the name of the extension YES Text
MMWExtensionDescription a short description of the extension NO Text
MMWVersionNumber the version of the extension NO Text
MMWScriptLanguage the language used by the extension YES php, ruby, perl, python
MMWInputOption tells MarkMyWords which type of input shall be sent to the extension-script YES See table MMWInputOption-values
MMWSupplementOption tells MarkMyWords, if additional infos shall be added to be sent to the extension-script YES See table MMWSupplementOption-values
MMWSupplementOptionMessage add a message, which should be displayed, when the supplement-sheet is called, so the user knows why this sheet appears YES Text
MMWSupplementPresetValue adds a pre-set string to the supplement-textfield NO Text
MMWOutputOption tells MarkMyWords how the result of the execution shall be presented to the user YES See table MMWOutputOption-values

MMWInputOption-values

Value Description
none no input will be sent
fulltext the full text of the current document will be sent
selection the selected text of the document will be sent
filename the filename of the current document will be sent
JSON a JSON-Array containing all previous details and some more (see JSON-Array for specific details)

MMWSupplementOption-values

Value Description
none no further input required
string user can write an additional text which can be used for the execution
file user can choose a file which pathname will be supplied to the execution
folder user can choose a folder which pathname will be supplied to the execution

MMWOutputOption-values

Value Description
message displays the result in a message-sheet
sheet displays the result in a sheet with options: insert at selection, copy to pasteboard
append appends the result to the current document
prepend prepends the result to the current document
selection replaces the current selection of the current document with the result, or when no text is selected, inserts the result at the current cursor-position
fulltext replaces the text of the current document with the result

The JSON-Input-Option

The JSON-input-option is the most versatile option providing various details about the current document to your extension.
Code-example that reads in the JSON-array and lists the attachment-filepaths of the current document:

<?php
$fp = fopen("php://stdin", "r");
while($line = fgets($fp, 1024)){
	$input .= $line;
}
fclose($fp);
$result = json_decode($input, true);
echo "Attachments:\n";
for($i = 0; $i < count($result['Attachments']); $i++){
	echo "* ".$result['Attachments'][$i]."\n";
}

Key Description
Attachments Array of Filepaths to the Attachments of the current document
ColorLabel Integer-value of the set Color-Label of the current document (0 = none, 1 = gray, 2 = green, 3 = purple, 4 = blue, 5 = yellow, 6 = red, 7 = orange)
FileName Filepath of the current document
FullText Text of the current document
HTML Converted text of the current document
SelectedText Selected text of the current document
Tags Array of Strings containing set Finder-Tags

Accessing the input values

When developing the extension, you'll probably require access to the input values. While the regular input is provided as a stream of text, the supplement option is an additional argument when executing the script.

The following code is an example to read in the input:


$input = "";
// open the stdin textstream
$fp = fopen("php://stdin", "r");
// reading the current line to the end
while($line = fgets($fp, 1024)){	
	// appending the read in line
	$input .= $line;
}
fclose($fp);
Accessing the supplement-option is showed in the following example:

$supplement = $argv[1];

$argv is a global variable in PHP and contains the provided arguments when starting to execute a script of an extension.

The icon

The icon is a simple PNG-Image-file. It should be squared and the dimensions should be at least 128 x 128 pixels.