1066, 1067: Infos zur Plugin-Schnittstelle

Posted: 01.04.2010, 21:09 1066, 1067: Infos zur Plugin-Schnittstelle

Hallo zusammen,

ich habe mal die mir bisher vorliegenden Informationen zu der seit Ahnenblattversion 2.50 vorhandenen Plugin-Schnittstelle zusammengestellt:

Stand: 31.03.2010

Grundsätzliches:
Die Plugins dienen dazu, das Programm Ahnenblatt um Funktionen zu erweitern, die nicht direkt in das Programm Ahnenblatt integriert sind.
Einige Plugins liefert der Autor des Programms Ahnenblatt (Dirk Böttcher) bereits mit dem Programm mit.
Dies sind in Version 2.62:
- CD brennen
- CD brennen (Windows)
- Zeichentabelle
- Übertragung zum Palm (Plucker 1.3.1)
- Übertragung zum Palm (Plucker 1.6.2)
- Speichern für Pocket PC

Die von Dirk Böttcher seit Version 2.50 geschaffene Plugin-Schnittstelle ermöglicht, dass auch andere Programmierer Ahnenblatt um zusätzliche Funktionen erweitern können. Die Funktionalitäten der Plugins sollen hier nicht erläutert werden. Diese kann man den Beschreibungen im Downloadbereich, den Diskussionen im Forum und den jeweiligen Hilfetexten entnehmen.

In diesem Beitrag sollen die Befehle der ABP-Dateien erläutert werden. Die ABP-Dateien enthalten die Befehle die nacheinander abgearbeitet werden wenn das jeweilige Plugin aus Ahnenblatt heraus aufgerufen wird. Die Dateiendung ABP steht hier für Ahnenblatt-Plugin.
Der Aufruf erfolgt durch Auswahl des jeweiligen Plugins unter "Tools".
Eine ABP-Datei kann man mit einem Editor erstellen.
Die meisten Plugins rufen ein weiteres Programm auf, das in einer speziellen Programmiersprache geschrieben wurde. Grundsätzlich können hier alle auf einem Windows-PC lauffähigen Programme aufgerufen werden.
Nach dem Download der durch andere Programmierer bereitgestellten Plugins (i.d.R. eine zip-Datei) muss diese Datei in den Unterordner ...\Plugins entpackt werden.
Da Ahnenblatt mehrsprachig ist können auch die Plugins mehrsprachig erstellt werden.

Es werden jetzt die einzelnen Befehle der ABP-Dateien erläutert.
(Pfadangaben beziehen sich auf WINDOWS XP)

Ein einfaches Plugin könnte so aussehen:
-----------------------------------------------------
[plugin]
Text=Test-Plugin
1=$MAKEDIR(%temp%\Test)
2=$SAVEAS(CSVFILE-UNICODE,%temp%\Test\ahnen.csv)
3=%abpluginpath%\Test.exe
-----------------------------------------------------
Dieses Plugin stellt eine starke Vereinfachung eines Plugins dar.
Es gibt weitere Befehle, um das Plugin sinnvoller und stabiler zu gestalten.
Einige dieser Befehle werden im Folgenden erklärt. Hierzu wird das o.g. Plugin erweitert.
-----------------------------------------------------
[plugin]

Version=2.50

FileMustBeOpened=1

Text=Test-Plugin
Text.1031=Test-Plugin (deutsch)
Text.1036=Test-Plugin (französisch)
Text.1045=Test-Plugin (polnisch)

MustExist.1=%abpluginpath%\Test.exe

HideWhenFilesMissing=1

Help=%abpluginpath%\Hilfe.txt
Help.1031=%abpluginpath%\Hilfe-German.txt
Help.1036=%abpluginpath%\Hilfe-French.txt
Help.1045=%abpluginpath%\Hilfe-Polish.txt

1=$MAKEDIR(%temp%\Test)
2=$SAVEAS(CSVFILE-UNICODE,%temp%\Test\ahnen.csv)
3=$COPY(%abpluginpath%\CDBurner.ico,%temp%\Test)
4=%temp%\Test
5=%abpluginpath%\Test.exe
5.Param=%abLangName% %temp%
-----------------------------------------------------
Bemerkung:
Die Zeilen 3=... und 4=... machen hier wenig Sinn und dienen nur der Erklärung.

Die Befehle bedeuten im Einzelnen:

