Seite 1 von 1

Was ist ein Script-AddIn? (mit Tutorial)

Verfasst: 21. Feb 2014 00:27
von Kundal
Was ist ein Script-AddIn?

Script-AddIns sind Skriptdateien (z.B. mit der Dateiendung *.vbs für VB-Skript oder *.js für JSkript), die im Ordner /dopusdata/Script AddIns installiert werden. Diese Skripts werden automatisch ausgeführt, wenn in DOpus ein bestimmtes Ereignis auftritt. Es können aber auch neue Skriptbefehle erstellt werden, die in der Befehlsliste im Anpassen-Dialog (Reiter Befehle=>Skriptbefehle) aufgeführt werden.

Script-AddIns können auch in Form einer Datei mit der Endung .osp (Opus Script Package) vorliegen. Das ist einfach ein Archiv im Zip-Format, das die Script-Datei enthält. Das Archiv kann auch mehrere Skripts, oder z.B. eine Hilfedatei enthalten. Vor Allem bietet sich das Format aber an, um einem Skript, das einen neuen Skriptbefehl erstellt, ein passendes Icon für den Symbolleisten-Schalter mitzugeben. Das Icon wird dann im Archiv im gleichen Format wie ein Iconset (Icons + XML-Datei) in den Unterordner „icons“ gespeichert.

Die Installation eines Script-AddIns erfolgt einfach durch Kopieren der Script-Datei bzw. des OSP-Archivs nach /dopusdata/Script AddIns oder indem man die Datei per Drag & Drop in das Fenster Einstellungen=>Voreinstellungen=>Symbolleisten=>Skripts zieht. Hier findet sich eine Übersicht der installierten Script-AddIns. Ungepackte Skript-Dateien lassen sich, wenn ausgewählt, durch Klick auf den Button Bearbeiten direkt im Texteditor öffnen. Wenn das Skript Konfigurations-Optionen anbietet ist der Button Konfigurieren aktiviert.

Tutorial: Erstellen eines Script-AddIns mit Directory Opus

In diesem Tutorial werde ich die Erstellung eines Skripts demonstrieren, das immer dann eine Variable setzt, wenn im Dual-Modus die Quelle von einer Dateianzeige zur anderen wechselt (DUALSWAP=true, wenn die Quelle rechts ist und DUALSWAP=false, wenn die Quelle links ist). Außerdem erstellt das Skript einen neuen Skriptbefehl mit Namen RestoreDual, der im Prinzip wie der Befehl Set Dual =remember,toggle funktioniert, aber zusätzlich anhand der Variable DUALSWAP beim Zurückgehen vom Einzel-Modus in den Dual-Modus erinnert, ob die Quelle ursprünglich rechts war, um sie auf der richtigen Seite wiederherzustellen.

