+ <para>Eine normale "if-then"-Bedingung. Die Zeilen zwischen dem "if"
+ und dem "end" werden nur ausgegeben, wenn die Variable
+ <varname>variablenname</varname> gesetzt und ungleich 0 ist.</para>
+
+ <para>Handelt es sich bei der benannten Variable um ein Array, also
+ um einen Variablennamen, über den man mit <command><%foreach
+ variablenname%></command> iteriert, so wird mit diesem Konstrukt
+ darauf getestet, ob das Array Elemente enthält. Somit würde im
+ folgenden Beispiel nur dann eine Liste von Zahlungseingängen samt
+ ihrer Überschrift "Zahlungseingänge" ausgegeben, wenn tatsächlich
+ welche getätigt wurden:</para>
+
+ <programlisting><%if payment%>
+Zahlungseingänge:
+ <%foreach payment%>
+ Am <%paymentdate%>: <%payment%> €
+ <%end foreach%>
+<%end if%></programlisting>
+
+ <para>Die Bedingung kann auch negiert werden, indem das Wort
+ <function>not</function> nach dem <filename>if</filename> verwendet
+ wird. Beispiel:</para>
+
+ <programlisting><%if not cp_greeting%>
+...
+<%end%></programlisting>
+
+ <para>Zusätzlich zu dem einfachen Test, ob eine Variable gesetzt ist
+ oder nicht, bietet dieser Block auch die Möglichkeit, den Inhalt
+ einer Variablen mit einer festen Zeichenkette oder einer anderen
+ Variablen zu vergleichen. Ob der Vergleich mit einer Zeichenkette
+ oder einer anderen Variablen vorgenommen wird, hängt davon ab, ob
+ die rechte Seite des Vergleichsoperators in Anführungszeichen
+ gesetzt wird (Vergleich mit Zeichenkette) oder nicht (Vergleich mit
+ anderer Variablen). Zwei Beispiele, die beide Vergleiche
+ zeigen:</para>
+
+ <programlisting><%if var1 == "Wert"%></programlisting>
+
+ <para>Testet die Variable <varname>var1</varname> auf
+ übereinstimmung mit der Zeichenkette <constant>Wert</constant>.
+ Mittels <function>!=</function> anstelle von <function>==</function>
+ würde auf Ungleichheit getestet.</para>
+
+ <programlisting><%if var1 == var2%></programlisting>
+
+ <para>Testet die Variable <varname>var1</varname> auf
+ übereinstimmung mit der Variablen <varname>var2</varname>. Mittel
+ <function>!=</function> anstelle von <function>==</function> würde
+ auf Ungleichheit getestet.</para>
+
+ <para>Erfahrere Benutzer können neben der Tests auf (Un-)Gleichheit
+ auch Tests auf Übereinstimmung mit regulären Ausdrücken ohne
+ Berücksichtung der Groß- und Kleinschreibung durchführen. Dazu dient
+ dieselbe Syntax wie oben nur mit <function>=~</function> und
+ <function>!~</function> als Vergleichsoperatoren.</para>
+
+ <para>Beispiel für einen Test, ob die Variable
+ <varname>intnotes</varname> (interne Bemerkungen) das Wort
+ <constant>schwierig</constant> enthält:</para>
+
+ <programlisting><%if intnotes =~ "schwierig"%></programlisting>
+ </sect3>
+
+ <sect3 id="dokumentenvorlagen-und-variablen.bloecke.foreach">
+ <title>Der foreach-Block</title>
+
+ <programlisting><%foreach variablenname%>
+...
+<%end%></programlisting>
+
+ <para>Fügt die Zeilen zwischen den beiden Anweisungen so oft ein,
+ wie das Perl-Array der Variablen <varname>variablenname</varname>
+ Elemente enthät. Dieses Konstrukt wird zur Ausgabe der einzelnen
+ Posten einer Rechnung / eines Angebots sowie zur Ausgabe der Steuern
+ benutzt. In jedem Durchlauf werden die <link
+ linkend="dokumentenvorlagen-und-variablen.invoice-posten">zeilenbezogenen
+ Variablen</link> jeweils auf den Wert für die aktuelle Position
+ gesetzt.</para>
+
+ <para>Die Syntax sieht normalerweise wie folgt aus:</para>
+
+ <programlisting><%foreach number%>
+Position: <%runningnumber%>
+Anzahl: <%qty%>
+Artikelnummer: <%number%>
+Beschreibung: <%description%>
+...
+<%end%></programlisting>
+
+ <para>Besonderheit in OpenDocument-Vorlagen: Tritt ein
+ <function><%foreach%></function>-Block innerhalb einer
+ Tabellenzelle auf, so wird die komplette Tabellenzeile so oft
+ wiederholt wie notwendig. Tritt er außerhalb auf, so wird nur der
+ Inhalt zwischen <function><%foreach%></function> und
+ <function><%end%></function> wiederholt, nicht aber die
+ komplette Zeile, in der er steht.</para>
+ </sect3>
+ </sect2>
+
+ <sect2 id="dokumentenvorlagen-und-variablen.markup">
+ <title>Markup-Code zur Textformatierung innerhalb von
+ Formularen</title>
+
+ <para>Wenn der Benutzer innhalb von Formularen in kivitendo Text
+ anders formatiert haben möchte, so ist dies begrenzt möglich.
+ kivitendo unterstützt die Textformatierung mit HTML-ähnlichen Tags.
+ Der Benutzer kann z.B. bei der Artikelbeschreibung auf einer Rechnung
+ Teile des Texts zwischen Start- und Endtags setzen. Dieser Teil wird
+ dann automatisch in Anweisungen für das ausgewählte Vorlagenformat
+ (HTML oder PDF über LaTeX) umgesetzt.</para>
+
+ <para>Die unterstützen Formatierungen sind:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><b>Text</b></term>
+
+ <listitem>
+ <para>Text wird in Fettdruck gesetzt.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><i>Text</i></term>
+
+ <listitem>
+ <para>Text wird kursiv gesetzt.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><u>Text</u></term>
+
+ <listitem>
+ <para>Text wird unterstrichen.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><s>Text</s></term>
+
+ <listitem>
+ <para>Text wird durchgestrichen. Diese Formatierung ist nicht
+ bei der Ausgabe als PDF über LaTeX verfügbar.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><bullet></term>
+
+ <listitem>
+ <para>Erzeugt einen ausgefüllten Kreis für Aufzählungen (siehe
+ unten).</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>Der Befehl <command><bullet></command> funktioniert
+ momentan auch nur in Latex-Vorlagen.</para>
+ </sect2>
+
+ <sect2 id="dokumentenvorlagen-und-variablen.anrede"
+ xreflabel="Hinweise zur Anrede">
+ <title>Hinweise zur Anrede</title>
+
+ <para>Das Flag "natürliche Person"
+ (<varname>natural_person</varname>) aus den Kunden- oder
+ Lieferantenstammdaten kann in den Druckvorlagen zusammen mit
+ dem Feld "Anrede" (<varname>greeting</varname>) z.B. dafür
+ verwendet werden, die Anrede zwischen einer allgemeinen und
+ einer persönlichen Anrede zu unterscheiden.
+ <programlisting><%if natural_person%><%greeting%> <%name%><%else%>Sehr geehrte Damen und Herren<%end if%></programlisting>
+ </para>
+ </sect2>
+
+ </sect1>
+
+ <sect1 id="excel-templates">
+ <title>Excel-Vorlagen</title>
+
+ <sect2 id="excel-templates.summary">
+ <title>Zusammenfassung</title>
+
+ <para>Dieses Dokument beschreibt den Mechanismus, mit dem
+ Exceltemplates abgearbeitet werden, und die Einschränkungen, die damit
+ einhergehen.</para>
+ </sect2>
+
+ <sect2 id="excel-templates.usage">
+ <title>Bedienung</title>
+
+ <para>Der Excel Mechanismus muss in der Konfigurationsdatei aktiviert
+ werden. Die Konfigurationsoption heißt <varname>excel_templates =
+ 1</varname> im Abschnitt <varname>[print_templates]</varname>.</para>
+
+ <para>Eine Excelvorlage kann dann unter dem Namen einer beliebigen
+ anderen Vorlage mit der Endung <filename>.xls</filename> gespeichert
+ werden. In den normalen Verkaufsmasken taucht nun
+ <constant>Excel</constant> als auswählbares Format auf und kann von da
+ an wie LaTeX- oder OpenOffice-Vorlagen benutzt werden.</para>
+
+ <para>Der Sonderfall der Angebote aus der Kundenmaske ist ebenfalls
+ eine Angebotsvorlage und wird unter dem internen Namen der Angebote
+ <filename>sales_quotation.xls</filename> gespeichert.</para>
+ </sect2>
+
+ <sect2 id="excel-templates.syntax">
+ <title>Variablensyntax</title>
+
+ <para>Einfache Syntax:
+ <command><<varname>></command></para>
+
+ <para>Dabei sind <constant><<</constant> und
+ <constant>>></constant> die Delimiter. Da Excel auf festen
+ Breiten besteht, kann der Tag künstlich verlängert werden, indem
+ weitere <constant><</constant> oder <constant>></constant>
+ eingefügt werden. Der Tag muss nicht symmetrisch sein.
+ Beispiel:</para>
+
+ <programlisting><<<<<varname>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>></programlisting>
+
+ <para>Um die Limitierung der festen Breite zu reduzieren, können
+ weitere Variablen in einem Block interpoliert werden. Whitespace wird
+ dazwishen dann erhalten. Beispiel:</para>
+
+ <programlisting><<<<<varname1 varname2 varname3>>>>>>>>>>>>>>>>>>>>>>>>>></programlisting>
+
+ <para>Die Variablen werden interpoliert, und linksbündig mit
+ Leerzeichen auf die gewünschte Länge aufgefüllt. Ist der String zu
+ lang, werden überzählige Zeichen abgeschnitten.</para>
+
+ <para>Es ist ausserdem möglich, Daten rechtsbündig darzustellen, wenn
+ der Block mit einem Leerzeichen anfängt. Beispiel:</para>
+
+ <programlisting><<<<<< varname>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>></programlisting>
+
+ <para>Dies würde rechtsbündig triggern. Wenn bei rechtsbündiger
+ Ausrichtung Text abgeschnitten werden muss, wird er vom linken Ende
+ entfernt.</para>
+ </sect2>
+
+ <sect2 id="excel-templates.limitations">
+ <title>Einschränkungen</title>
+
+ <para>Das Excelformat bis 2002 ist ein binäres Format, und kann nicht
+ mit vertretbarem Aufwand editiert werden. Der Templatemechanismus
+ beschränkt sich daher darauf, Textstellen exakt durch einen anderen
+ Text zu ersetzen.</para>
+
+ <para>Aus dem gleichen Grund sind die Kontrolllstrukturen
+ <command><%if%></command> und
+ <command><%foreach%></command> nicht vorhanden. Der Delimiter
+ <constant><% %></constant> kommt in den Headerinformationen
+ evtl. vor. Deshalb wurde auf den sichereren Delimiter
+ <constant><<</constant> und <constant>>></constant>
+ gewechselt.</para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="features.warehouse">
+ <title>Mandantenkonfiguration Lager</title>
+
+ <para>Die Lagerverwaltung in kivitendo funktioniert standardmässig wie
+ folgt: Wird ein Lager mit einem Lagerplatz angelegt, so gibt es die
+ Möglichkeit hier über den Menüpunkt Lager entsprechende Warenbewegungen
+ durchzuführen. Ferner kann jede Position eines Lieferscheins ein-, bzw.
+ ausgelagert werden (Einkauf-, bzw. Verkauf). Es können beliebig viele
+ Lager mit beliebig vielen Lagerplätzen abgebildet werden. Die
+ Lagerbewegungen über einen Lieferschein erfolgt durch Anklicken jeder
+ Einzelposition und das Auswählen dieser Position zu einem Lager mit
+ Lagerplatz. Dieses Verfahren lässt sich schrittweise vereinfachen, je
+ nachdem wie die Einstellungen in der Mandatenkonfiguration gesetzt
+ werden.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><option>Auslagern über Standardlagerplatz</option> Hier wird
+ ein zusätzlicher Knopf (Auslagern über Standard-Lagerplatz) in dem
+ Lieferschein-Beleg hinzugefügt, der dann alle Lagerbewegungen über
+ den Standardlagerplatz (konfigurierbar pro Ware) durchführt.</para>
+ </listitem>
+
+ <listitem>
+ <para><option>Auslagern ohne Bestandsprüfung</option> Das obige
+ Auslagern schlägt fehl, wenn die entsprechende Menge für die
+ Lagerbewegung nicht vorhanden ist, möchte man dies auch ignorieren
+ und ggf. dann nachpflegen, so kann man eine Negativ-Warenmenge mit
+ dieser Option erlauben. Hierfür muss ein entsprechender Lagerplatz
+ (Fehlbestand, o.ä.) konfiguriert sein.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Zusätzliche Funktionshinweise:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><option>Standard-Lagerplatz</option> Ist dieser konfiguriert,
+ wird dies auch als Standard-Voreinstellung bei der Neuerfassung von
+ Stammdaten → Waren / Dienstleistung / Erzeugnis verwendet.</para>
+ </listitem>
+
+ <listitem>
+ <para><option>Standard-Lagerplatz verwenden, falls keiner in
+ Stammdaten definiert</option> Wird beim 'Auslagern über
+ Standardlagerplatz' keine Standardlagerplatz zu der Ware gefunden,
+ so wird mit dieser Option einfach der Standardlagerplatz
+ verwendet.</para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1 id="features.swiss-charts-of-accounts">
+ <title>Schweizer Kontenpläne</title>
+
+ <para>Seit der Version 3.5 stehen in kivitendo 3 Kontenpläne für den
+ Einsatz in der Schweiz zur Verfügung, einer für Firmen und
+ Organisationen, die nicht mehrwertsteuerpflichtig sind, einer für
+ Firmen, die mehrwertsteuerpflichtig sind und einer speziell für
+ Vereine.</para>
+
+ <para>Die Kontenpläne orientieren sich am in der Schweiz üblicherweise
+ verwendeten KMU-Kontenrahmen und sind mit der Revision des
+ Schweizerischen Obligationenrechts (OR) vom 1.1.2013 kompatibel,
+ insbesondere <literal>Art.957a Abs.2</literal>.</para>
+
+ <para>Beim Vereinskontenplan sind standardmässig nur die Konten 1100
+ (Debitoren CHF) und 1101 (Debitoren EUR) als Buchungskonten im Verkauf
+ sowie die Konten 2000 (Kreditoren CHF) und 2001 (Kreditoren EUR) als
+ Buchungskonten im Einkauf vorgesehen. Weitere Konten können bei Bedarf
+ in den Konto-Detaileinstellungen als Einkaufs- oder Verkaufskonten
+ konfiguriert werden.</para>
+
+ <para>Die Möglichkeit, Saldosteuersätze zu verwenden ist in der
+ aktuellen Version von kivitendo noch nicht integriert.</para>
+
+ <para>Trotzdem können auch Firmen, die per Saldosteuersatz mit der
+ Eidgenössischen Steuerverwaltung abrechnen, kivitendo bereits nutzen.
+ Dazu wird der Kontenplan mit MWST ausgewählt. Anschliessend müssen alle
+ Aufwandskonten editiert werden und dort der Steuersatz auf 0% gesetzt
+ werden.</para>
+
+ <para>So werden bei Kreditorenbuchungen keine Vorsteuern
+ verbucht.</para>
+
+ <para>Bezugssteuern für aus dem Ausland bezogene Dienstleistungen müssen
+ manuell verbucht werden.</para>
+
+ <para>Wünsche für Anpassungen an den Schweizer Kontenplänen sowie
+ Vorschläge für weitere (z.B. branchenspezifische) Kontenpläne bitte an
+ <literal>empfang@revamp-it.ch</literal> senden.</para>
+ </sect1>
+
+ <sect1 id="features.part_classification">
+ <title>Artikelklassifizierung</title>
+
+ <sect2>
+ <title>Übersicht</title>
+
+ <para>Die Klassifizierung von Artikeln dient einer weiteren
+ Gliederung, um zum Beispiel den Einkauf vom Verkauf zu trennen,
+ gekennzeichnet durch eine Beschreibung (z.B. "Einkauf") und ein Kürzel
+ (z.B. "E"). Für jede Klassifizierung besteht eine Beschreibung und
+ eine Abkürzung die normalerweise aus einem Zeichen besteht, kann aber
+ auf mehrere Zeichen erweitert werden, falls zur Unterscheidung
+ notwendig. Sinnvoll sind jedoch nur maximal 2 Zeichen.</para>
+ </sect2>
+
+ <sect2>
+ <title>Basisklassifizierung</title>
+
+ <para>Als Basisklassifizierungen gibt es</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Einkauf</para>
+ </listitem>
+
+ <listitem>
+ <para>Verkauf</para>
+ </listitem>
+
+ <listitem>
+ <para>Handelsware</para>
+ </listitem>
+
+ <listitem>
+ <para>Produktion</para>
+ </listitem>
+
+ <listitem>
+ <para>- keine - (diese wird bei einer Aktualisierung für alle
+ existierenden Artikel verwendet und ist gültig für Verkauf und
+ Einkauf)</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Es können weitere Klassifizierungen angelegt werden. So kann es
+ z.B. für separat auszuweisende Artikel folgende Klassen geben:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Lieferung (Logistik, Transport) mit Kürzel L</para>
+ </listitem>
+
+ <listitem>
+ <para>Material (Verpackungsmaterial) mit Kürzel M</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2>
+ <title>Attribute</title>
+
+ <para>Bisher haben die Klassifizierungen folgende Attribute, die auch
+ alle gleichzeitg gültig sein können</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>gültig für Verkauf - dieser Artikel kann im Verkauf genutzt
+ werden</para>
+ </listitem>
+
+ <listitem>
+ <para>gültig für Einkauf - dieser Artikel kann im Einkauf genutzt
+ werden</para>
+ </listitem>
+
+ <listitem>
+ <para>separat ausweisen - hierzu gibt es zur Dokumentengenerierung
+ (LaTeX) eine zusätzliche Variable</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Für das Attribut "separat ausweisen" stehen in den
+ LaTeX-Vorlagen die Variable <emphasis
+ role="bold"><%non_separate_subtotal%> </emphasis>zur Verfügung,
+ die alle nicht separat auszuweisenden Artikelkosten saldiert, sowie
+ pro separat auszuweisenden Klassifizierungen die Variable<emphasis
+ role="bold">< %separate_X_subtotal%></emphasis>, wobei X das
+ Kürzel der Klassifizierung ist.</para>
+
+ <para>Im obigen Beispiel wäre das für Lieferkosten <emphasis
+ role="bold"><%separate_L_subtotal%></emphasis> und für
+ Verpackungsmaterial <emphasis role="bold">
+ <%separate_M_subtotal%></emphasis>.</para>
+ </sect2>
+
+ <sect2>
+ <title>Zwei-Zeichen Abkürzung</title>
+
+ <para>Der Typ des Artikels und die Klassifizierung werden durch zwei
+ Buchstaben dargestellt. Der erste Buchstabe ist eine Lokalisierung des
+ Artikel-Typs ('P','A','S'), deutsch 'W', 'E', und 'D' für Ware
+ Erzeugnis oder Dienstleistung und ggf. weiterer Typen.</para>
+
+ <para>Der zweite Buchstabe (und ggf. auch ein dritter, falls nötig)
+ entspricht der lokalisierten Abkürzung der Klassifizierung.</para>
+
+ <para>Diese Abkürzung wird überall beim Auflisten von Artikeln zur
+ Erleichterung mit dargestellt.</para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="features.file_managment">
+ <title>Dateiverwaltung (Mini-DMS)</title>
+
+ <sect2>
+ <title>Übersicht</title>
+
+ <para>Parallel zum alten WebDAV gibt es ein Datei-Management-System,
+ das Dateien verschiedenen Typs verwaltet. Dies können</para>
+
+ <orderedlist>
+ <listitem>
+ <para>aus ERP-Daten per LaTeX Template erzeugte
+ PDF-Dokumente,</para>
+ </listitem>
+
+ <listitem>
+ <para>zu bestimmten ERP-Daten gehörende Anhangdateien
+ unterschiedlichen Formats,</para>
+ </listitem>
+
+ <listitem>
+ <para>per Scanner eingelesene PDF-Dateien,</para>
+ </listitem>
+
+ <listitem>
+ <para>per E-Mail empfangene Dateianhänge unterschiedlichen
+ Formats,</para>
+ </listitem>
+
+ <listitem>
+ <para>sowie speziel für Artikel hochgeladene Bilder sein.</para>
+ </listitem>
+ </orderedlist>
+
+ <screenshot>
+ <screeninfo>Übersicht</screeninfo>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata contentwidth="600" fileref="images/DMS-Overview.png"/>
+ </imageobject>
+ </mediaobject>
+ </screenshot>
+ </sect2>
+
+ <sect2>
+ <title>Struktur</title>
+
+ <para>Über eine vom Speichermedium unabhängige Zwischenschicht werden
+ die Dateien und ihre Versionen in der Datenbank verwaltet. Darunter
+ können verschiedene Implementierungen (Backends) gleichzeitig
+ existieren:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Dateisystem</para>
+ </listitem>
+
+ <listitem>
+ <para>WebDAV</para>
+ </listitem>
+
+ <listitem>
+ <para>Schnittstelle zu externen
+ Dokumenten-Management-Systemen</para>
+ </listitem>
+
+ <listitem>
+ <para>andere Datenbank</para>
+ </listitem>
+
+ <listitem>
+ <para>etc ...</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Es gibt unterschiedliche Typen von Dateien. Jedem Typ läßt sich
+ in der Mandantenkonfiguration ein bestimmtes Backend zuordnen.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>"document": Das sind entweder generierte, eingescannte oder
+ hochgeladene PDF-Dateien, die zu bestimmten ERP-Daten
+ (ERP-Objekte, wie z.B. Rechnung, Lieferschein) gehören.</para>
+ </listitem>
+
+ <listitem>
+ <para>"attachment": zusätzlich hochgeladene Dokumente, die an
+ bestimmte ERP-Objekte angehängt werden, z.B. technische
+ Zeichnungen, Aufmaße. Diese können auch für Artikel, Lieferanten
+ und Kunden hinterlegt sein.</para>
+ </listitem>
+
+ <listitem>
+ <para>"image": Bilder für Artikel. Diese können auch verkleinert
+ in einer Vorschau (Thumbnail) angezeigt werden.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Zusätzlich werden in der Datenbank zu den Dateien neben der
+ Zuordnung zu ERP-Objekten, Dateityp Dateinamen und Backend, in dem die
+ Datei gespeichert ist, auch die Quelle der Datei notiert:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>"created": vom System erzeugte Dokumente"</para>
+ </listitem>
+
+ <listitem>
+ <para>"uploaded": hochgeladene Dokumente</para>
+ </listitem>
+
+ <listitem>
+ <para>"email": vom Mail-System empfangene Dateien</para>
+ </listitem>
+
+ <listitem>
+ <para>"scanner[1]": von einem oder mehreren Scannern erzeugte
+ Dateien. Existieren mehrere Scanner, so sind diese durch
+ unterschiedliche Quellennamen zu definieren.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Je nach Dateityp sind nur bestimmte Quellen zulässig. So gibt es
+ für "attachment" und "image" nur die Quelle "uploaded". Für "document"
+ gibt es auf jeden Fall die Quelle "created". Die Quellen "scanner" und
+ "email" müssen derzeit in der Datenbank konfiguriert werden (siehe
+ <xref linkend="file_management.dbconfig"/>).</para>
+ </sect2>
+
+ <sect2>
+ <title>Anwendung</title>
+
+ <para>Die Daten werden bei den ERP-Objekten als extra Reiter
+ dargestellt. Eine Verkaufsrechnung z.B. hat die Reiter "Dokumente" und
+ "Dateianhänge".</para>
+
+ <screenshot>
+ <screeninfo>Reiter "Dateianhänge"</screeninfo>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/DMS-Anhaenge.png" scale="50"/>
+ </imageobject>
+ </mediaobject>
+ </screenshot>
+
+ <para>Bei den Dateianhängen wird immer nur die aktuelle Version einer
+ Datei angezeigt. Wird eine Datei mit gleichem Namen hochgeladen, so
+ wird eine neue Version der Datei erstellt. Vorher wird der Anwender
+ durch einen Dialog gefragt, ob er eine neue Version anlegen will oder
+ ob er die Datei umbenennen will, falls es eine neue Datei sein
+ soll.</para>
+
+ <screenshot>
+ <screeninfo>Reiter "Dateianhänge"</screeninfo>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata contentwidth="40"
+ fileref="images/DMS-Anhaenge-hochladen.png"
+ width="100"/>
+ </imageobject>
+ </mediaobject>
+ </screenshot>
+
+ <para>Es können mehrere Dateien gleichzeitig hochgeladen werden,
+ solange in Summe die maximale Größe nicht überschritten wird (siehe
+ <xref linkend="file_management.clientconfig"/>).</para>
+
+ <screenshot>
+ <screeninfo>Reiter "Dokumente"</screeninfo>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/DMS-Dokumente.png" width="500"/>
+ </imageobject>
+ </mediaobject>
+ </screenshot>
+
+ <para>Sind keine weiteren Quellen für Dokumente konfiguriert, so gibt
+ es nur "erzeugte Dokumente". Es werden alle Versionen der generierten
+ Datei angezeigt. Für Verkaufsrechnungen kommen keine anderen Quellen
+ zur Geltung. Werden entsprechend der <xref
+ linkend="file_management.dbconfig"/> zusätzliche Quellen konfiguriert,
+ so sind diese z.B. bei Einkaufsrechnungen sichtbar:</para>
+
+ <screenshot>
+ <screeninfo>Reiter "Dokumente"</screeninfo>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata contentwidth="600"
+ fileref="images/DMS-Dokumente-Scanner.png"/>
+ </imageobject>
+ </mediaobject>
+ </screenshot>
+
+ <para>Statt des Löschens wird hier die Datei zurück zur Quelle
+ verschoben. Somit kann die Datei anschließend an ein anderes
+ ERP-Objekt angehängt werden.</para>
+
+ <para>Derzeit sind "Titel" und "Beschreibung" noch nicht genutzt. Sie
+ sind bisher nur bei Bildern relevant.</para>
+ </sect2>
+
+ <sect2>
+ <title>Konfigurierung</title>
+
+ <sect3 id="file_management.clientconfig"
+ xreflabel="Mandantenkonfigurierung">
+ <title>Mandantenkonfiguration</title>
+
+ <sect4>
+ <title>Reiter "Features"</title>
+
+ <para>Unter dem Reiter <emphasis role="bold">Features</emphasis>
+ im Abschnitt Dateimanagement ist neben dem "alten" WebDAV das
+ Dateimangement generell zu- und abschaltbar, sowie die Zuordnung
+ der Dateitypen zu Backends. Die Löschbarkeit von Dateien, sowie
+ die maximale Uploadgröße sind Backend-unabhängig</para>
+
+ <screenshot>
+ <screeninfo>Mandantenkonfig Reiter "Features"</screeninfo>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/DMS-ClientConfig.png" width="500"/>
+ </imageobject>
+ </mediaobject>
+ </screenshot>
+
+ <para>Die einzelnen Backends sind einzeln einschaltbar.
+ Spezifische Backend-Konfigurierungen sind hier noch
+ ergänzbar.</para>
+ </sect4>
+
+ <sect4>
+ <title>Reiter "Allgemeine Dokumentenanhänge"</title>
+
+ <para>Unter dem Reiter <emphasis role="bold">Allgemeine
+ Dokumentenanhänge</emphasis> kann für alle ERP-Dokumente (
+ Angebote, Aufträge, Lieferscheine, Rechnungen im Verkauf und
+ Einkauf ) allgemeingültige Anhänge hochgeladen werden.</para>
+
+ <screenshot>
+ <screeninfo>Mandantenkonfig Reiter "Allgemeine
+ Dokumentenanhänge"</screeninfo>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/DMS-Allgemeine-Dokumentenanhaenge.png"
+ width="500"/>
+ </imageobject>
+ </mediaobject>
+ </screenshot>
+
+ <para>Diese Anhänge werden beim Generieren von PDF-Dateien an die
+ ERP-Dokumente angehängt, z.B. AGBs oder aktuelle Angebote. Es
+ werden in dem Fall die Daten kopiert, sodass an den ERP-Dokumenten
+ immer die Anhänge zum Generierungszeitpunkt eingebettet
+ sind.</para>
+ </sect4>
+ </sect3>
+
+ <sect3 id="file_management.dbconfig"
+ xreflabel="Datenbank-Konfigurierung">
+ <title>Datenbank-Konfigurierung</title>
+
+ <para>Die zusätzlichen Quellen für "email" oder ein oder mehrere
+ Scanner sind derzeit vom Administrator direkt in der
+ Datenbanktabelle "user_preferences" einzurichten. Die "value" ist im
+ JSON-Format mit den jeweiligen Werten des Verzeichnisses und der
+ Beschreibung der Quelle.</para>
+
+ <programlisting>
+ id | login | namespace | version | key | value
+----+-----------+--------------+---------+----------+---------------------------
+ 1 | #default# | file_sources | 0.00000 | scanner1 |
+ {"dir":"/var/tmp/scanner1","desc":"Scanner Einkauf"}
+ 2 | #default# | file_sources | 0.00000 | scanner2 |
+ {"dir":"/var/tmp/scanner2","desc":"Scanner Verkauf"}
+ 3 | #default# | file_sources | 0.00000 | emails |
+ {"dir":"/var/tmp/emails","desc":"Empfangene Mails" }
+ </programlisting>
+
+ <para>Es ist daran gedacht, statt dem Default-Eintrag später für
+ bestimmte Benutzer ('login') bestimmte Quellen zuzulassen. Dies wird
+ nach Bedarf implementiert.</para>
+ </sect3>
+
+ <sect3 id="file_management.kiviconfig"
+ xreflabel="kivitendo-Konfigurationsdatei">
+ <title>kivitendo-Konfigurationsdatei</title>
+
+ <para>Dort ist im Abschnitt [paths] der relative oder absolute Pfad
+ zum Dokumentenwurzelverzeichnis einzutragen. Dieser muss für den
+ Webserver schreib- und lesbar sein, jedoch nicht ausführbar.</para>
+
+ <programlisting>
+[paths]
+document_path = /var/local/kivi_documents
+ </programlisting>
+
+ <para>Unter diesem Wurzelverzeichnis wird pro Mandant automatisch
+ ein Unterverzeichnis mit der ID des Mandanten angelegt.</para>
+ </sect3>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>Webshop-Api</title>
+
+ <para>Das Shopmodul bietet die Möglichkeit Onlineshopartikel und
+ Onlineshopbestellungen zu verwalten und zu bearbeiten.</para>
+
+ <para>Es ist Multishopfähig, d.h. Artikel können mehreren oder
+ unterschiedlichen Shops zugeordnet werden. Bestellungen können aus
+ mehreren Shops geholt werden.</para>
+
+ <para>Zur Zeit bietet das Modul nur einen Connector zur REST-Api von
+ Shopware. Weitere Connectoren können dazu programmiert und eingerichtet
+ werden.</para>
+
+ <sect2>
+ <title>Rechte für die Webshopapi</title>
+
+ <para>In der Administration können folgende Rechte vergeben
+ werden</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Webshopartikel anlegen und bearbeiten</para>
+ </listitem>
+
+ <listitem>
+ <para>Shopbestellungen holen und bearbeiten</para>
+ </listitem>
+
+ <listitem>
+ <para>Shop anlegen und bearbeiten</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2>
+ <title>Konfiguration</title>
+
+ <para>Unter System->Webshops können Shops angelegt und konfiguriert
+ werden</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata contentdepth="500" contentwidth="700"
+ fileref="images/Shop_Listing.png"/>
+ </imageobject>
+ </mediaobject>
+ </sect2>
+
+ <sect2>
+ <title>Webshopartikel</title>
+
+ <sect3>
+ <title>Shopvariablenreiter in Artikelstammdaten</title>
+
+ <para>Mit dem Recht "Shopartikel anlegen und bearbeiten" und des
+ Markers <emphasis role="bold">"Shopartikel" in den Basisdaten
+ </emphasis>zeigt sich der Reiter "Shopvariablen" in den
+ Artikelstammdaten. Hier können jetzt die Artikel mit
+ unterschiedlichen Beschreibung und/oder Preisen für die
+ konfigutierten Shops angelegt und bearbeitet werden. An dieser
+ Stelle können auch beliebig viele Bilder dem Shopartikel zugeordnet
+ werden. Artikelbilder gelten für alle Shops.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata contentdepth="500" contentwidth="600"
+ fileref="images/Shop_Artikel.png"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>Die Artikelgruppen werden direkt vom Shopsystem geholt somit
+ ist es möglich einen Artikel auch mehreren Gruppen
+ zuzuordenen</para>
+ </sect3>
+
+ <sect3>
+ <title>Shopartikelliste</title>
+
+ <para>Unter dem Menu Webshop->Webshop Artikel hat man nochmal
+ eine Gesamtübersicht. Von hier aus ist es möglich Artikel im Stapel
+ unter verschiedenen Kriterien <alles><nur Preis><nur
+ Bestand><Preis und Bestand> an die jeweiligen Shops
+ hochzuladen.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/Shop_Artikel_Listing.png"/>
+ </imageobject>
+ </mediaobject>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Bestellimport</title>
+
+ <para>Unter dem Menupunkt Webshop->Webshop Import öffnet sich die
+ Bestellimportsliste. Hier ist sind Möglichkeiten gegeben Neue
+ Bestellungen vom Shop abzuholen, geholte Bestellungen im Stapel oder
+ einzeln als Auftrag zu transferieren. Die Liste kann nach
+ verschiedenen Kriterien gefiltert werden.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/Shop_Bestell.png"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>Bei Einträgen in der Liste.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>keine Kundennummer: Es gibt ähnliche Kundendatensätze und
+ der Datensatz konnte nicht eindeutig zugewiesen werden.</para>
+ </listitem>
+
+ <listitem>
+ <para>Kundennummer und Rechnungen rot hinterlegt: Der Kunde hat
+ offene Posten und kann deswegen nicht im Stapel übernommen
+ werden.</para>
+ </listitem>
+
+ <listitem>
+ <para>Rechnungsadresse grün hinterlegt: Der Kunde konnte eindeutig
+ einem Datensatz zugeordnet werden. Die Shopbestellung kann im
+ Stapel mit dem Button "Anwenden" und wenn markiert als Auftrag
+ übernommen werden.</para>
+ </listitem>
+
+ <listitem>
+ <para>Kundennummer vorhanden, aber die Checkbox "Auftrag
+ erstellen" fehlt. Der Kunde hat vermutlich eine
+ Shopauftragssperre.</para>
+ </listitem>
+
+ <listitem>
+ <para>Lieferadresse grau hinterlegt: Optische Anzeige, dass es
+ sich um eine unterschiedliche Lieferadresse handelt.
+ Lieferadressen werden aber grundsätzlich beim Transferieren zu
+ Aufträgen mit übernommen.</para>
+ </listitem>
+
+ <listitem>
+ <para>In der Spalte Positionen/Betrag/Versandkosten zeigt sich ein
+ tooltip zu den Positionen.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Maske Auftrag erstellen</para>
+
+ <para>Viele Shopsysteme haben drei verschieden Adresstypen Kunden-,
+ Rechnungs-, und Lieferadresse, die sich auch alle unterscheiden
+ können. Diese werden im oberen Bereich angezeigt. Es ist möglich jede
+ dieser Adresse einzeln in kivitendo als Kunde zu übernehmen. Es werden
+ die Werte Formulareingabe übernommen. Es wird bei einer Änderung
+ allerdings nur diese in die kivitendo Kundenstammdaten übernommen, die
+ Shopbestellung bleibt bestehen.</para>
+
+ <para>Mit der mittleren Adresse(Rechnungsadresse) im oberen Bereich,
+ kann ich den ausgewählten kivitendodatensatz des mittleren Bereich
+ überschreiben. Das ist sinnvoll, wenn ich erkenne, das der Kunde z.B.
+ umgezogen ist.</para>
+
+ <para>Im mittleren Bereich das Adresslisting zeigt:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Rot hinterlegt: Kunde hat eine Shopauftragssperre, diese
+ muss zuerst deaktiviert werden bevor ich diesem Kunden eine
+ Shopbestellung zuordnen kann.</para>
+ </listitem>
+
+ <listitem>
+ <para>Kundenname fett und rot: Hier hat der Kunde eine Bemerkung
+ in den Stammdaten. Ein Tooltip zeigt diese Bemerkung. Das kann dan
+ auch der Grund für die Auftragssperre sein.</para>
+ </listitem>
+
+ <listitem>
+ <para>Die Buttons "Auftrag erstellen" und "Kunde mit
+ Rechnungsadresse überschreiben" zeigen sich erst, wenn ein Kunde
+ aus dem Listing ausgewählt ist.</para>
+ </listitem>
+
+ <listitem>
+ <para>Es ist aber möglich die Shopbestellung zu löschen.</para>
+ </listitem>
+
+ <listitem>
+ <para>Ist eine Bestellung schon übernommen, zeigen sich an dieser
+ Stelle, die dazugehörigen Belegverknüpfungen.</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2>
+ <title>Mapping der Daten</title>
+
+ <para>Das Mapping der kivitendo Daten mit den Shopdaten geschieht in
+ der Datei SL/ShopConnector/<SHOPCONNECTORNAME>.pm
+ z.B.:SL/ShopConnector/Shopware.pm</para>
+
+ <para>In dieser Datei gibt es einen Bereich wo die Bestellpostionen,
+ die Bestellkopfdaten und die Artikeldaten gemapt werden. In dieser
+ Datei kann ein individelles Mapping dann gemacht werden. Zu Shopware
+ gibt es hier eine sehr gute Dokumentation: <ulink
+ url="https://developers.shopware.com/developers-guide/rest-api/">https://developers.shopware.com/developers-guide/rest-api/</ulink></para>
+ </sect2>
+ </sect1>
+ <sect1 id="features.zugferd">
+ <title>ZUGFeRD Rechnungen</title>
+ <sect2 id="features.zugferd.preamble">
+ <title>Vorbedingung</title>
+ <para>
+ Für die Erstellung von ZUGFeRD PDFs wird TexLive2018 oder höher benötigt.
+ </para>
+ <note>
+ <para>
+ Wer kein TexLive2018 oder höher installieren kann, kann eine lokale Umgebung nur für kivitendo wie folgt erzeugen:
+ </para>
+ <programlisting>
+ 1. Download des offiziellen Installers von https://www.tug.org/texlive/quickinstall.html
+
+ 2. Installer ausführen, Standard-Ort für Installation belassen, evtl. ein paar Pakete abwählen, installieren lassen
+
+ 3. Ein kleine Script »run_pdflatex.sh« anlegen, das den PATH auf das Installationsverezichnis setzt und pdflatex ausführt:
+
+ ------------------------------------------------------------
+ #!/bin/bash
+
+ export PATH=/usr/local/texlive/2020/bin/x86_64-linux:$PATH
+ hash -r
+
+ exec pdflatex "$@"
+ ------------------------------------------------------------
+
+ 4. In config/kivitendo.conf den Parameter »latex« auf den Pfad zu »run_pdflatex.sh« setzen
+
+ 5. Webserver neu starten
+ </programlisting>
+ </note>
+ </sect2>
+ <sect2 id="features.zugferd.summary">
+ <title>Übersicht</title>
+
+ <para>Mit der Version 3.5.6 bietet kivitendo die Möglichkeit ZUGFeRD
+ Rechnungen zu erstellen, sowie auch ZUGFeRD Rechnungen direkt in
+ kivitendo einzulesen. </para>
+
+ <para>Bei ZUGFeRD Rechnungen handelt es sich um eine PDF Datei in
+ der eine XML-Datei eingebettet ist. Der Aufbau der XML-Datei ist
+ standardisiert und ermöglicht so den Austausch zwischen
+ den verschiedenen Softwareprodukten. Kivitendo setzt mit der
+ Version 3.5.6 den ZUGFeRD 2.1 Standard um.</para>
+
+ <para>Weiter Details zu ZUGFeRD sind unter diesem Link zu finden:
+ <ulink url="https://www.ferd-net.de/standards/was-ist-zugferd/index.html">https://www.ferd-net.de/standards/was-ist-zugferd/index.html</ulink>
+ </para>
+ </sect2>
+
+ <sect2 id="features.zugferd.create_zugferd_bills">
+
+ <title>Erstellen von ZUGFeRD Rechnungen in Kivitendo</title>
+ <para>Für die Erstellung von ZUGFeRD Rechnungen bedarf es in
+ kivitendo zwei Dinge:</para>
+
+ <orderedlist>
+
+ <listitem>
+ <para>Die Erstellung muss in der Mandantenkonfiguration
+ aktiviert sein</para>
+ </listitem>
+
+ <listitem>
+ <para>Beim mindestens einem Bankkonto muss die Option
+ „Nutzung von ZUGFeRD“ aktiviert sein</para>
+ </listitem>
+
+ </orderedlist>
+ <sect3>
+ <title>Mandantenkonfiguration</title>
+
+ <para>Die Einstellung für die Erstellung von ZUGFeRD Rechnungen
+ erfolgt unter „System“ → „Mandatenkonfiguration“ → „Features“.
+ Im Abschnitt „Einkauf und Verkauf“ finden Sie die Einstellung
+ „Verkaufsrechnungen mit ZUGFeRD-Daten erzeugen“.
+ Hier besteht die Auswahl zwischen:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>ZUGFeRD-Rechnungen erzeugen</para>
+ </listitem>
+
+ <listitem>
+ <para>ZUGFeRD-Rechnungen im Testmodus erzeugen</para>
+ </listitem>
+
+ <listitem>
+ <para>Keine ZUGFeRD Rechnungen erzeugen</para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>Rechnungen die als PDF erzeugt werden, werden je nach
+ Einstellung nun im ZUGFeRD Format ausgegeben.</para>
+
+ </sect3>
+
+ <sect3>
+ <title>Konfiguration der Bankkonten</title>
+
+ <para>Unter „System → Bankkonten“ muss bei mindestens einem
+ Bankkonto die Option „Nutzung mit ZUGFeRD“ auf „Ja“ gestellt
+ werden.</para>
+ </sect3>
+
+ </sect2>
+
+ <sect2 id="features.zugferd.read_zugferd_bills">
+
+ <title>Einlesen von ZUGFeRD Rechnungen in Kivitendo</title>
+
+ <para>Es lassen sich auch Rechnungen von Kreditoren, die im
+ ZUGFeRD Format erstellt wurden, nach Kivitendo importieren.
+ Hierfür müssen auch zwei Voraussetzungen erfüllt werden:
+ </para>
+
+ <orderedlist>
+
+ <listitem>
+ <para>Beim Lieferanten muss die Umsatzsteuer-ID und das
+ Bankkonto hinterlegt sein</para>
+ </listitem>
+
+ <listitem>
+ <para>Für den Kreditoren muss eine Buchungsvorlage existieren.</para>
+ </listitem>
+
+ </orderedlist>
+
+ <para>Wenn diese Voraussetzungen erfüllt sind, kann die Rechnung
+ über „Finanzbuchhaltung“ → „Factur-X-/ZUGFeRD-Import“ über die „Durchsuchen“
+ Schaltfläche ausgewählt werden und über die Schaltfläche „Import“
+ eingeladen werden. Es öffnet sich daraufhin die Kreditorenbuchung.
+ Die auslesbaren Daten aus dem eingebetteten XML der PDF Datei
+ werden in der Kreditorenbuchung ergänzt.</para>
+
+ </sect2>
+
+ </sect1>
+
+ </chapter>
+
+ <chapter>
+ <title>Entwicklerdokumentation</title>
+
+ <sect1 id="devel.globals" xreflabel="Globale Variablen">
+ <title>Globale Variablen</title>
+
+ <sect2>
+ <title>Wie sehen globale Variablen in Perl aus?</title>
+
+ <para>Globale Variablen liegen in einem speziellen namespace namens
+ "main", der von überall erreichbar ist. Darüber hinaus sind bareword
+ globs global und die meisten speziellen Variablen sind...
+ speziell.</para>
+
+ <para>Daraus ergeben sich folgende Formen:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>$main::form</literal></term>
+
+ <listitem>
+ <para>expliziter Namespace "main"</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>$::form</literal></term>
+
+ <listitem>
+ <para>impliziter Namespace "main"</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>open FILE, "file.txt"</literal></term>
+
+ <listitem>
+ <para><varname>FILE</varname> ist global</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>$_</literal></term>
+
+ <listitem>
+ <para>speziell</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>Im Gegensatz zu <productname>PHP</productname> gibt es kein
+ Schlüsselwort wie "<function>global</function>", mit dem man
+ importieren kann. <function>my</function>, <function>our</function>
+ und <function>local</function> machen was anderes.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>my $form</literal></term>
+
+ <listitem>
+ <para>lexikalische Variable, gültig bis zum Ende des
+ Scopes</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>our $form</literal></term>
+
+ <listitem>
+ <para><varname>$form</varname> referenziert ab hier
+ <varname>$PACKAGE::form</varname>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>local $form</literal></term>
+
+ <listitem>
+ <para>Alle Änderungen an <varname>$form</varname> werden am Ende
+ des scopes zurückgesetzt</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+
+ <sect2>
+ <title>Warum sind globale Variablen ein Problem?</title>
+
+ <para>Das erste Problem ist <productname>FCGI</productname>.</para>
+
+ <para><productname>SQL-Ledger</productname> hat fast alles im globalen
+ namespace abgelegt, und erwartet, dass es da auch wiederzufinden ist.
+ Unter <productname>FCGI</productname> müssen diese Sachen aber wieder
+ aufgeräumt werden, damit sie nicht in den nächsten Request kommen.
+ Einige Sachen wiederum sollen nicht gelöscht werden, wie zum Beispiel
+ Datenbankverbindungen, weil die sehr lange zum Initialisieren
+ brauchen.</para>
+
+ <para>Das zweite Problem ist <function>strict</function>. Unter
+ <function>strict</function> werden alle Variablen die nicht explizit
+ mit <function>Package</function>, <function>my</function> oder
+ <function>our</function> angegeben werden als Tippfehler angemarkert,
+ dies hat, seit der Einführung, u.a. schon so manche langwierige
+ Bug-Suche verkürzt. Da globale Variablen aber implizit mit Package
+ angegeben werden, werden die nicht geprüft, und somit kann sich
+ schnell ein Tippfehler einschleichen.</para>
+ </sect2>
+
+ <sect2>
+ <title>Kanonische globale Variablen</title>
+
+ <para>Um dieses Problem im Griff zu halten gibt es einige wenige
+ globale Variablen, die kanonisch sind, d.h. sie haben bestimmte
+ vorgegebenen Eigenschaften, und alles andere sollte anderweitig
+ umhergereicht werden.</para>
+
+ <para>Diese Variablen sind im Moment die folgenden neun:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><varname>$::form</varname></para>
+ </listitem>
+
+ <listitem>
+ <para><varname>%::myconfig</varname></para>
+ </listitem>
+
+ <listitem>
+ <para><varname>$::locale</varname></para>
+ </listitem>
+
+ <listitem>
+ <para><varname>$::lxdebug</varname></para>
+ </listitem>
+
+ <listitem>
+ <para><varname>$::auth</varname></para>
+ </listitem>
+
+ <listitem>
+ <para><varname>$::lx_office_conf</varname></para>
+ </listitem>
+
+ <listitem>
+ <para><varname>$::instance_conf</varname></para>
+ </listitem>
+
+ <listitem>
+ <para><varname>$::dispatcher</varname></para>
+ </listitem>
+
+ <listitem>
+ <para><varname>$::request</varname></para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Damit diese nicht erneut als Müllhalde missbraucht werden, im
+ Folgenden eine kurze Erläuterung der bestimmten vorgegebenen
+ Eigenschaften (Konventionen):</para>
+
+ <sect3>
+ <title>$::form</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>Ist ein Objekt der Klasse
+ "<classname>Form</classname>"</para>
+ </listitem>
+
+ <listitem>
+ <para>Wird nach jedem Request gelöscht</para>
+ </listitem>
+
+ <listitem>
+ <para>Muss auch in Tests und Konsolenscripts vorhanden
+ sein.</para>
+ </listitem>
+
+ <listitem>
+ <para>Enthält am Anfang eines Requests die Requestparameter vom
+ User</para>
+ </listitem>
+
+ <listitem>
+ <para>Kann zwar intern über Requestgrenzen ein Datenbankhandle
+ cachen, das wird aber momentan absichtlich zerstört</para>
+ </listitem>
+ </itemizedlist>
+
+ <para><varname>$::form</varname> wurde unter <productname>SQL
+ Ledger</productname> als Gottobjekt für alles missbraucht. Sämtliche
+ alten Funktionen unter SL/ mutieren <varname>$::form</varname>, das
+ heißt, alles was einem lieb ist (alle Variablen die einem ans Herz
+ gewachsen sind), sollte man vor einem Aufruf (!) von zum Beispiel
+ <function>IS->retrieve_customer()</function> in Sicherheit
+ bringen.</para>
+
+ <para>Z.B. das vom Benutzer eingestellte Zahlenformat, bevor man
+ Berechnung in einem bestimmten Format durchführt (SL/Form.pm Zeile
+ 3552, Stand version 2.7beta), um dies hinterher wieder auf den
+ richtigen Wert zu setzen:</para>
+
+ <programlisting> my $saved_numberformat = $::myconfig{numberformat};
+ $::myconfig{numberformat} = $numberformat;
+ # (...) div Berechnungen
+ $::myconfig{numberformat} = $saved_numberformat;</programlisting>
+
+ <para>Das Objekt der Klasse Form hat leider im Moment noch viele
+ zentrale Funktionen die vom internen Zustand abhängen, deshalb bitte
+ nie einfach zerstören oder überschreiben (zumindestens nicht kurz
+ vor einem Release oder in Absprache über bspw. die devel-Liste ;-).
+ Es geht ziemlich sicher etwas kaputt.</para>
+
+ <para><varname>$::form</varname> ist gleichzeitig der Standard Scope
+ in den <productname>Template::Toolkit</productname> Templates
+ außerhalb der Controller: der Ausdruck <function>[% var
+ %]</function> greift auf <varname>$::form->{var}</varname> zu.
+ Unter Controllern ist der Standard Scope anders, da lautet der
+ Zugriff <function>[% FORM.var %]</function>. In Druckvorlagen sind
+ normale Variablen ebenfall im <varname>$::form</varname> Scope, d.h.
+ <function><%var%></function> zeigt auf
+ <varname>$::form->{var}</varname>. Nochmal von der anderen Seite
+ erläutert, innerhalb von (Web-)Templates sieht man häufiger solche
+ Konstrukte:</para>
+
+ <programlisting>[%- IF business %]
+# (... Zeig die Auswahlliste Kunden-/Lieferantentyp an)
+[%- END %]</programlisting>
+
+ <para>Entweder wird hier dann $::form->{business} ausgewertet
+ oder aber der Funktion
+ <function>$form->parse_html_template</function> wird explizit
+ noch ein zusätzlicher Hash übergeben, der dann auch in den
+ (Web-)Templates zu Verfügung steht, bspw. so:</para>
+
+ <programlisting>$form->parse_html_template("is/form_header", \%TMPL_VAR);</programlisting>
+
+ <para>Innerhalb von Schleifen wird
+ <varname>$::form->{TEMPLATE_ARRAYS}{var}[$index]</varname>
+ bevorzugt, wenn vorhanden. Ein Beispiel findet sich in SL/DO.pm,
+ welches über alle Positionen eines Lieferscheins in Schleife
+ läuft:</para>
+
+ <programlisting>for $i (1 .. $form->{rowcount}) {
+ # ...
+ push @{ $form->{TEMPLATE_ARRAYS}{runningnumber} }, $position;
+ push @{ $form->{TEMPLATE_ARRAYS}{number} }, $form->{"partnumber_$i"};
+ push @{ $form->{TEMPLATE_ARRAYS}{description} }, $form->{"description_$i"};
+ # ...
+}</programlisting>
+ </sect3>
+
+ <sect3>
+ <title>%::myconfig</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>Das einzige Hash unter den globalen Variablen</para>
+ </listitem>
+
+ <listitem>
+ <para>Wird spätestens benötigt wenn auf die Datenbank
+ zugegriffen wird</para>
+ </listitem>
+
+ <listitem>
+ <para>Wird bei jedem Request neu erstellt.</para>
+ </listitem>
+
+ <listitem>
+ <para>Enthält die Userdaten des aktuellen Logins</para>
+ </listitem>
+
+ <listitem>
+ <para>Sollte nicht ohne Filterung irgendwo gedumpt werden oder
+ extern serialisiert werden, weil da auch der Datenbankzugriff
+ für diesen user drinsteht.</para>
+ </listitem>
+
+ <listitem>
+ <para>Enthält unter anderem Datumsformat dateformat und
+ Nummernformat numberformat</para>
+ </listitem>
+
+ <listitem>
+ <para>Enthält Datenbankzugriffinformationen</para>
+ </listitem>
+ </itemizedlist>
+
+ <para><varname>%::myconfig</varname> ist im Moment der Ersatz für
+ ein Userobjekt. Die meisten Funktionen, die etwas anhand des
+ aktuellen Users entscheiden müssen, befragen
+ <varname>%::myconfig</varname>. Innerhalb der Anwendungen sind dies
+ überwiegend die Daten, die sich unter <guimenu>Programm</guimenu>
+ -> <guimenuitem>Einstellungen</guimenuitem> befinden, bzw. die
+ Informationen über den Benutzer die über die
+ Administrator-Schnittstelle eingegeben wurden.</para>
+ </sect3>
+
+ <sect3>
+ <title>$::locale</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>Objekt der Klasse "Locale"</para>
+ </listitem>
+
+ <listitem>
+ <para>Wird pro Request erstellt</para>
+ </listitem>
+
+ <listitem>
+ <para>Muss auch für Tests und Scripte immer verfügbar
+ sein.</para>
+ </listitem>
+
+ <listitem>
+ <para>Cached intern über Requestgrenzen hinweg benutzte
+ Locales</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Lokalisierung für den aktuellen User. Alle Übersetzungen,
+ Zahlen- und Datumsformatierungen laufen über dieses Objekt.</para>
+ </sect3>
+
+ <sect3>
+ <title>$::lxdebug</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>Objekt der Klasse "LXDebug"</para>
+ </listitem>
+
+ <listitem>
+ <para>Wird global gecached</para>
+ </listitem>
+
+ <listitem>
+ <para>Muss immer verfügbar sein, in nahezu allen
+ Funktionen</para>
+ </listitem>
+ </itemizedlist>