Extensions

Version: 3.0.0
Date: 01.01.2024
updated for macOS 14 Sonoma

Scripting languages: The MarkMyWords extension system has supported various script languages since its introduction. However, the script languages supported in macOS have been increasingly restricted with more recent versions. Of the originally supported languages Perl, Ruby, PHP and Python, none can be used from macOS 12 onwards by default. If you are using macOS 12 or higher, Javascript is recommended
Note PHP in macOS 12 or newer: The PHP scripting language can be used if a corresponding PHP parser is set up and activated for MarkMyWords. More information on this topic can be found in the chapter: Using your own PHP interpreter.
Note Perl and Ruby in macOS 12 or newer: In order to use these two scripting languages, the installation of the Xcode Command Line Tools is required. These tools can by installed with the Terminal app by entering the command "xcode-select --install",
Note Python in macOS 12 or newer: Due to new Sandbox-Restrictions, Python can't be used in macOS 12 or newer for MarkMyWords Extensions.
Note Javascript: As of version 2.9.0 of MarkMyWords, the Javascript scripting language can also be used to develop extensions. Since the use of Javascript and its execution is natively supported by macOS without additional interpreters, the further development of the extension system will primarily take place for this scripting language.
Note on this document: The PHP scripting language is currently used for many examples. These examples are also symbolically informative for the other languages. In future versions of MarkMyWords, however, more attention will be paid to the scripting language Javascript.

Extensions can be used to extend the functionality of MarkMyWords to suit your own needs. To activate an extension, it can be quickly selected and executed either in the main menu under Extensions or in the toolbar via the pop-up button Extensions.

To manage the installed extensions, the Extension Manager can be called up via the main menu under Window > Extension Manager. The Extension Manager can be used to install extensions, create new extensions and edit or remove existing extensions.

Development of extensions for MarkMyWords

Recommendation

The Extension Manager should be used to create extensions, as it considerably simplifies the creation of new extensions and minimizes errors, as various elements of the extension are created automatically.

Note: The following descriptions assume that PHP is used as the programming language for the development of the extension. However, MarkMyWords also supports Javascript, Perl and Ruby as well as Python in older macOS versions.

The MarkMyWords extension site

The MarkMyWords extension site provides various example extensions and core samples for Javascript, Perl, PHP, Python and Ruby, which can be used as inspiration or as a starting point for developing your own extension.

The package

Each extension for MarkMyWords is a simple folder with the extension mmwxtz. A normal extension contains three files:

The script

The main script for the extension must be called script.php.
Additional scripts can be added as a file in the extension package and included accordingly.
Note: This does not apply to extensions that are developed with Javascript.
Processing the output: The result is a simple string output, an example for PHP:
<?php
	// your cool code
	echo „The result is correct“;
?>

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

Error handling: MarkMyWords can intercept error messages from the extension. Displaying the error messages is as easy as displaying the result, simply add Error: in front of the corresponding 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 it is important that the values are set correctly. It is therefore advisable to use the Extension Manager, which takes care of the correct values.
To create the plist file by hand, it is easiest to use the Apple Property List Editor from the Developer Package, but the plist file can also be edited with a normal text editor (e.g. MarkMyWords). To do this, simply use an existing script.plist file and adapt its values to your own requirements. The following values are available:

Plist properties

Property Description Required align=„center“ Values
MMWCreator developer name NO Text
MMWCreatorHomepage developer’s 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 javascript, php, ruby, perl, python
MMWInputOption tells MarkMyWords what kind of input should be sent to the extension script YES see table MMWInputOption values
MMWSupplementOption tells MarkMyWords whether additional information should be sent to the extension script YES See table MMWSupplementOption values
MMWSupplementOptionMessage adds a message to be displayed when the supplement sheet is called so that the user knows why this dialog appears YES Text
MMWSupplementPresetValue inserts a preset string into the supplement text field NO Text
MMWOutputOption tells MarkMyWords how the result of the execution should be presented to the user YES See table MMWOutputOption values

MMWInputOption-Values

Value Description
none no input is sent
fulltext the entire text of the current document is sent
selection the selected text of the document is sent
filename the file name of the current document is sent
JSON a JSON array containing all the previous entries and some more (see JSON array for specific entries))

MMWSupplementOption-Values

Value Description
none no further input required
string the user can enter an additional text that can be used for the execution
file the user can select a file whose path name is passed to the execution
folder the user can select a folder whose path name is passed to the execution

MMWOutputOption-Values

Value Description
message displays the result in an info dialog
sheet displays the result in a dialog, with the options: paste to selection, copy to clipboard
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 inserts the result at the current cursor position if no text is selected
fulltext replaces the text of the current document with the result

The JSON supplement option

The JSON supplement option is the most versatile option that provides your extension with various details about the current document.
Code example that reads the JSON array and lists the file paths of the attachments 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 file paths to the attachments of the current document
ColorLabel Integer value of the color label set for the current document (0 = none, 1 = grey, 2 = green, 3 = purple, 4 = blue, 5 = yellow, 6 = red, 7 = orange)
FileName File path 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

Access to the input values

Note: The following text refers to the PHP scripting language. The corresponding procedure for the Perl, Python and Ruby languages can be found in the core examples. For the Javascript scripting language, the necessary information is available in a separate chapter under „Javascript-specific functions and variables“.
When developing the extension, access to the input values is required in most cases. While the regular input is provided as a text stream, the additional option is an additional argument when executing the script.

The following code is an example of reading the input values:

<?php
	$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);
?>

Access to the supplement option is shown in the following example:

<?php
	$supplement = $argv[1];
?>

$argv is a global variable in PHP and contains the specified arguments when an extension script is to be executed.

Javascript-specific functions and variables

The Javascript scripting language has its own variables for accessing input and supplement values as well as additional functions that make it easier to read and write external data.

Global variables

(String) MJS_Var_Input This variable contains the value that was defined as input in the script.plist (see table MMWInputOption values for the possible options)

(String) MJS_Var_Supplement This variable contains the value that was defined as a supplement in the script.plist (see table MMWSupplementOption values for the possible options)


Global functions

(String) <- MJS_Function_getURLContents(String URL)
This method can be used to read the content of a specified URL
Returns an error [Error: Message] as a string if the specified URL could not be called up
(String) <- MJS_Function_readFile(String path)
This function enables a file to be read by specifying a path. The encoding of the string is always UTF-8. Pay attention to sandbox restrictions
Returns an error [Error: Message] as a string if the read was not successful
(String) <- MJS_Function_writeToFile(String text, String path)
This method can be used to save a string to a file by specifying a path. UTF-8 is always used as the encoding. Pay attention to sandbox restrictions
Returns an error [Error: Message] as a string if the write was not successful
(Array) <- MJS_Function_readDir(String path)
This method can be used to read the contents of a directory. The file names in the specified directory are returned as strings collected in an array. Pay attention to sandbox restrictions
Returns an error [Error: Message] as a string if the read was not successful

Sandbox restrictions

MarkMyWords operates within a sandbox, so this restriction also applies to all extensions used in MarkMyWords. Sandbox means that MarkMyWords only has limited access to the file system. If this is to be extended, this must be explicitly specified by the user, e.g. by opening a file via the Open dialog. If File/Directory is selected as the supplement option, the corresponding access is granted. Currently selected Quicksave directories can also be accessed.

The icon

The icon is a simple PNG image file. It should be square and the dimensions should be at least 128 x 128 pixels.