[plugin]
Dieser Text muss vorhanden sein, sonst erkennt Ahnenblatt nicht, dass es sich um ein Plugin handelt und bietet das Plugin nicht unter "Tools" an.

Version=2.50
Dieser Eintrag besagt, dass das Plugin erst ab der Ahnenblatt-Version 2.50 funktioniert. Bei älteren Ahnenblatt-Versionen wird das Plugin nicht unter "Tools" angeboten.

FileMustBeOpened=1
Das Plugin wird zwar im Menü "Tools" angeboten, es lässt sich jedoch nicht starten, wenn keine Ahnen-Datei geöffnet ist (der Button "Start" ist dann ausgegraut).
Eine evtl. vorhandene Hilfedatei kann jedoch trotzdem geöffnet werden.

Text=Test-Plugin
Als Pluginbezeichnung wird unter "Tools" der frei wählbare Text "Test-Plugin" angezeigt, unabhängig davon, welche Sprache in Ahnenblatt eingestellt ist.
Da Ahnenblatt mehrsprachig ist, kann man durch den Zusatz der Länderkennung die Anzeige des Textes in einer anderen Sprache steuern:
Text.1031=Test-Plugin
Anzeige in deutsch
Text.1036=Test-Plugin
Anzeige in Französisch
Weitere Länderkennungen sind z.B. 1034 für Spanisch, 1045 für Polnisch.

MustExist.1=%abpluginpath%\Test.exe
Das Plugin wird zwar im Menü "Tools" angeboten, es lässt sich jedoch nicht starten, wenn eine bestimmte Datei (hier: Test.exe) nicht vorhanden ist (der Button "Start" ist dann ausgegraut).
Eine evtl. vorhandene Hilfedatei kann jedoch trotzdem geöffnet werden.

HideWhenFilesMissing=1
Das Plugin wird nicht im Menü "Tools" angeboten, wenn die mit dem Befehl "MustExist.1" abgefragte Datei nicht vorhanden ist.

Help=%abpluginpath%\Hilfe.txt
Zusätzlich zum Starten eines Plugins wird ein Button "Hilfe" angezeigt, wenn mit dem obigen Befehl eine Hilfedatei deklariert wird.
Auch hier kann man (analog zu dem Befehl "Text.1031=Test-Plugin") mit dem Zusatz der Länderkennung den Aufruf eines übersetzten Hilfetextes vorsehen.

