Processwire vfm-online.de


Autor: michael.hafner@vfm-online.de

Historie

Inhalt

  1. Einleitung (Admins, Nutzer:innen)
  2. Allgemeine Hinweise (Admins, Nutzer:innen)
  3. Installation (Admins)
  4. Grundlagen zum Zusammenspiel von Frontend und Backend (Admins, Nutzer:innen)
  5. Grundlagen zum Zusammenspiel von Frontend und Backend (Admins)
  6. Nutzerverwaltung (Admins)
  7. ANHANG: Site-Konfiguration (Admins)
  8. ANHANG: Bekannte Probleme, Workarounds (Admins)
  9. ANHANG: Änderung der Default-Sprache (Admins)

Einleitung

Zweck des Dokuments

Diese Notizen entstehen während der Einrichtung des Systems. Sie verstehen sich nicht als vollständige Systemdokumentation, und sie richten sich nicht ausschließlich an Entwickler-, Administrator- oder Endnutzer:innen.

Der Großteil des Textes dient als Gedankenstütze für administrative oder Entwicklungsaufgaben. Ein Teil des Textes ist für Anwender:innen geschrieben, die in der Pflegeoberfläche mehr tun, als Inhalte zu erfassen - also zum Beispiel Felder anlegen oder Templates definieren. Abschnitte dieser Art sind im Inhaltsverzeichnis gesondert ausgewiesen.

Das Dokument kann und soll von seinen Leser:innen nach Bedarf ergänzt bzw. aktualisiert werden. Da keine automatische Versionierung erfolgt, gilt folgende Regel:

Konventionen

Notation in diesem Dokument

Entwicklungsname des Projekts

Der Entwicklungsname des Projekts ist "otlet" (nach Paul Otlet (23.08.1868-10.12.1944)). Der String "otlet" wird überall verwendet, wo Abgrenzungen gegen Namensraum und -konventionen von Processwire notwendig sind oder deutlich gemacht werden sollen:

Pfadangaben

Das Dokument gibt Verzeichnispfade relativ zum Hauptverzeichnis von Processwire an.
Ein realer Pfad "/mnt/web023/a0/21/546221/htdocs/cms/processwire/site/config-dev.php" erscheint im Dokument also als "site/config-dev.php".

Begriffe, Abkürzungen

Backend
Die Pflege- und Administrationsoberfläche des Systems.
Frontend
Die Website, die die Inhalte des Systems anzeigt.

Allgemeine Hinweise

Installation

Das System wurde am 09.09.2020 in Version 3.0.165 installiert.

Schritte

Basiskonfiguration

Die Basiskonfiguration nach Aufruf Installscript:

Grundregel (Admins)

PW gliedert sich in zwei Hauptverzeichnisse, "/site" und "/wire". Das Verzeichnis "/site" Gehört dem Projekt, es ist von PW-Updates nicht betroffen; hier und nur hier findet die seitenspezifische Konfiguration statt, hier werden Templates und Scripte abgelegt. Das Verzeichnis "/wire" gehört der Anwendung Processwire, es wird bei Updates von PW überschrieben, hier ändert das Projekt nichts.

Grundlagen zum Zusammenspiel von Frontend und Backend

  1. Inhalte, die das Frontend (FE; die Seite) anzeigt, werden im Backend (BE) erfasst.
  2. Im BE erfasste Inhalte werden in Feldern gespeichert.
  3. Einige Felder sind von PW vordefiniert; der BE-User kann weitere Felder hinzufügen.
    1. Es können beliebig viele Felder hinzugefügt werden.
      1. Felder werden im BE unter "Verwaltung" > "Felder" > "Neues Feld hinzufügen" angelegt.
      2. Beim Hinzufügen eines Feldes legt der BE-User einen Datentyp fest, der angibt, welche Art von Daten ein Feld speichern kann. Datentypen sind z.B. "Text" (für einfache Zeichenfolgen), "Datum" (für Kalenderdaten), "Options" (für vordefinierte Listen zugelassener Einträge).
        1. Der Typ wird bei der Anlage des Feldes unter "Typ" angegeben.
        2. Fehlt ein benötigter Feldtyp in der Liste, muss er möglicherweise installiert werden: "Module" > "Core", Listeneinträge, die mit "FieldType" beginnen.
  4. Ein neu definiertes Feld ist nicht ohne weitere Schritte nutzbar. Es muss zunächst in ein "Template" eingebunden werden.
    1. Ein Template ist (im wesentlichen) eine Liste von Feldern, die einer Seite zugeordnet wird. Siehe hierzu Kap. Templates
    2. Um ein Feld einem Template hinzuzufügen, im BE "Verwaltung" > "Templates" > [Name des Templates] aufrufen, dann Liste "Feld hinzufügen" öffnen.
    3. Ein Feld kann mehreren Templates hinzugefügt werden.

