Extensions

Version: 3.0.0
Datum: 01.01.2024
aktualisiert für macOS 14 Sonoma

Hinweis Scriptsprachen: Das Extension-System von MarkMyWords unterstützt seit seiner Einführung verschiedene Script-Sprachen. Allerdings wurden die Script-Sprachen, die in macOS mit neueren Versionen immer weiter eingeschränkt. Von den ursprünglich unterstützten Sprachen Perl, Ruby, PHP und Python kann ab macOS 12 standardmäßig keine mehr verwendet werden. Wenn macOS 12 oder neuer verwendet wird, ist die Nutzung von Javascript empfohlen.
Hinweis PHP in macOS 12 oder neuer: Die Scriptsprache PHP kann für die Nutzung verwendet werden, wenn ein entsprechender PHP-Parser eingerichtet und für MarkMyWords freigeschaltet ist. Mehr zu diesem Thema findet sich im Kapitel: Eigenen PHP-Interpreter verwenden.
Hinweis Perl und Ruby in macOS 12 oder neuer: Um diese beiden Skriptsprachen verwenden zu können, ist die Installation der Xcode Command Line Tools erforderlich. Diese Tools können mit der Terminal-App durch Eingabe des Befehls "xcode-select --install" installiert werden,
Hinweis: Python in macOS 12 oder neuer: Aufgrund neuer Sandbox-Restriktionen kann Python in macOS 12 oder neuer nicht für MarkMyWords Extensions verwendet werden.
Hinweis Javascript: Ab Version 2.9.0 von MarkMyWords kann auch die Scriptsprache Javascript zur Entwicklung von Extensions verwendet werden. Da die Verwendung von Javascript und dessen Ausführung nativ und ohne zusätzliche Interpreter von macOS unterstützt wird, wird die weitere Entwicklung des Extension-Systems vorrangig für diese Scriptsprache stattfinden.
Hinweis zu diesem Dokument: Derzeit werden für viele Beispiele die Scriptsprache PHP verwendet. Diese Beispiele sind symbolhaft auch für die anderen Sprachen informativ. In kommenden Versionen von MarkMyWords wird allerdings verstärkt auf die Scriptsprache Javascript eingegangen werden.

Mit Erweiterungen kann der Funktionsumfang von MarkMyWords den eigenen Bedürfnissen erweitert werden. Um eine Erweiterung zu aktivieren, kann diese entweder im Hauptmenü unter dem Punkt Extensions oder in der Symbolleiste über den Popup-Button Extensions schnell ausgewählt und ausgeführt werden.

Um die installierten Extensions zu verwalten, kann der Extension-Manager über das Hauptmenü unter dem Punkt Fenster > Extension-Manager aufgerufen werden. Über den Extension-Manager können Erweiterungen installiert, neue Extensions erstellt und bestehende Extensions bearbeitet oder entfernt werden.

Entwicklung von Erweiterungen für MarkMyWords

Empfehlung

Für die Erstellung von Erweiterungen sollte der Extension-Manager verwendet werden, da er die Erstellung neuer Erweiterungen erheblich vereinfacht und Fehler minimiert, da verschiedene Elemente der Extension automatisch erzeugt werden.

Hinweis: Die folgenden Beschreibungen gehen davon aus, dass PHP als Programmiersprache für die Entwicklung der Erweiterung verwendet wird. MarkMyWords unterstützt jedoch auch Javascript, Perl und Ruby sowie Python in älteren macOS Versionen.

Die MarkMyWords Extension-Site

Auf der MarkMyWords Extension-Seite stehen verschiedene Beispiel-Extensions und Core-Examples für Javascript, Perl, PHP, Python und Ruby bereit, die als Inspiration oder als Ausgangspunkt für die Entwicklung einer eigenen Extension verwendet werden können.

Das Paket

Jede Extension für MarkMyWords ist ein einfacher Ordner mit der Endung mmwxtz. Eine normale Erweiterung enthält drei Dateien:

Das Skript

Das Hauptskript für die Extension muss script.php heißen.
Zusätzliche Skripte können als Datei in das Extension-Package hinzufügt werden und entsprechend inkludiert werden.
Hinweis: Dies gilt nicht für Extensions, die mit Javascript entwickelt werden.
Verarbeitung der Ausgabe: Das Ergebnis ist eine einfache String-Ausgabe, ein Beispiel für PHP:
<?php
	// your cool code
	echo "The result is correct";
?>

In diesem Fall wäre der Rückgabewert dieser Extension: The result is correct.