1=$MAKEDIR(%temp%\Test)
Anlegen eines neuen Unterverzeichnisses (hier: "c:\Dokumente und Einstellungen\"aktueller User"\Lokale Einstellungen\Temp\Test").
Der Verzeichnisname (hier: Test) kann frei gewählt werden.
Hier tauchen zwei grundlegende Festlegungen auf:

1. Systembefehle:
Für die Plugins können bestimmte Systembefehle verwendet werden.
Bisher sind folgende Systembefehle bekannt:

$MAKEDIR
Anlegen eines Verzeichnisses
$COPY
Kopieren einer Datei an einen anderen Ort

2. Umgebungsvariablen
Für die Plugins können bestimmte Umgebungsvariablen verwendet werden.
Bisher sind folgende Umgebungsvariablem bekannt:

%temp%
Enthät den Dateipfad "c:\Dokumente und Einstellungen\"aktueller User"\Lokale Einstellungen\Temp".

%abpluginpath%
Enthält (bei mir) den Dateipfad "C:\Programme\Ahnenblatt\Plugins".
Dies ist der Pfad des Plugin-Unterverzeichnisses. Der Inhalt dieser Umgebungsvariable ist davon abhängig, wo der jeweilige User das Programm Ahnenblatt installiert hat.

%cdburning%
Enthält den Dateipfad "C:\Dokumente und Einstellungen\"aktueller User"\Lokale Einstellungen\Anwendungsdaten\Microsoft\CD Burning".

%windir%
Enthält den Dateipfad "C:\WINDOWS".

%abLangName%
Enthält die in Ahnenblatt eingestellte Sprache (z.B.: German). Dies ist auch gleichzeitig der Name der Sprachedatei (ohne .lng Endung).

%abLangID%
Enthält die Identifikationsnummer der eingestellten Sprache entprechend den üblichen Windows-Konventionen (1031 ist z.B. Deutsch).

%ProgramFiles%
Enthält den Dateipfad "C:\Programme".

%outfile%
Enthält den kompletten Pfad mit dem Dateinamen, der vom User für eine Dateiausgabe ausgewählt wurde (z.B.: "C:\Dokumente und Einstellungen\"aktueller User"\eigene Dateien\Test.csv").

%outfilename%
Enthält die gleiche Ausgabe wie %outfile%

%outfilenameonly%
Enthält den vom User gewählten Dateinamen für eine Dateiausgabe (z.B.: "Test").

%outfiledir%
Enthält den Pfad, der ausgewählt wurde um dorthinein eine Datei zu speichern (z.B.: "C:\Dokumente und Einstellungen\"aktueller User"\eigene Dateien").

%outfilepath%
Enthält die gleiche Ausgabe wie %outfiledir%

2=$SAVEAS(CSVFILE-UNICODE,%temp%\Test\ahnen.csv)
Erzeugt eine csv-Datei (hier: ahnen.csv) mit allen in Ahnenblatt enthaltenen Daten in dem zuvor angelegten Unterverzeichnis.
Der Dateiname (hier: ahnen.csv) kann frei gewählt werden.
Hier sind wir auf eine zweite grundlegende Festlegung gestoßen.
Für die Plugins können bestimmte Speicherbefehle verwendet werden. Das Ergebnis dieser Speicherbefehle entspricht - bis auf eine Ausnahme bei der csv-Datei - den Speicherbefehlen in Ahnenblatt, die unter "Datei" -> "Speichern unter..." aufgerufen werden können.
Ausgegeben werden immer die in der aktuellen Ahnenblatt-Sitzung enthaltenen Daten.
Bisher sind folgende Speicherbefehle bekannt:
AHNENBLATT: Erzeugt eine Ahnenblatt-Datei (*.ahn)
AHNENBLATT+PICS: Wie vor und zusätzlich Abspeichern aller in Ahnenblatt verlinkten Bilder in das gleiche Verzeichnis wie die *.ahn-Datei
CSVFILE: Erzeugt eine CSV-Datei in der bereits in Ahnenblatt enthaltenen Zeichencodierung (*.csv) mit dem Tabulator als Trennzeichen. (Aus Ahnenblatt heraus wird als Trenner das Semikolon verwendet!!!). Wenn in der Ahnendatei nur ANSI-Zeichen vorkommen, wird die csv-Datei als ANSI-codiert ausgegeben. Wenn in der Ahnendatei auch nur ein UNICODE-Zeichen vorkommt, wird die csv-Datei als UNICODE-codiert (hier: UTF8) ausgegeben.
CSVFILE-ANSI: Wie vor, jedoch in der (erzwungenen) ANSI-Codierung (*.csv)
CSVFILE-UNICODE: Wie vor, jedoch in der (erzwungenen) UNICODE-Codierung (*.csv)
GEDCOM: Erzeugt eine GEDCOM-Datei in der bereits in Ahnenblatt enthaltenen Zeichencodierung (*.ged)
GEDCOM-ANSI: Wie vor, jedoch in der (erzwungenen) ANSI-Codierung (*.ged)
GEDCOM-UNICODE: Wie vor, jedoch in der (erzwungenen) UNICODE-Codierung (*.ged)
GEDCOM+PICS: Wie vor und zusätzlich Abspeichern aller in Ahnenblatt verlinkten Bilder in das gleiche Verzeichnis wie die *.ged-Datei
PalmWeb: Erzeugt eine HTML-Datei für einen PALM oder Pocket-PC (*.htm)
WEBSITE: Erzeugt eine HTML-Datei als website (*.htm)

3=$COPY(%abpluginpath%\CDBurner.ico,%temp%\Test)
Selbsterklärend

4=%temp%\Test
Wechsel in das angegebene Verzeichnis und Anzeige desselben im Explorer.

5=%abpluginpath%\Test.exe
Aufruf des Programmes "Test.exe".
Hierbei kann es sich um ein beliebiges, unter WINDOWS lauffähiges Programm handeln. Dieses Programm könnte nun die Daten aus der zuvor gespeicherten CSV-Datei verarbeiten.
Die hier aufgerufenen Programme stellen die eigentliche neue Funktionalität eines neuen Plugins dar.

5.Param=%abLangName% %temp%
Das Programm Test.exe wird mit den Parametern %abLangName% und %temp% aufgerufen.

Noch ein paar Überlegungen zu den Schreibrechten:
Wenn ein User nicht als Administrator unterwegs ist, sind evtl. seine Schreibrechte in bestimmte Verzeichnisse eingeschränkt. Es gibt Probleme, wenn ein "normaler" User ein Plugin startet, das in ein Verzeichnis abspeichern möchte, für das kein Schreibrecht besteht.
Dieses Problem kann man umgehen, indem ein Administrator diesem "normalen" User ein Schreibrecht für das bestimmte Verzeichnis einräumt.
Einige Pluginprogrammierer sind jedoch dazu übergegangen, das Anlegen von Verzeichnissen bzw. das Abspeichern von Dateien in den Pfad ...\Dokumente und Einstellungen\"aktueller User"\... vorzunehmen. Hier ist das Schreibrecht gesichert.

Posted: 01.04.2010, 22:16 (No subject)

Hallo Jürgen,

ein dickes Sonderlob zu Deiner tollen Anleitung.
Ich bin sicher, dass ich die auch noch brauchen kann.

Danke

Posted: 02.04.2010, 18:30 (No subject)

Posted: 03.10.2010, 08:51 (No subject)

Posted: 03.10.2010, 12:07 (No subject)

Hallo Iemhoff,

ja, Plugins, die nach dieser Anleitung geschrieben werden, laufen auch unter Version 2.62.
Sie laufen auf allen neueren Versionen von Ahnenblatt seit Version 2.50.

Der von Dir zitierte Satz besagt, dass Dirk Böttcher mit der Version 2.50 erstmals die Plugin-Schnittstelle eingeführt hat.

Posted: 14.11.2010, 12:58 PDF

Oben genannter Tekst von Jürgen als PDF-Datei. "Ein einfaches Plugin könnte so aussehen"

Posted: 09.01.2011, 13:45 (No subject)

supa beschreibung,

danke Cool

Posted: 10.01.2014, 17:55 (No subject)

mir ist da mal bei folgenden Befehl was aufgefallen.

MustExist.1=%abpluginpath%\Test.exe

wofür ist die "1"? Boolsche Operation?

Posted: 11.01.2014, 01:10 (No subject)

Ich denke eher dass man auch eine 2. und 3. und weitere solcher Bedingungen stellen kann. Über die Zahl könnte dann z.B. die Rückgabe des Wertes ermöglicht werden, bei dem die Bedingung eben nicht (mehr) erfüllt ist (sind).
Allerdings aus dem "Bauch heraus" wink

- nicht getestet.
Marcus

Posted: 13.01.2014, 12:35 (No subject)

Hallo Marc,

das bedeutet, dass die folgende Datei vorhanden sein muss. Sonst ist der Button zum Starten des Plugins ausgegraut.
Man kann weitere Dateien als Voraussetzung zum Starten angeben.
Ein Beispiel enthält die CDBurner.abp

Posted: 12.04.2014, 19:33 (No subject)

Gibt es ne Möglichkeit die AB Version als Parameter mitzugeben?

Hab nichts gefunden.

----------------------------
#Wunschliste_1066_OFFEN

Posted: 24.11.2014, 09:18 (No subject)

Ich hät gern noch nen Parameter welcher die Refnr der Startperson liefert.

Achja Markus und den Wunsch mit der ABVersion nicht vergessen aufzunehmen.

-------------------------------
#Wunschliste_1067_OFFEN

Posted: 16.01.2017, 14:35 (No subject)

hab grad festgestellt man kann für die hilfe auch einen Link angeben.
zb

Posted: 16.08.2018, 20:43 (No subject)

Habe etwas in der Version 2.99 gestöbert, und einige Neuigkeiten (zumindest für mich) bei den Plugins gefunden.

Variablen: %abpluginfilename%, %abpluginfilenameonly%, %abprogrampath%=%abprogramdir%, %desktopdirectory%, %mydocuments%, %mypictures%

Befehle: $DEL(dateiname), $MOVE(dateiname1,dateiname2), $MESSAGEBOX(Text %variable% Text)

Wer übrigens beliebige Systemkommandos absetzen will, kann das zB. so machen:
1=cmd.exe
1.param=/c echo temp=%temp% > %temp%\ausgabe.txt

Datenformate beim $SAVE():
CSVFILE3, CSVFILE3-ANSI, CSVFILE3-UNICODE: wurden ja schon angekündigt (wegen der #REFN Geschichte)
GEDML: GEDCOM 5.5 XML
GEDCOM60: GEDCOM 6.0 XML
TINYTAFEL: ??
RTFHELP: Daten als RTF Format

Seit welcher Version das schon alles geht habe ich nicht getestet.
In der V3 dürfte das auch alles vorhanden sein, nehme ich an.