Templates

Template Sets

Das System arbeitet mit externen HTML-Templates (z.Z. Bootstrap Moderna, https://bootstrapmade.com/free-bootstrap-template-corporate-moderna/).

Ladeprozess

Bei einem Frontend-Aufruf mit delayed output (im Gegensatz zu direct output) lädt PW defaultmäßig (ab Werk) folgende Dateien in der angegebenen Reihenfolge:

site/templates/_init.php
site/templates/_func.php Geladen per Include von "site/templates/_init.php"
site/templates/_main.php

Hinweise:

Diese Dateien wurden unverändert gelassen, um jederzeit auf das Basis-Template "ab Werk" zurückgreifen zu können.

Die vfm-Seite verwendet im Regelfalls das folgende Ladeverfahren:

site/templates/_vfm_init.php
site/templates/_func.php Geladen per Include in "site/templates/_vfm_init.php"
site/templates/_otletlib.php
site/templates/_main.php
site/templates/otlet_templatesets/[Aktives Templateset-Verzeichnis]/_vfm_init.php Geladen per Include in "site/templates/_vfm_main.php"
site/templates/otlet_templatesets/[Aktives Templateset-Verzeichnis]/_vfm_func.php Geladen per Include in "site/templates/otlet_templatesets/[Aktives Templateset-Verzeichnis]/_vfm_init.php"
site/templates/otlet_templatesets/[Aktives Templateset-Verzeichnis]/_vfm_main.php Geladen per Include in "site/templates/_vfm_main.php"
Aktives Templateset-Verzeichnis: Das Aktive Templateset wird in site/config.php in der Variable $otlet_buffer['active_templateset'] definiert (z.B. $otlet_buffer['active_templateset'] = 'moderna';) und von dort in $config->otlet_active_templateset sowie in $config['otlet']['active_templateset'] geladen. Durch Aufruf der Funktion otlet_templateset($templateset) kann der Wert in $config->otlet_active_templateset zur Laufzeit geändert werden, ohne die Konfiguration anzupassen. Das Verzeichnis des aktiven Templateset ist über die Variablen $config['dirs']['rel']['templatesets'] oder $config->otlet_active_templateset_dir. abrufbar. $config->otlet_active_templateset_dir wird analog zur Laufzeitanpassung des Templateset-Namens durch Aufruf von otlet_templateset($templateset) angepasst.

Die angepassten Dateien "_vfm_[*].php" in "site/templates" spielen in einer ähnlichen Weise zusammen, wie das Konstrukt der Processwire-Basicpage (Default ab Werk), leiten aber die Steuerung weiter an eine wiederum gleich konzipierte Dateiengruppe im Verzeichis des aktiven Templatesets. Sie bilden eine Abstraktionsschicht, die es ermöglicht, das Templateset durch eine einfache Konfigurationseinstellung zu wechseln, ohne die Verweise in den Templates des PW-Backends ebenfalls ändern zu müssen. Sie erlauben außerdem, designspezifische PHP-Funktionen (angesiedelt in "site/templates/otlet_templatesets/[Aktives Templateset-Verzeichnis]/_vfm_func.php") von designübergreifenden (angesiedelt in "site/templates/_func.php" und site"/templates/_otletlib.php") sauber voneinander zu trennen.

Aufgaben und Anbindung der geladenen Dateien

site/templates/_vfm_init.php Definition designübergreifender Variablen, die nicht zur Basiskonfiguration gehören. Derzeit: "$otlet_title = $page->get('headline|title');", "$otlet_content = $page->body;" und "$otlet_homepage = $pages->get('/');". Diese Datei wird in der Templateverwaltung des PW-Backends in vfm-Templates als Preload definiert: "Verwaltung" > "Templates" >" > [Templatename] > "Dateien" > "Datei voranstellen": Eintrag "_vfm_init.php2, "Deaktiviere automatisches Voranstellen von Datei: _init.php" ankreuzen.
site/templates/_func.php Diese Datei stellt Funktionen bereit, die unabhängig vom gewählten Templateset für das Rendern der Seite benötigt werden (z.B. eine Ladefunktion für die Einzeldateien des aktiven Seitentemplates).
site/templates/_otletlib.php Diese Datei stellt allgemeine Funktionen bereit, die nicht unmittelbar dem Rendern der Seite dienen (I/O-Funktionen, Logging, Konverter usw.).
site/templates/_main.php Diese Datei liest den Namen des aktiven Templatesets und leitet die Steuerung an die Dateien "_vfm_init.php" und "_vfm_main.php" des betreffenden Templateverzeichnisses weiter. Diese Datei wird in der Templateverwaltung des PW-Backends in vfm-Templates als Preload definiert: "Verwaltung" > "Templates" >" > [Templatename] > "Dateien" > "Datei anhängen": Eintrag "_vfm_main.php", "Deaktiviere automatisches Anhängen von Datei: _main.php" ankreuzen.
site/templates/[Aktives Seitentemplate] Dateien der Namensform "vfm_[Name].php" (z.B. "vfm_home.php") leiten ihren Aufruf an eine gleichnamige Datei im Verzeichnis "site/templates/otlet_templatesets/[Aktives Templateset-Verzeichnis]" weiter. Automatische Einbindung durch PW zur Laufzeit, gesteuert durch Namensgleichheit von Backend-Template und PHP-Datei. Beispielsweise bewirkt die Bindung einer Seite an das Template "vfmHome" im Backend, dass beim Aufruf der Seite im Frontend die Datei "site/templates/vfmHome.php" aufgerufen wirde.
site/templates/otlet_templatesets/[Aktives Templateset-Verzeichnis]/_vfm_init.php Diese Datei übernimmt die Aufgaben der PW-Defaultdatei "site/templates/_init.php", also die Initialisierung von Einstellungen, die für das Rendern der Seite mit dem aktiven Layout (Templateset) erforderlich sind. Beispielsweise liest sie alle HTML-Templates des Maintemplates (des gleichbleibenden Teils des Seitendesigns) in das Array $otlet_templates_main und stellt ein Array $otlet_templates_page für alle HTML-Templates der gerade aufgerufenen Seite bereit. Sie lädt außerdem (ebenfalls analog zu "site/templates/_init.php") die Datei "site/templates/otlet_templatesets/[Aktives Templateset-Verzeichnis]/_vfm_func.php".
site/templates/otlet_templatesets/[Aktives Templateset-Verzeichnis]/_vfm_func.php Diese Datei übernimmt die Aufgaben der PW-Defaultdatei "site/templates/_func.php", also die Bereitstellung von Funktionen, die für das Rendern der Seite mit dem aktiven Layout (Templateset) erforderlich sind.
site/templates/otlet_templatesets/[Aktives Templateset-Verzeichnis]/_vfm_main.php Diese Datei übernimmt die Aufgaben der PW-Defaultdatei "site/templates/_main.php": Sie enthät den gesamten HTML- und PHP-Code, der für die Anzeige des statischen Teils der Seite (Header, Footer, Menü etc.) erforderlich sind. Sie bindet außerdem den Inhalt der gerade aufgerufenen Seite in den variablen Teil des Designs ein ("echo $otlet_content;").
site/templates/otlet_templatesets/[Aktives Templateset-Verzeichnis]/[Aktives Seitentemplate] Dateien dieser Namensform (z.B. "vfm_home.php") werden von einer gleichnamigen Datei in "site/templates" aufgerufen. Sie lesen den Inhalt der aufgerufenen Seite aus der PW-Datenbank und tragen ihn in ein HTML-Template in einem gleichnamigen Verzeichnis in "site/templates/otlet_templatesets/[Aktives Templateset-Verzeichnis]" ein.

Beispiel-Ablauf (leicht vereinfacht, ohne _func-Dateien):

Nutzerverwaltung

Grundkonzept

Die Nutzerverwaltung basiert auf drei Bausteinen:

Berechtigungen (Permissions) Eine Berechtigung erlaubt einem Nutzer die Ausfürung einer bestimmten Aktion im System: Seiten (in einem bestimmten Bereich) einzusehen, Seiten (einer bestimmten Art) anzulegen, Seiten zu ändern usw..
Rollen (Roles) Rollen bündeln Berechtigungen unter einem Namen.
Nutzer (Users) Nutzer sind (aus Sicht des Systems) Gruppen von Rollen, die mit einem Namen und Authentifizierungsinformation verknüpft sind.
  • Einem Nutzer sind eine (Guest) bis mehrere Rollen zugeordnet.
  • Einer Rolle sind null bis mehrere Nutzer zugeordnet.
  • Einer Rolle sind null bis mehrere Berechtigungen zugeordnet.
  • Eine Berechtigung ist einer bis mehreren Rollen zugeordnet.

Registrierungsverfahren: Teil 1

  1. Eine Person ruft über den Menüpunkt "Anmelden | Registrieren" das Anmeldefenster auf.
  2. Sie wählt die Option "Register for an account".
  3. Sie trägt sich mit ihrer Mailadresse ein, wählt ein Passwort und sendet das Formular ab.
  4. Sie erhät eine E-Mail mit einem Bestätigungslink bzw. einem Confirmation Code (z.B. BYRjLbNaacWRHo4xyvDu6DZQeLeBft1kQVFJDsuL).
  5. Sie bestätigt ihre Registrierung per Link oder Eintrag des Confirmation Codes in das Formular.

Registrierungsverfahren: Teil 2

  1. Nach Schritt 1 sind dem neuen Nutzer automatisch die Rollen "Guest" und "Login-Register" zugeordnet.
  2. Fall A: Alle Rollen, die dem neuen Nutzer zugeordnet werden sollen, exisitieren bereits. In diesem Fall werden dem Nutzer unter "Zugriff" > "Benutzer" > [Name des Nutzers] > "Benutzerrollen" alle Rollen zugewiesen, der er erhalten soll.
  3. Fall B: Eine oder mehrere Rollen, die dem neuen Nutzer zugeordnet werden sollen, exisitieren noch nicht. In diesem Fall wird eine neue Rolle unter "Zugriff" > "Benutzerrollen" > "Neu hinzufügen" angelegt und mit Berechtigungen ausgestattet. Danach weiter wie in Fall A.

ANHANG: Änderung der Default-Sprache

Das System ist mehrsprachig aufgesetzt; die Default-Sprache in Processwire ist Englisch. Dieser default wurde wie folgt geändert:

    Change homepage's default language
    Problem
    You have a multi-language site, and started with for example English as primary, and French as secondary language 
    (so the English homepage is example.org/, the French one example.org/fr). Later in the project you want to set French as primary.

    Solution
    Here is what you can do to redirect the home page '/' to the German home page:

    Set page names for both languages for the home page ('en' for English, 'de' for German)
    In the LanguageSupportPageNames settings, choose the option "No - Root URL performs a redirect to: /name/". 
    When you go to the root url '/' it will redirect you to '/en/'
    Finally, create a module to hook into Session::redirect to force the redirection of the root url to the French 
    translation as follows:
     'LanguageDefault',
                    'version' => 1,
                    'summary' => 'A work around to changing the default language.',
                    'href' => 'https://processwire.com/talk/topic/9322-change-default-language-for-homepage/?p=89717',
                    'singular' => true,
                    'autoload' => true,
                );
            }
            /**
             * Initialize the module
             *
             * ProcessWire calls this when the module is loaded. For 'autoload' modules, this will be called
             * when ProcessWire's API is ready. As a result, this is a good place to attach hooks.
             *
             */
            public function init() {
                $this->session->addHookBefore('redirect', $this, 'setDefaultLanguage');
                // The hook checks whether you are viewing the home page, and whether you are redirecting to the English url, 
                // and if so, it changes the url to the French url
            }

            public function setDefaultLanguage($event) {
                if ($this->page->id == 1 && $event->arguments(0) == $this->page->localUrl('default')) {
                  $event->arguments(0, $this->page->localUrl('de'));
                }
            }
        }
    