Behandlung von Fehlern: MarkMyWords kann Fehlermeldungen der Extension abfangen. Die Anzeige der Fehlermeldungen gestaltet sich so einfach wie die Anzeige des Ergebnisses, dazu muss einfach Error: vor der entsprechenden Meldung vorangestellt werden. Ein Beispiel für PHP:
<?php
	if($result == true){
		// Your cool code here
	}
	else{
		$message = "Error: This didn’t work, try again!";
	}
	echo $message;
?>

Die Plist

Die script.plist-Datei ist das Herzstück der Extension und es ist wichtig, dass die Werte korrekt gesetzt werden. Daher empfiehlt es sich, den Extension-Manager zu verwenden, der sich um die korrekten Werte kümmert.
Um die plist-Datei von Hand zu erstellen, ist es am einfachsten, den Apple Property List Editor aus dem Developer Package zu verwenden, die plist-Datei kann allerdings auch mit einem normalen Texteditor (z.B. MarkMyWords) bearbeitet werden. Dazu sollte einfach eine bestehende Skript-Plist-Datei verwendet werden und deren Werte den eigenen Bedürfnissen angepasst werden. Die folgenden Werte sind verfügbar:

Plist-Eigenschaften

Property Beschreibung Erforderlich Werte
MMWCreator Name des Entwicklers NO Text
MMWCreatorHomepage Website des Entwicklers NO Text
MMWExtensionName der Name der Erweiterung YES Text
MMWExtensionDescription eine kurze Beschreibung der Erweiterung NO Text
MMWVersionNumber die Version der Erweiterung NO Text
MMWScriptLanguage die von der Erweiterung verwendete Sprache YES javascript, php, ruby, perl, python
MMWInputOption teilt MarkMyWords mit, welche Art von Eingabe an das Erweiterungsskript gesendet werden soll YES Siehe Tabelle MMWInputOption-Werte
MMWSupplementOption teilt MarkMyWords mit, ob zusätzliche Informationen an das Erweiterungsskript gesendet werden sollen YES Siehe Tabelle MMWSupplementOption-Werte
MMWSupplementOptionMessage fügt eine Meldung hinzu, die angezeigt werden soll, wenn das Ergänzungsblatt aufgerufen wird, damit der Benutzer weiß, warum dieser Dialog erscheint YES Text
MMWSupplementPresetValue fügt eine voreingestellte Zeichenkette in das Supplement-Textfeld ein NO Text
MMWOutputOption teilt MarkMyWords mit, wie das Ergebnis der Ausführung dem Benutzer präsentiert werden soll YES Siehe Tabelle MMWOutputOption-Werte

MMWInputOption-Werte

Wert Beschreibung
none es wird keine Eingabe gesendet
fulltext es wird der gesamte Text des aktuellen Dokuments gesendet
selection der ausgewählte Text des Dokuments wird gesendet
filename der Dateiname des aktuellen Dokuments wird gesendet
JSON ein JSON-Array, das alle vorherigen Angaben und einige weitere enthält (siehe JSON-Array für spezifische Angaben))

MMWSupplementOption-Werte

Wert Beschreibung
keine keine weitere Eingabe erforderlich
string der Benutzer kann einen zusätzlichen Text eingeben, der für die Ausführung verwendet werden kann
file der Benutzer kann eine Datei auswählen, deren Pfadname an die Ausführung übergeben wird
folder der Benutzer kann einen Ordner auswählen, dessen Pfadname an die Ausführung übergeben wird

MMWOutputOption-Werte

Wert Beschreibung
message zeigt das Ergebnis in einem Info-Dialog an
sheet zeigt das Ergebnis in einem Dialog an, mit den Optionen: in die Auswahl einfügen, in die Zwischenablage kopieren
append fügt das Ergebnis an das aktuelle Dokument an
prepend stellt das Ergebnis dem aktuellen Dokument voran
selection ersetzt die aktuelle Auswahl des aktuellen Dokuments durch das Ergebnis oder fügt das Ergebnis an der aktuellen Cursor-Position ein, wenn kein Text ausgewählt ist
fulltext ersetzt den Text des aktuellen Dokuments durch das Ergebnis

Die JSON-Supplement-Option

Die JSON-Supplement-Option ist die vielseitigste Option, die Ihrer Erweiterung verschiedene Details über das aktuelle Dokument liefert.
Code-Beispiel, dass das JSON-Array einliest und die Dateipfade der Attachments des aktuellen Dokuments auflistet:
<?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";
	}
