
    MODULE

    Modularer Aufbau ist immer eine Gradwanderung. Einerseits möchte man flexibel bleiben, andererseits muss man genau festgelegten Regeln
    folgen. Für den Anwender ist ein modularer Aufbau etwas Feines, er braucht sich um nichts kümmern und letztendlich sollte alles so funk-
    tionieren, wie gewünscht.
    Anders sieht das für den Programmierer aus, der strengen Regeln bei der Installation folgen muss, damit auch alles da landet, wo es hin-
    gehört. Oftmals sind Dateien zu editieren und neue Dateien/Verzeichnisse anzulegen. Parameter müssen gesetzt werden und in Scripten, die
    mit Datenbanken arbeiten müssen neue Tabellen angelegt werden oder bestehende müssen erweitert werden. All das interessiert einen Anwender
    nicht.

    Seit 2016 habe ich (zumindest neue) Module in Unterverzeichnissen von <i>adressql/templates</i> abgelegt. Ein Beispiele sei das Verzeichnis

        templates/gallerie

    Der Grund ist ein ganz einfacher, ich führe bei allen Modulen ein chdir() in diese Verzeichnisse durch und sperre Module somit "quasi" ein.
    Ältere Module folgen diesem Prinzip zwar nicht zu 100%, sie sind aber schon derart fester Bestandteil von adresSQL, dass ich sie nicht mehr
    als Modul im eigentlichen Sinn betrachte.

    Erstellen wir also ein Testmodul:

        ANMERKUNG!

        Man wird u.U. nicht umhin kommen, sich mit einigen Variablen, die ich standardmässig setze, auseinander zu setzen. Das sind vor Allem
        Die Variablen <b>SESSION</b> und <b>$moddir</b>. Mit diesen Variablen lässt sich vieles "Voreingestellte" verwenden und das Rad muss nicht
        neu erfunden werden. Dazu kommt aber später ein eigener Punkt in dieser Hilfe.


    1.
    Was wir also zuerst brauchen ist ein Unterverzeichnis in adressql/templates, wo wir unsere Modulscripte ablegen also erstellen wir das
    Verzeichnis

            <b>adressql/templates/test</b>


    2.
    Das Zweite was wir brauchen ist eine Startdatei, die unser Modul startet, nennen wir sie <b>test.tpl</b> und legen wir sie in unserem
    Verzeichnis <b>adressql/templates/test</b> ab. Der Inhalt ist mit einigen kurzen Erklärungen versehen.
    (Diese Datei kann Wahlweise auch im Verzeichnis adressql/templates abgelegt werden, dann muss man sich um sein chdir() und seine Pfade
    aber selber kümmern bzw. absolute Pfade einsetzen.)

        <div style="width:60%; margin-left:6em;">
            <?php htmlspecialchars(highlight_string($code)); ?>
        </div>
        Machen wir dieses Template, mit seinen Inhalten, zu einem Standard für Module, kann eigentlich nichts mehr schief gehen. Im Kontainer
        (zwischen den DIV`s) kann nun der gesamte Code eingefügt werden.

        Das Template hat alle notwendigen Text und SQL-Funktionen, sowie das CSS-Stylesheet von adresSQL bereits includiert, Sie können sich also
        aus anderen Scripten Abfragen etc. herauskopieren. Beachten Sie dazu auch den Hinweis auf bestehenden Funktionen in dieser Hilfe.
        Der Aufruf <b>require_once("test_func.php");</b> verlangt eine Datei dieses Namens im Verzeichnis test.


    3.
    Nun legen wir einen Sprachparameter für unseren Modulnamen an (damit unsere Kartei auch einen Namen bekommt):

        Administration -> Grundeinstellungen -> Scriptsprache anpassen

        Ganz unten fügen wir im Feld Übersetzung unsere Ausgabe "Neues Testmodul" und im Feld Language Codewort "testmodul" (ohne Anführungszeichen)
        ein.


    4.
    Unser Modul muss zum Schluss noch eingetragen und aktiviert werden.

        Administration -> Grundeinstellungen -> Nav-Karteikarten anpassen

        Einen neuen Eintrag erstellen und folgende Felder ausfüllen:

            Language Codewort   Template    Verzeichnis     Überschrift     Aktiv
            <b>testmodul           test.tpl    test            $lng[testmodul]         &radic;</b>


        INFO!
        Der Eintrag <b>$lng[testmodul]</b> sorgt dafür, dass in der Überschrift der entsprechende Eintrag aus der Sprachdatei angezeigt wird. Achten Sie
        darauf, dass hier keine Anführungszeichen oder Singlequotes verwendet werden.

    Das war`s! Mehr brauchen wir nicht zu tun. Nach einem Browser-Refresh sollte eine neue Kartei <i><b>Neues Testmodul</b></i> zur Verfügung stehen.
    Damit keine Missverständnisse aufkommen, ich nutze selbst genau diesen Weg, um neue Module zu erstellen.

    Natürlich lässt sich die Installation des Moduls nahezu automatisieren, was wir als nächstes besprechen werden!

    <b>---------------------------------------------------------------------------------------------------------------------------------------</b>


    Module und Updates über das Admincenter installieren:
    -----------------------------------------------------

    adresSql bietet die Möglichkeit über den Adminpunkt "Update/Module verwalten" zusätzliche Module zu installieren oder Updates per Knopf-
    druck einzuspielen. Im Wesentlichen wird dabei eine Datei namens <b>setup.dat</b> verwendet. Beliben wir beim Beispiel von oben mit unserem
    Testmodul und der test.tpl!

    Wir packen den gesamten Ordner <i>test</i> inkl. aller Unterverzeichnisse und Dateien in eine ZIP-Datei (der Name ist egal). Rufen wir in der
    Administration den Punkt <i>"Update/Module verwalten"</i> auf und laden wir die ZIP-Datei hoch, wird sie im Verzeichnis <b>update</b> entpackt.
    Es entsteht ein Verzeichnisbaum unterhalb von uptdate mit allen Unterverzeichnissen und Dateien und wir müssen adresSQL nun nur noch mitteilen,
    was mit den einzelnen Daten passieren soll. Dazu dient die setup.dat.

    Die Installations-Datei hat für unser Testmodul folgenden Zeilenweisen Aufbau (ich bespreche die Einzelheiten weiter unten).

          <b>** trenner</b>
          <b><font color="red">^</font></b>
          <b>****</b>
          <b>** createdir</b>
          ./templates/test<b><font color="red">^</font></b>0777
          <b>****</b>
          <b>** startup</b>
          ./update/test.tpl<b><font color="red">^</font></b>templates/test/test.tpl<b><font color="red">^</font></b>0755<b><font color="red">^</font></b>testmodul<b><font color="red">^</font></b>test.tpl<b><font color="red">^</font></b>test<b><font color="red">^</font></b>$lng[testmodul]
          <b>****</b>
          <b>** files</b>
          ./update/test/test_func.php<b><font color="red">^</font></b>templates/test/test_func.php<b><font color="red">^</font></b>0755
          <b>****</b>
          <b>** language</b>
          language/de<b><font color="red">^</font></b>testmodul = Testmodul
          language/de<b><font color="red">^</font></b>probelauf = Probeausgabe
          <b>****</b>
          <b>** vars</b>
          vars/testmodul<b><font color="red">^</font></b>bla = hoppel
          <b>****</b>
          <b>** execute</b>
          ./update/install_testmodul.php
          <b>****</b>

       Die Datei besteht aus einzelnen Tag-Informationen, die durch <b>2 Sterne, einen Abstand und eine Bezeichnung</b> geöffnet und durch <b>4 Sterne</b>
       wieder geschlossen werden. Dazwischen stehen Informationen zu jeder Datei, jedem Verzeichnis, die ähnlich einer CSV-Datei aufgebaut sind.

       In obigem Beispiel sind diese Tags also

          ** trenner
          ** createdir
          ** startup
          ** files
          ** language
          ** vars
          ** execute

    Wir benötigen für unser Testmodul zwar nicht alle Tags, ich werde sie aber dennoch kurz besprechen.
    Welche Funktion jedem Trenner zugeordnet ist, ist in der Datei <b>/vars/.htmoddefs</b> hinterlegt. Hier steht der Einleitungs-Tag und die zu-
    gehörige Funktion die aufgerufen werden soll. Z.B.

        ** createdir    mod_create_dir

    bedeutet, dass der Tag ** createdir mit der Funktion mod_create_dir abgearbeitet werden soll. Alle abarbeitenden Funktionen finden sich in
    der Datei

            /templates/admin/update_mod_func.php.

    Der Datei .htmoddefs können Sie auch entnehmen welche weiteren Tags es gibt, für ein Modul brauchen wir aber nur die oben genannten.

        <b><i>ACHTUNG!!</i></b>
        Die Datei /vars/.htmoddefs legt genau fest, in welcher Reihenfolge die einzelnen Tags abgearbeitet werden. Das Update geht diese
        Datei Zeilenweise durch und arbeitet die Funktionen von oben nach unten ab. Das ist sinnvoll, da vor dem Kopierprozess der Datei
        <b>test.tpl</b> ins Verzeichnis <b>templates/test</b> natürlich erst das Verzeichnis erstellt werden muss. Die Reihenfolge, in der
        Sie in der setup.dat Tags setzen ist also egal, die Reihenfolge wird durch die Datei .htmoddef festgelegt.

    Nach jedem Tag werden Anweisungen hinterlegt, die in bestimmter Reihenfolge abgearbeitet werden. Je nachdem, ob man .var Dteien erweitern,
    Verzeichnisse erstellen oder Files kopieren möchte werden bestimmte Funktionen aufgerufen, die diese Anweisungen in Einzelteile zerlegen,
    neu zusammenbauen und abarbeiten. Die Tag-Namen sind NICHT frei wähl bar.

    Jeder Tag wird durch 4 Sterne geschlossen. Das Script weiss dann, dass ein neuer Tag abgearbeitet werden muss oder dass das Script
    beendet werden soll.

    Die Tags im Einzelnen und der Befehlsaufbau wie im Beispiel oben:

    <b>** trenner</b>

       <i><b><font color="red">^</font></b></i>

       Legt fest, mit welchem Trennzeichen die einzelnen Anweisungen zwischen den Tags zu trennen sind. Ich nutze standardmässig <b><font color="red">^</font></b>, da dieses
       Zeichen kaum für Texte oder CSV-Tateien eingesetzt wird und in Texten selten vorkommt. Sie können aber auch jedes andere Zeichen verwenden.

    <b>** createdir</b>

       <i>./templates/test<font color="red">^</font>0777</i>

       Gibt den Namen des Verzeichnisses an, gefolgt von den Rechten (chmod) die gesetzt werden sollen. Hier wird also das Verzeichnis
       templates/test (chmod 777) erstellt.

    <b>** startup</b>

       <b><i>./update/test.tpl<font color="red">^</font>templates/test/test.tpl<font color="red">^</font>0755<font color="red">^</font></b>testmodul<font color="red">^</font>test.tpl<font color="red">^</font>test<font color="red">^</font>$lng[testmodul]</i>

       Entspricht einem automatisierten Aufruf des Adminpunktes <b><i>Nav-Karteikarten anpassen</i></b>, dem nur ein Kopierprozess voraus-
       geht. Die ersten 3 Parameter sind der Kopierbefehl, die restlichen decken sich mit den Parametern aus "Nav-Karteikarten anpassen".

       Zerlegt man also die Zeile in die Einzelteile, bedeuten die einzelnen Werte

          * Quelle - Ziel - Rechte
          * Language-Codewort - Template - Verzeichnis - Überschrift (wie im genannten Adminpunkt)

       Zuerst wird der Kopervorgang angeben, also kopiere /update/test.tpl nach templates/test/test.tpl und setze die Rechte auf 755.
       Dann folgen die Parameter, die auch bei einer händischen Anlage eingegeben werden müssten, also:

            Language Codewort   Template    Verzeichnis     Überschrift
            <b>testmodul           test.tpl    test            $lng[testmodul]</b>


           Anmerkung!
           <i>** files</i> kopiert einfach Dateien von A nach B
           <i>** startup</i> kopiert nicht nur, sondern prüft einige Dinge und legt Berechtigungen für das Modul an. Eine Unterscheidung ist
           daher wichtig!


    <b>** files</b>****

       <i>./update/test/test_function.php<font color="red">^</font>templates/test/test_function.php<font color="red">^</font>0755</i>

       Diese Datei (test_func.php) haben wir zwar nicht in unserem Beispiel oben, dieser Punkt wird aber wohl der häufigst gebrauchte sein.
       Er kopiert Dateien von Quelle nach Ziel und setzt die entprechenden Rechte. Wichtig ist hier, dass die Pfade stimmen!

    <b>** language</b>

       <i>
       language/de<font color="red">^</font>testmodul = Testmodul
       language/de<b><font color="red">^</font></b>probelauf = Probeausgabe
       </i>

       Erweitert die Sprachdatei (hier die für deutsch) und hängt Einträge an die Datei an. Dieser Punkt entspricht unserem Punkt 3 aus
       unserem Beispiel oben.

       Da die Sprachdateien einen festen Aufbau haben sehen diese Einträge immer gleich aus.
       Der erste Parameter gibt die Sprachdatei an (die Datein haben die Endung .var, die Endung wird automatisch angehängt), der zweite
       Parameter ist der Eintrag, der der Sprachdatei hinzugefüt werden soll. Existiert eine Sprache nicht, wird die Datei neu angelegt.
       Das Update erkennt doppelte Spracheinträge und filtert diese heraus.

    <b>** vars</b>

       <i>
       vars/testmodul<font color="red">^</font>bla = hoppel
       </i>

       Einige Parameter des Scripts sind NICHT in der Datenbank angelegt, sondern liegen in Dateien.
       Diese Variablen-Dateien müssen in manchen Fällen ebenfalls mit Einträgen erweitert werden. Da die .var-Dateien je nach Funktion einen
       bestimmten Aufbau haben (manchmal sind es 2 Einträge je Zeile, manchmal z.B. 5), ist es notwendig das Update für jede Vardatei genau
       festzulegen. Entsprechend gibt es mehrere Funktionen, die verschiedene .var-Dateien erweitern und prüfen.

       Eine Update-Funktion, die einen beliebigen Eintrag an eine beliebige Datei hängt ist in Arbeit.


    <b>** execute</b>

       Kennzeichnet ein ausführbares Script, dass am Ende des Updates gestartet wird um z.B. Tabellen zu erzeugen oder Felder in Tabellen hin-
       zuzufügen oder zu löschen.

           ACHTUNG!!
           Executables werden nach dem Update automatisch gelöscht!

       Achten Sie darauf, dass diese Dateien per <i>iclude()</i> aufgerufen werden, also der Pfad zur Datei korrekt angeben wird. Also z.B.
       <i>
       ./update/install_testmodul.php
       </i>

    Weitere Tags sind in Arbeit b.z.w schon vorbereitet aber noch nicht in Verwendung.