Quelle (angepasst): https://processwire-recipes.com/recipes/change-homepages-default-language/

ANHANG: Site-Konfiguration

Anmerkungen, Hinweise

Konfiguration

    $otlet_buffer = array();
    $otlet_buffer['active_templateset'] = 'moderna';
    $otlet_buffer['params'] = array(
      'msglevel' => 3,
    );
    $otlet_buffer['urls'] = array(
      'templates' => $config->urls->templates,
      'templatesets' => $config->urls->templates.'otlet_templatesets/',
      'active_templateset' => $config->urls->templates.'otlet_templatesets/'.$otlet_buffer['active_templateset'].'/',
      'images' => $config->urls->templates.'otlet_images/',
      'styles' => $config->urls->templates.'otlet_styles/',
    );
    $otlet_buffer['dirs'] = array(
      'rel' => array(
        'active_templateset' => 'otlet_templatesets/'.$otlet_buffer['active_templateset'].'/',
      )
    );
    $otlet_buffer['files'] = array(
      'logo_home' => $config->urls->templates.'otlet_images/vfm-logo.jpg',
      'logo_std' => $config->urls->templates.'otlet_images/vfm-logo.jpg',
      'favicon' => $config->urls->templates.'otlet_images/favicon.ico',
    );
    $otlet_buffer['placeholders'] = array(
      'openingtag' => '',
      'closingtag' => ''
    );
    $otlet_buffer['messages'] = array(
      0 => array('Variable not set', 3),
      1 => array('File included', 3),
    );
    $config->otlet = $otlet_buffer;
    unset($otlet_buffer);
  

ANHANG: Bekannte Probleme, Workarounds