?>
Schlüssel Beschreibung
Attachments Array von Dateipfaden zu den Attachments des aktuellen Dokuments
ColorLabel Ganzzahliger Wert des eingestellten Color-Labels des aktuellen Dokuments (0 = keine, 1 = grau, 2 = grün, 3 = lila, 4 = blau, 5 = gelb, 6 = rot, 7 = orange)
FileName Dateipfad des aktuellen Dokuments
FullText Text des aktuellen Dokuments
HTML Konvertierter Text des aktuellen Dokuments
SelectedText Ausgewählter Text des aktuellen Dokuments
Tags Array von Strings, die gesetzte Finder-Tags enthalten

Zugriff auf die Eingabewerte

Hinweis: der nachfolgende Text bezieht sich auf die Scriptsprache PHP. Die entsprechende Vorgehensweise für die Sprachen Perl, Python und Ruby kann in den Core-Examples nachvollzogen werden. Für die Scriptsprache Javascript stehen die erforderlichen Informationen in einem eigenen Kapitel unter "Javascript-Spezifische Funktionen und Variablen" bereit.
Bei der Entwicklung der Erweiterung wird in den meisten Fällen Zugriff auf die Eingabewerte benötigt. Während die reguläre Eingabe als Textstrom bereitgestellt wird, ist die Zusatzoption ein zusätzliches Argument beim Ausführen des Skripts.

Der folgende Code ist ein Beispiel für das Einlesen der Eingabewerte:

<?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);
?>
Der Zugriff auf die Supplement-Option wird im folgenden Beispiel gezeigt:
<?php
	$supplement = $argv[1];
?>

$argv ist eine globale Variable in PHP und enthält die angegebenen Argumente, wenn ein Skript einer Erweiterung ausgeführt werden soll.

Javascript-Spezifische Funktionen und Variablen

Für die Scriptsprache Javascript stehen eigene Variablen für den Zugriff auf die Eingabe- und Supplement-Werte bereit sowie zusätzliche Funktionen, die das Lesen und Schreiben externer Daten erleichtern.

Globale Variablen

(String) MJS_Var_Input
Diese Variable beinhaltet den Wert, der als Input in der script.plist definiert wurde (siehe Tabelle MMWInputOption-Werte für die möglichen Optionen)
(String) MJS_Var_Supplement
Diese Variable beinhaltet den Wert, der als Supplement in der script.plist definiert wurde (siehe Tabelle MMWSupplementOption-Werte für die möglichen Optionen)

Globale Funktionen

(String) <- MJS_Function_getURLContents(String URL)
Über diese Methode kann der Inhalt einer angegebenen URL eingelesen werden
Gibt einen Fehler [Error: Nachricht] als String zurück, wenn die angegebene URL nicht aufgerufen werden konnte
(String) <- MJS_Function_readFile(String path)
Diese Funktion ermöglicht das Lesen eine Datei unter Angabe eines Pfades. Das Encoding des Strings ist immer UTF-8. Sandbox-Restriktionen beachten
Gibt einen Fehler [Error: Nachricht] als String zurück, wenn das Lesen nicht erfolgreich war
(String) <- MJS_Function_writeToFile(String text, String path)
Mit dieser Methode kann ein String in einer Datei gespeichert werden unter Angabe eines Pfades. Als Encoding wird immer UTF-8 verwendet. Sandbox-Restriktionen beachten
Gibt einen Fehler [Error: Nachricht] als String zurück, wenn das Schreiben nicht erfolgreich war
(Array) <- MJS_Function_readDir(String path)
Mit dieser Methode kann der Inhalt eines Verzeichnisses ausgelesen werden. Die Dateinamen in dem spezifizierten Verzeichnis als Strings gesammelt in einem Array zurückgegeben. Sandbox-Restriktionen beachten
Gibt einen Fehler [Error: Nachricht] als String zurück, wenn das Lesen nicht erfolgreich war

Sandbox-Restriktionen

MarkMyWords operiert innerhalb einer Sandbox, diese Einschränkung gilt somit auch für alle Extensions, die in MarkMyWords verwendet werden. Sandbox bedeutet, dass MarkMyWords nur begrenzten Zugriff auf das Dateisystem hat. Wenn dieser erweitert werden soll, muss dies explizit durch den Nutzer angegeben werden, z.B. durch Öffnen einer Datei über den Öffnen-Dialog. Wenn als Supplement-Option Datei/Verzeichnis gewählt wird, ist der entsprechende Zugriff gewährt. Auch auf aktuell gewählte Quicksave-Verzeichnisse kann zugegriffen werden.

Das Icon

Das Icon ist eine einfache PNG-Bilddatei. Es sollte quadratisch sein und die Abmessungen sollten mindestens 128 x 128 Pixel betragen.