Zur Erstellung von Script-AddIns bietet DOpus 11 einen Editor, der komfortabel beim Erstellen einer Skript-Vorlage unterstützt. Um den Editor aufzurufen, gehen wir in DOpus auf die Seite Einstellungen=>Voreinstellungen=>Symbolleiste=>Skripts, klicken oben links auf Datei und wählen im Menü den Eintrag Neues Skript erstellen.
NeuesScript.png
Im Editor findet sich auf der rechten Seite eine Liste aller möglichen Ereignisse, die das Script auslösen können. Ganz oben ist OnInit bereits vorgewählt, das benötigt wird, um Informationen über das Skript in DOpus anzuzeigen und das Skript zu initialisieren. Wir scrollen in der Liste ganz nach unten und aktivieren für unser Skript zunächst das Kästchen bei OnSourceDestChange und dann ganz unten bei NewScriptCommand. Hier müssen wir dem neuen Skiptbefehl einen Namen geben, tragen dort also RestoreDual ein und bestätigen mit Enter. Jetzt geben wir links mindestens unter Skriptname den Namen, unter dem die Datei gespeichert werden soll, an (hier ebenfalls RestoreDual). Die Felder Beschreibung und Copyright sind optional, wobei es natürlich sinnvoll ist, eine Kurzbeschreibung wie 'Set Dual=remember,toggle' mit Wiederherstellung der Quelle in der rechten Dateianzeige einzugeben. Oben kann zwischen VBScript und JScript gewählt werden. Für unser Beispiel bleiben wir bei VBScript. Mit einem Klick auf OK wird die Datei erstellt und der Editor geschlossen.
VorlagenEditor.png
Auf der Einstellungsseite Skripts erscheint unsere neue Skriptvorlage nun als neuer Eintrag. Um das Skript weiter zu bearbeiten, aktivieren wir es zunächst durch Setzen des entsprechenden Häkchens, markieren dann den Eintrag und klicken auf den Schalter Bearbeiten.
Einstellungen.png
Die Datei wird nun im Standard-Texteditor geöffnet.
Tipp: Es wird vorrangig der Editor benutzt, der in der Registrierung für den Dateityp *.vbs unter HKEY_CLASSES_ROOT\VBSFile\Shell\Edit\Command eingetragen ist. Empfehlenswert ist ein Texteditor, der Zeilennummern anzeigen kann.
Die noch funktionslose Skriptvorlage stellt sich im Texteditor nun so dar:
ScriptVorlage.png
Wie zu erkennen ist, finden sich drei Funktionen im Skript. Die erste, Function OnInit(initData) enthält in Zeile 11-13 u.a. die Informationen zum Script, wie sie auf der Einstellungsseite dargestellt werden. Um das Script beim Start von DOpus immer zu aktivieren, fügen wir nach Zeile 13 die Zeile initData.default_enable = true ein. In Zeile 16-21 finden sich jetzt die Informationen zum neuen Scriptbefehl, wie sie in der Befehlsliste dargestellt werden. Da hier mehr Platz für die Beschreibung (cmd.desc = "") zur Verfügung steht, als in den Einstellungen, können wir ab Zeile 18 einen ausführlicheren Text einfügen. Um das Script übersichtlich zu halten, setzen wir Zeilenumbrüche ein, indem wir am Ende jeder Zeile die Zeichen &_ anfügen und jede Zeile in Anführungszeichen setzen.

Code: Alles auswählen

	cmd.desc = "Der Befehl 'RestoreDual' erweitert den Befehl " &_
		   "'Set Dual=remember,toggle',indem er es ermöglicht, " &_
		   "die Quelle in der rechten Dateianzeige wiederherzustellen, " &_
		   "wenn diese sich vor Verlassen des Dual-Modus auf der rechten Seite befand" 
Jetzt weisen wir dem Skriptbefehl noch ein Icon zu, indem wir am Ende der Funktion (jetzt Zeile 25) die Zeile cmd.icon = "dualdisplay" einfügen. Hier könnte auch ein Pfad zu einer Datei angegeben werden.
Achtung: Syntaxfehler im Bereich dieser Funktion führen dazu, dass DOpus das Script ignoriert und aus der Liste in den Einstellungen löscht.
OnInit.png
Als Nächstes widmen wir uns der zweiten Funktion Function OnSourceDestChange (jetzt in Zeile 29-33). Hier wollen wir testen, ob sich die Quelle im aktiven Lister in der rechten oder linken Dateianzeige befindet. Dazu fügen wir in Zeile 30 die folgenden neuen Zeilen ein:

Code: Alles auswählen

If SourceDestData.Tab.right = SourceDestData.source then
		DOpus.Output "rechts"
		DOpus.vars.Set "DUALSWAP", true
	Else
		DOpus.Output "links
		DOpus.vars.Set "DUALSWAP", false
	End If
