From e1be86ca6bfc7c210a5b791a12f6585bbf621856 Mon Sep 17 00:00:00 2001 From: Daniel Seifert Date: Sun, 5 Jul 2020 22:35:53 +0200 Subject: [PATCH] complete documentation and manual --- README.md | 18 ++++++++++---- ...030_Kompatibilitaet_mit_anderen_Modulen.md | 2 +- .../manual/010_Funktionen/010_Funktionen.md | 7 +++++- .../010_Funktionen/020_Kompatibilitaet.md | 7 ++++++ .../020_Programmierung/010_Anpassungen.md | 17 ++++--------- .../020_Programmierung/020_Templatedesign.md | 24 +++++++++++++++++++ .../020_Programmierung/020_neueDokumente.md | 0 .../020_Programmierung/030_Registries.md | 0 .../020_Programmierung/030_neueDokumente.md | 9 +++++++ .../020_Programmierung/040_Registries.md | 12 ++++++++++ docs/daux/manual/_index.md | 8 ++++++- 11 files changed, 84 insertions(+), 20 deletions(-) create mode 100644 docs/daux/manual/020_Programmierung/020_Templatedesign.md delete mode 100644 docs/daux/manual/020_Programmierung/020_neueDokumente.md delete mode 100644 docs/daux/manual/020_Programmierung/030_Registries.md create mode 100644 docs/daux/manual/020_Programmierung/030_neueDokumente.md create mode 100644 docs/daux/manual/020_Programmierung/040_Registries.md diff --git a/README.md b/README.md index 6600934..5620374 100644 --- a/README.md +++ b/README.md @@ -2,23 +2,31 @@ PDF-Dokumentgenerator für OXID eShop -Erstellen Sie unterschiedlichste statische oder dynamische PDF-Dokument auf Kopfdruck. Der Dokumentinhalt wird in Smartytemplates definiert. +Erstellen Sie unterschiedlichste statische oder dynamische PDF-Dokument auf Kopfdruck. Der Dokumentinhalt wird aus Smartytemplates erstellt. -Das Modul kann einfach erweitert werden, um bestehende Dokumente anzupassen oder Neue hinzuzufügen. +An den Bestellungen Ihres OXID-Shops steht Ihnen die Erstellung von Rechnung und Lieferschein zur Verfügung. + +Das Modul kann einfach erweitert werden, um bestehende Dokumente anzupassen oder Neue hinzuzufügen. ## Systemanforderungen: -- installierter OXID eShop -- PHP-Version, für die Installationspakete verfügbar sind +- installierter OXID eShop in Version 6 +- PHP-Version, für die Installationspakete verfügbar sind (PHP 7) - Installation via Composer +## Kompatibilität: + +Das Modul enthält die selbe Funktionalität wie das `OXID Invoice-PDF`-Modul. Grundsätzlich können beide Module parallel im Shop installiert werden, wenn dies erforderlich ist. + +Soll das `OXID Invoice-PDF`-Modul komplett vom `PDF Dokumente` Modul ersetzt werden (weil z.B. dritte Module ebenfalls dessen Funktion verwenden), stellen wir in Kürze eine Anpassung dafür zur Verfügung. + ## Installation: ```bash composer require d3/pdfdocuments --update-no-dev ``` -Eine detaillierte Installationsanleitung finden Sie [online](https://docs.oxidmodule.com/PDF-Dokumente/) und im docs-Verzeichnis dieses Pakets. +Eine detaillierte Installationsanleitung finden Sie [online](https://docs.oxidmodule.com/PDF-Dokumente/) und im docs-Verzeichnis dieses Pakets. Dort ist ebenfalls das Modulhandbuch hinterlegt. ## Support: diff --git a/docs/daux/installation/010_Anforderungen/030_Kompatibilitaet_mit_anderen_Modulen.md b/docs/daux/installation/010_Anforderungen/030_Kompatibilitaet_mit_anderen_Modulen.md index b8fc5bd..ba64bf0 100644 --- a/docs/daux/installation/010_Anforderungen/030_Kompatibilitaet_mit_anderen_Modulen.md +++ b/docs/daux/installation/010_Anforderungen/030_Kompatibilitaet_mit_anderen_Modulen.md @@ -2,4 +2,4 @@ title: Kompatibilität mit anderen Modulen --- -Das „Modul“ integriert sich auch in die Erweiterung "Auftragsmanager" von (D3) Data Development, sofern dieses im Shop installiert wurde. Diese Integration wurde für die Version 4.0.0.0 des "Auftragsmanager"-Moduls entwickelt. +Das PDF Dokumente-Modul integriert sich auch in die Erweiterung "Auftragsmanager" von (D3) Data Development, sofern dieses im Shop installiert wurde. Diese Integration wurde für die Version 4.0.0.0 des "Auftragsmanager"-Moduls entwickelt. diff --git a/docs/daux/manual/010_Funktionen/010_Funktionen.md b/docs/daux/manual/010_Funktionen/010_Funktionen.md index fa26afe..93a44b7 100644 --- a/docs/daux/manual/010_Funktionen/010_Funktionen.md +++ b/docs/daux/manual/010_Funktionen/010_Funktionen.md @@ -1,4 +1,9 @@ --- -title: Benutzerhandbuch +title: Funktionen --- +Erstellen Sie unterschiedlichste statische oder dynamische PDF-Dokument auf Kopfdruck. Der Dokumentinhalt wird aus Smartytemplates erstellt. + +An den Bestellungen Ihres OXID-Shops steht Ihnen die Erstellung von Rechnung und Lieferschein zur Verfügung. + +Das Modul kann einfach erweitert werden, um bestehende Dokumente anzupassen oder Neue hinzuzufügen. diff --git a/docs/daux/manual/010_Funktionen/020_Kompatibilitaet.md b/docs/daux/manual/010_Funktionen/020_Kompatibilitaet.md index e69de29..3c2fdbc 100644 --- a/docs/daux/manual/010_Funktionen/020_Kompatibilitaet.md +++ b/docs/daux/manual/010_Funktionen/020_Kompatibilitaet.md @@ -0,0 +1,7 @@ +--- +title: Kompatibilität +--- + +Das Modul enthält die selbe Funktionalität wie das `OXID Invoice-PDF`-Modul. Grundsätzlich können beide Module parallel im Shop installiert werden, wenn dies erforderlich ist. + +Soll das `OXID Invoice-PDF`-Modul komplett vom `PDF Dokumente` Modul ersetzt werden (weil z.B. dritte Module ebenfalls dessen Funktion verwenden), stellen wir in Kürze eine Anpassung dafür zur Verfügung. diff --git a/docs/daux/manual/020_Programmierung/010_Anpassungen.md b/docs/daux/manual/020_Programmierung/010_Anpassungen.md index f1c6c17..fb83104 100644 --- a/docs/daux/manual/020_Programmierung/010_Anpassungen.md +++ b/docs/daux/manual/020_Programmierung/010_Anpassungen.md @@ -1,18 +1,11 @@ --- -title: optische Anpassungen +title: Anpassungen an bestehenden Dokumenten --- -Die Modulausgaben können durch eigene CSS-Styles angepasst werden. Um die Updatefähigkeit des Moduls zu -erhalten, übernehmen Sie die neuen Stylesheets bitte in modulunabhängige Dateien. +Die Dokumente werden aus Smartytemplates erstellt, die Sie im `Application/views/tpl/documents` finden. -Die mitgelieferten Assets (CSS, JavaScripts) werden von uns über einen vorkonfigurierten Kompilierungstask -erstellt. Dieser kann via [Grunt](https://gruntjs.com/) ausgeführt werden. Möchten Sie eigene oder -angepasste Inhalte daraus kompilieren lassen, installieren Sie das Modul bitte mit Composer und der -`--prefer-source`-Option. Dann stehen Ihnen die Quelldateien im Ordner `src/build` zur Verfügung. +Für Änderungen einzelner Dokumentbereiche können Sie die darin notierten Templateblöcke in einem eigenen Modul überladen und deren Inhalt so verändern oder ergänzen. So müssen Sie das Originalmodul nicht verändern. -Diese können direkt aufgerufen werden, um eventuelle Anpassungen im zu Grunde liegenden Theme zu -integrieren. Alternativ können Sie die Sources auch in eigene Kompilierungsprozesse einbinden, -um projektspezifische Assets zu erstellen. +Beachten Sie, dass Templateblöcke in gemeinsam genutzen Templates auch in allen Dokumenten Änderungen hervorrufen. -Details zur Verwendung des Taskrunners und der Quelldateien entnehmen Sie bitte der `README.md` im -oben erwähnten Build-Ordner. \ No newline at end of file +Für umfangreichere Veränderungen können Sie dem jeweiligen Dokument auch auch anderes Template zuordnen. Überladen Sie dafür die entsprechende Dokumentenklasse und verändern Sie den Rückgabewert der Methode `getTemplate`. \ No newline at end of file diff --git a/docs/daux/manual/020_Programmierung/020_Templatedesign.md b/docs/daux/manual/020_Programmierung/020_Templatedesign.md new file mode 100644 index 0000000..40dfaf8 --- /dev/null +++ b/docs/daux/manual/020_Programmierung/020_Templatedesign.md @@ -0,0 +1,24 @@ +--- +title: Hinweise für Templatedesigner +--- + +## HTML + +Aus den Templates wird HTML-ähnlicher Quellcode mit CSS-Angaben erzeugt, der zur Erzeugung des PDF-Dokumentes dient. + +Der Quellcode beinhaltet jedoch einige wenige Besonderheiten (z.B. die `page`-, `page_head`- und `page_footer`-Tags), die im [HTML2PDF-Projekt](https://github.com/spipu/html2pdf) beschrieben sind. + +## CSS + +Layouts können mit inline CSS-Styles definiert werden. Die Einbindung externer Stylesheets wird zum Zeitpunkt der Dokumentationserstellung leider nicht unterstützt. + +Beachten Sie bitte, dass auch nur ein CSS-Subset unterstützt wird. Mit etwas CSS-Kreativität sollten sich die üblichen Formatierungen dennoch deutlich einfacher umsetzen lassen, als dies direkt in PHP-Programmierung möglich wäre. + +## Smarty + +Innerhalb der Templates steht Ihnen die komplette Smarty-Funktionalität zur Verfügung. + +## Debug + +Zur Erstellung der Dokumente kann es hilfreich sein, dass statt des fertigen PDFs eine besser prüfbare Zwischenversion exportiert wird. +Dies können Sie mit der Entwickleroption im Modul erreichen, die Sie im Adminbereich des Shops unter `Erweiterungen -> Module -> D3 PDF-Dokumente -> Einstell. -> Grundeinstellungen`. Sie erhalten dann beim Download ein HTML-Dokument, welches einfach im Browser analysiert werden kann. \ No newline at end of file diff --git a/docs/daux/manual/020_Programmierung/020_neueDokumente.md b/docs/daux/manual/020_Programmierung/020_neueDokumente.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/daux/manual/020_Programmierung/030_Registries.md b/docs/daux/manual/020_Programmierung/030_Registries.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/daux/manual/020_Programmierung/030_neueDokumente.md b/docs/daux/manual/020_Programmierung/030_neueDokumente.md new file mode 100644 index 0000000..4574e22 --- /dev/null +++ b/docs/daux/manual/020_Programmierung/030_neueDokumente.md @@ -0,0 +1,9 @@ +--- +title: neue Dokumente hinzufügen +--- + +Erstellen Sie eine neue PHP-Klasse, die mindestens das Interface `D3\PdfDocuments\Application\Model\Interfaces\pdfdocumentsGenericInterface` implementiert. Für Dokumente, die auf Bestellungen basieren (z.B. Rechnungen, Angebote, ...) können Sie statt dessen auch das optimierte Interface `D3\PdfDocuments\Application\Model\Interfaces\pdfdocumentOrderInterface` verwenden. + +Wenn Sie Ihre Dokumentenklasse von `D3\PdfDocuments\Application\Model\AbstractClasses\pdfdocumentsGeneric` bzw. von `D3\PdfDocuments\Application\Model\AbstractClasses\pdfdocumentsOrder` ableiten, sind für jedes Dokument nur noch wenige Zeilen Quellcode nötig. Beide abstrakte Klassen implementieren die oben genannten Interfaces automatisch. + +Als Beispiele dienen Ihnen die im Modul enthaltenen Dokumentklassen `invoice` und `deliverynote`. \ No newline at end of file diff --git a/docs/daux/manual/020_Programmierung/040_Registries.md b/docs/daux/manual/020_Programmierung/040_Registries.md new file mode 100644 index 0000000..5d04b0a --- /dev/null +++ b/docs/daux/manual/020_Programmierung/040_Registries.md @@ -0,0 +1,12 @@ +--- +title: Registries +--- + +Sollen in einem bestimmten Bereich des Shops mehrere Dokumente zur Auswahl angeboten werden, verwenden wir so genannte Registries für diese Liste. +So gibt es zum Beispiel eine Registry für den Bereich der Bestellungsdokumente im Adminbereich des Shops unter `Bestellungen verwalten -> Bestellungen -> Übersicht`. + +Sollen in diesem Bereich neue Dokumente zusätzlich angeboten werden oder bestehende Dokumente entfernt werden, können Sie die jeweilige Registry im eigenen Modul überladen und mit deren Methoden die Dokumentliste manipulieren. + +Benötigen Sie eine eigene Regsitry, können Sie eine eigene Klasse erstellen, die `D3\PdfDocuments\Application\Model\Registries\registryAbstract` erweitert. + +Ein Beispiel zur Verwendung von Registries finden Sie in der Erweiterung des im 1. Abschnitt genannten Adminbereich. \ No newline at end of file diff --git a/docs/daux/manual/_index.md b/docs/daux/manual/_index.md index 834f612..ba85e07 100644 --- a/docs/daux/manual/_index.md +++ b/docs/daux/manual/_index.md @@ -1 +1,7 @@ -It starts here. +--- +title: Handbuch +--- + +Im Abschnitt [Funktionen](010_Funktionen/010_Funktionen.md) finden Sie Informationen zum Funktionsumfang des Moduls und dessen Zusammenspiel mit dem `InvoicePdf` Modul von OXID eSales. + +Unter [Programmierung](020_Programmierung/010_Anpassungen.md) sind Hinweise enthalten, die Templatedesignern und Programmierern als Hinweise zur Erweiterung der Dokumente behilflich sind. \ No newline at end of file