Initial commit: v1.4 with documentation

2026-08-15 17:04:43 +02:00
parent 7c976e8619
commit 9838a86660
8 changed files with 503 additions and 0 deletions
@@ -0,0 +1,319 @@
+(*
+START.scpt - Version 1.4
+Rolle dieses Scripts
+--------------------
+Dieses Script ist der sichtbare Einstiegspunkt fŸr Anwender:innen.
+Es selbst verschickt keine Belege und fŸhrt auch keine Einrichtung durch,
+sondern Ÿbernimmt nur zwei Aufgaben:
+1. PrŸfen, ob relativ zur aktuellen DEVONthink-Auswahl eine Konfigurationsdatei
+   fŸr den Belegversand existiert.
+2. Falls in dieser Konfiguration SHOW_README=true gesetzt ist,
+   einen kurzen Willkommen-/Hinweisdialog anzeigen.
+3. Danach das Setup-Script _belegversand_setup.scpt starten.
+Das Setup-Script entscheidet anschlie§end selbst:
+- ob bereits eine gŸltige Einrichtung vorliegt und direkt das Hauptscript
+  gestartet werden kann,
+- oder ob zunŠchst die Konfiguration eingerichtet werden muss.
+Wichtig:
+--------
+START.scpt ist bewusst klein gehalten.
+Die eigentliche Fachlogik liegt in:
+- _belegversand_setup.scpt
+- _belegversand.scpt
+*)
+-- Name des Setup-Scripts, das im Unterordner "Helpers/scripts" liegt.
+-- Dieses Script wird von START.scpt immer am Ende aufgerufen.
+property setupScriptName : "_belegversand_setup.scpt"
+-- Name der DEVONthink-Gruppe, in der Konfigurationsdateien liegen.
+property configGroupName : "_config"
+-- Name der eigentlichen Konfigurationsdatei in DEVONthink.
+property configRecordName : "belegversand.conf"
+(*
+runSiblingScript(scriptFileName)
+--------------------------------
+LŠdt und startet ein weiteres AppleScript aus dem Unterordner "Helpers/scripts".
+Parameter:
+- scriptFileName : Dateiname des aufzurufenden Scripts, z. B.
+  "_belegversand_setup.scpt"
+Ablauf:
+- absolute Basis-Path setzen (Home + fest Pfad zu Belegversand_1-4)
+- daran den Unterordner "Helpers/scripts" und den Dateinamen anhŠngen
+- prŸfen, ob die Scriptdatei existiert
+- Script laden
+- Script ausfŸhren
+Fehlerbehandlung:
+- wenn die Datei nicht gefunden wird -> Hinweisdialog
+- wenn das Laden oder Starten fehlschlŠgt -> Hinweisdialog mit Fehlermeldung
+Wichtig:
+--------
+Der absolute Pfad ist invariant und unabhŠngig vom Speicherort dieses Scripts.
+*)
+on runSiblingScript(scriptFileName)
+	-- Absolute Basis-Path (Home + fest Installation)
+	set basePath to (do shell script "echo ~") & "/Library/Application Scripts/com.devon-technologies.think/Menu/Belegversand_1-4"
+	set targetPath to basePath & "/Helpers/scripts/" & scriptFileName
+	
+	try
+		set targetAlias to POSIX file targetPath as alias
+	on error
+		display dialog "Hinweis: Scriptdatei nicht gefunden:" & return & targetPath buttons {"OK"} default button "OK"
+		return
+	end try
+	
+	try
+		set loadedScript to load script targetAlias
+		run loadedScript
+	on error errMsg number errNum
+		display dialog "Hinweis: Konnte Script nicht starten:" & return & scriptFileName & return & return & errMsg buttons {"OK"} default button "OK"
+	end try
+end runSiblingScript
+(*
+recordText(theRecord)
+---------------------
+Liest den Textinhalt eines DEVONthink-Records.
+Verwendung in START.scpt:
+-------------------------
+Hier wird dieser Handler genutzt, um den Inhalt der Datei
+"_config/belegversand.conf" als Text einzulesen.
+Ablauf:
+- zunŠchst plain text versuchen
+- wenn das fehlschlŠgt, auf content ausweichen
+- wenn beides fehlschlŠgt, leeren String zurŸckgeben
+Hinweis:
+--------
+Die Konvertierung erscheint hier als "rich text", weil AppleScript/Script Editor
+solche Stellen beim Kompilieren teilweise selbststŠndig umschreiben kann.
+Der funktionale Zweck ist hier aber: Textinhalt lesbar zurŸckgeben.
+*)
+on recordText(theRecord)
+	tell application id "DNtp"
+		try
+			set t to plain text of theRecord
+			if t is missing value then set t to ""
+			return t as rich text
+		on error
+			try
+				set t to content of theRecord
+				if t is missing value then set t to ""
+				return t as rich text
+			on error
+				return ""
+			end try
+		end try
+	end tell
+end recordText
+(*
+findChildByName(parentRecord, childName)
+----------------------------------------
+Sucht innerhalb einer DEVONthink-Gruppe ein direktes Kind mit bestimmtem Namen.
+Parameter:
+- parentRecord : die Gruppe, in der gesucht werden soll
+- childName    : Name des gesuchten direkten Kinds
+RŸckgabe:
+- den gefundenen DEVONthink-Record
+- oder missing value, wenn nichts passt
+Verwendung in START.scpt:
+-------------------------
+- _config-Gruppe unter der DB-Wurzel suchen
+- belegversand.conf innerhalb von _config suchen
+*)
+on findChildByName(parentRecord, childName)
+	tell application id "DNtp"
+		try
+			set kids to children of parentRecord
+			repeat with i from 1 to count of kids
+				set c to item i of kids
+				if (name of c as rich text) is childName then return c
+			end repeat
+		end try
+	end tell
+	return missing value
+end findChildByName
+(*
+getTopParentGroup(theRecord)
+----------------------------
+Ermittelt die oberste Gruppe einer DEVONthink-Hierarchie ausgehend von einem Record.
+Ablauf:
+- starte mit dem aktuell Ÿbergebenen Record
+- frage wiederholt nach dessen Eltern
+- solange es noch einen Parent gibt, gehe eine Ebene nach oben
+- sobald kein Parent mehr vorhanden ist, ist die Wurzel erreicht
+Verwendung in START.scpt:
+-------------------------
+START.scpt kennt die gewŸnschte Datenbank nicht direkt.
+Darum nimmt es irgendein ausgewŠhltes Objekt in DEVONthink
+und geht davon Ÿber die Parent-Kette bis zur obersten Gruppe hoch.
+Dort wird dann _config gesucht.
+Vorteil:
+--------
+Das Script ist dadurch nicht an einen festen Datenbanknamen gebunden,
+sondern arbeitet relativ zur aktuellen Auswahl.
+*)
+on getTopParentGroup(theRecord)
+	tell application id "DNtp"
+		set currentRecord to theRecord
+		
+		repeat
+			try
+				set p to parents of currentRecord
+				if p is {} then return currentRecord
+				set currentRecord to item 1 of p
+			on error
+				return currentRecord
+			end try
+		end repeat
+	end tell
+end getTopParentGroup
+(*
+configValue(configText, keyName)
+--------------------------------
+Liest aus einem einfachen key=value-Konfigurationstext den Wert zu einem bestimmten SchlŸssel.
+Parameter:
+- configText : kompletter Textinhalt der Konfigurationsdatei
+- keyName    : gesuchter SchlŸssel, z. B. "SHOW_README"
+RŸckgabe:
+- Textwert des gefundenen SchlŸssels
+- oder missing value, wenn kein passender Eintrag existiert
+Funktionsweise:
+---------------
+- zeilenweise durch die Konfiguration gehen
+- prŸfen, ob eine Zeile mit "KEY=" beginnt
+- den Teil rechts vom "=" zurŸckgeben
+*)
+on configValue(configText, keyName)
+	set keyPrefix to keyName & "="
+	repeat with oneLine in paragraphs of configText
+		set lineText to oneLine as text
+		if lineText starts with keyPrefix then
+			if (length of lineText) is equal to (length of keyPrefix) then
+				return ""
+			else
+				set val to text ((length of keyPrefix) + 1) thru -1 of lineText
+				return val as text
+			end if
+		end if
+	end repeat
+	return missing value
+end configValue
+(*
+findConfigInCurrentDB()
+-----------------------
+Sucht die Konfigurationsdatei belegversand.conf relativ zur aktuellen DEVONthink-Auswahl.
+Ablauf:
+1. aktuelle Auswahl holen
+2. falls nichts ausgewŠhlt ist -> missing value
+3. von der Auswahl zur DB-Wurzel hochgehen
+4. dort die Gruppe _config suchen
+5. darin die Datei belegversand.conf suchen
+RŸckgabe:
+- den gefundenen Config-Record
+- oder missing value, wenn keine passende Konfiguration existiert
+Wichtig:
+--------
+Es wird absichtlich nicht global in allen Datenbanken gesucht,
+sondern immer nur relativ zur aktuellen Auswahl.
+So bleibt das Verhalten bei mehreren Datenbanken stabil und nachvollziehbar.
+*)
+on findConfigInCurrentDB()
+	tell application id "DNtp"
+		set sel to selection
+		if sel is {} then return missing value
+		set selectedRecord to item 1 of sel
+	end tell
+	
+	set dbRootRecord to my getTopParentGroup(selectedRecord)
+	set configGroupRecord to my findChildByName(dbRootRecord, configGroupName)
+	if configGroupRecord is missing value then return missing value
+	
+	set configRecord to my findChildByName(configGroupRecord, configRecordName)
+	return configRecord
+end findConfigInCurrentDB
+(*
+showWelcomeDialogIfNeeded()
+---------------------------
+Zeigt den Start-/Willkommensdialog an, falls die Konfiguration dies wŸnscht.
+Ablauf:
+1. Config-Datei relativ zur aktuellen Auswahl suchen
+2. Config-Datei lesen
+3. Wert SHOW_README auslesen
+4. falls SHOW_README=true -> Hinweisdialog anzeigen
+5. falls User "Diesen Dialog nicht mehr anzeigen" wŠhlt:
+   SHOW_README auf false in der Config zurŸckschreiben
+Hinweis:
+--------
+START.scpt fŸhrt selbst keine Einrichtung und keinen Versand durch.
+Der Dialog ist nur eine Hilfe fŸr Anwender:innen.
+Er verweist auf die interne README-Datei in _config.
+Bewusst einfach:
+----------------
+Es gibt hier nur zwei Buttons:
+- "Weiter"
+- "Diesen Dialog nicht mehr anzeigen"
+Die README wird nicht direkt aus dem Dialog gešffnet.
+*)
+on showWelcomeDialogIfNeeded()
+	set configRecord to my findConfigInCurrentDB()
+	if configRecord is missing value then return
+	
+	set cfgText to my recordText(configRecord)
+	set showReadmeVal to my configValue(cfgText, "SHOW_README")
+	if showReadmeVal is missing value then return
+	
+	set showReadmeLower to do shell script "printf %s " & quoted form of showReadmeVal & " | tr '[:upper:]' '[:lower:]'"
+	if showReadmeLower is not "true" then return
+	
+	set msgText to "Willkommen beim Belegversand, Version 1.4." & return & return & Â
+		"Mit dieser Funktion kannst du Dokumente aus dieser DEVONthink-Datenbank auswŠhlen, in ein ZIP-Archiv packen und als Mail-Entwurf vorbereiten." & return & return & Â
+		"Anschlie§end kšnnen die verarbeiteten Dokumente mit dem Tag 'gesendet' markiert werden. Der Versand wird zusŠtzlich in Protokolldateien dokumentiert." & return & return & Â
+		"Hinweise zur Einrichtung und Benutzung findest du in der Datei:" & return & Â
+		"README-Belegversand" & return & Â
+		"im Ordner:" & return & Â
+		"_config"
+	
+	set choice to button returned of (display dialog msgText buttons {"Diesen Dialog nicht mehr anzeigen", "Weiter"} default button "Weiter")
+	
+	if choice is "Diesen Dialog nicht mehr anzeigen" then
+		set newCfgText to ""
+		repeat with oneLine in paragraphs of cfgText
+			set lineText to oneLine as text
+			if lineText starts with "SHOW_README=" then
+				set newCfgText to newCfgText & "SHOW_README=false" & return
+			else
+				set newCfgText to newCfgText & lineText & return
+			end if
+		end repeat
+		
+		tell application id "DNtp"
+			try
+				set plain text of configRecord to newCfgText
+			on error
+				set content of configRecord to newCfgText
+			end try
+		end tell
+	end if
+end showWelcomeDialogIfNeeded
+(*
+run
+---
+Haupteinstiegspunkt des START-Scripts.
+Ablauf:
+1. optionalen Startdialog anzeigen
+2. Setup-Script starten
+Wichtig:
+--------
+START.scpt delegiert die eigentliche Entscheidung an das Setup-Script.
+Dort wird geprŸft:
+- existiert schon eine gŸltige Konfiguration?
+  -> dann Hauptscript starten
+- oder muss erst eingerichtet werden?
+*)
+on run
+	
+	with timeout of 3600 seconds
+		
+		my showWelcomeDialogIfNeeded()
+		my runSiblingScript(setupScriptName)
+		
+	end timeout
+	
+end run