DEVONthink-Belegversand-Automatisation/START.applescript

(*
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