OnSourceDestChange.png
Die Zeilen 31 und 34 dienen lediglich dem Zweck, in der Skriptausgabe eine Rückmeldung zu erhalten, ob der Test in Zeile 30 erfolgreich war. Die Zeilen können später wieder gelöscht werden. Um die Ausgabe zu überprüfen, öffnen wir nun in DOpus unter Symbolleiste_Menü=>Hilfe=>Protokolle=>Weitere Protokolle die Skriptausgabe. Wenn wir jetzt im Dual-Modus die aktive Dateianzeige zwischen links und rechts wechseln sollte die Ausgabe mit der Seite auf der sich die Quelle befindet, übereinstimmen (Ausgabe: RestoreDual: rechts für Rechts und RestoreDual: links für Links). Sollten sich Fehler im Skript finden, würden diese mit Zeilenangabe ausgegeben.
Wenn hier alles in Ordnung ist, können wir uns der dritten Funktion Function OnRestoreDual zuwenden (Zeilen 41-43). Hier wird der neue Skriptbefehl definiert. Da diese Funktion beim Klicken auf einen Schalter ausgeführt werden soll, müssen wir ihr die entsprechenden Methoden, Eigenschaften etc. verfügbar machen, indem wir ein passendes Ereignis-Objekt angeben. Dazu ändern wir Zeile 41 in Function OnRestoreDual(ByRef ClickData). Jetzt können wir in Zeile 42 die benötigten Befehlscode-Zeilen einfügen:

Code: Alles auswählen

	swap = false
	If DOpus.vars.Exists("DUALSWAP") Then
		swap = DOpus.vars.Get("DUALSWAP")
	End If
	If (ClickData.Func.Command.IsSet("DUAL=Off")) and swap Then
		ClickData.Func.Command.RunCommand("SET Dual=Remember,Toggle")
		ClickData.Func.Command.RunCommand("Go SWAP")
		ClickData.Func.Command.RunCommand("Set SOURCE=Right ")
	Else
		ClickData.Func.Command.RunCommand("SET Dual=Remember,Toggle")
	End If

In der ersten For-Schleife erhalten wir, falls vorhanden, die Variable DUALSWAP, um zu entscheiden, ob die Quelle links oder rechts wiederhergestellt werden muss. In der zweiten For-Schleife werden dann herkömmliche Schaltercodes eingesetzt. Wenn die Quelle ursprünglich links war, genügt der übliche Befehl Set Dual=remember,toggle, um die Ausgangssituation wiederherzustellen. War die Quelle jedoch ursprünglich rechts, wird diese Situation mit den zusätzlichen Befehlen Go SWAP und SET Source=Right wiedergestellt.
OnRestoreDual.png
Damit ist die Erstellung des Script-AddIns abgeschlossen. Wir bereinigen den Code noch, indem wir die Zeilen 31 und 34 löschen und speichern die Datei.

Um die Funktion zu testen, erstellen wir in einer Symbolleiste einen neuen Schalter mit dem Befehl RestoreDual und überprüfen, ob erwartungsgemäss zwischen Dual- und Einzelmodus gewechselt und die ursprüngliche Situation bezüglich Rechts/Links und Quelle/Ziel richtig wiederhergestellt wird. Da der Befehl der Befehlsliste im Anpassen-Menü in der Kategorie Skriptbefehle hinzugefügt wurde, können wir ihn auch von dort per Drag & Drop auf eine Symbolleiste ziehen. Bei Bedarf kann der Befehl im neuen Schalter nun mit weiteren Befehlen wie z.B. Set ViewPane=toggle kombiniert werden. Sollte der Befehl nicht ordnungsgemäß funktionieren, kann mit Hilfe der Skriptausgabe ("Weitere Protokolle", wie oben beschrieben) überprüft werden, ob und in welcher Zeile ein Fehler bei der Ausführung aufgetreten ist.

Den fertigen Schalter aus diesem Tutorial zum Download gibt es hier: Set DUAL=toggle,remember mit verbesserter Remember-Funktion

Re:

Verfasst: 9. Aug 2014 15:45
von SuperSwinka45
Thema ist sehr informativ und nützlich für mich. PS. Hallo an alle, ich bin neu hier und es ist mein erster beitrag.

Re: Was ist ein Script-AddIn? (mit Tutorial)

Verfasst: 9. Aug 2014 16:11
von Kundal
Herzlich willkommen und viel Spaß bei deinen ersten DOpus-Scripting-Projekten.
Vielleicht sehen wir hier ja mal brauchbare Ergebnisse von dir. :)