MODX 2 Mini-Workshop

[Jo]

Tutorial (TuTo) - Workshop - MODX - Anleitung - Starthilfe

MODX 2.8.x Revolution benötigt mindestens (server-requirements MODX 2):

• PHP 5.6, seit MODX 3 mind. PHP 7.2 oder höher
• MySQL 5.6, besser MariaDB 10.1 oder höher
• Apache 2.2.x, besser NGINX 1.8 oder höher

Update: Seit dem 30. März 2022 ist MODX 3 raus:

• Getting Started
• upgrading from 2.x to 3.0
• server-requirements MODX 3

Kurzinstallationsanleitung & Tipps für MODX 2
Das ist keine 100%ige Schritt-für-Schritt Anleitung und setzt entsprechende Kenntnisse voraus. Mehr Infos siehe MODX Documentation und Troubleshooting+Installation

MODX ist ein Content Management Framework (CMF)
zitiere aus Wikipedia: "Ein Content-Management-Framework (CMF) ist ein Komponenten-Framework zur schnelleren Entwicklung von Content-Management-Systemen (CMS)"

Ein CMS generiert euch die HTML-Seiten dynamisch, in der Art

Code Auswählen Erweitern

domainname.de/index.php?id=1oder besser suchmaschinenoptimiert (SEO), wie etwa

Code Auswählen Erweitern

domainname.de/home.html
Vorwort
MODX benötigt Kenntnisse in HTML und CSS. Vergleicht es nicht mit WordPress oder Joomla, das wäre wie "Äpfel mit Birnen vergleichen" - MODX ist anders. Im Allgemeinen würde ich zusammenfassen das MODX ein Framework für Entwickler und kein out-of-the-box klick mich zusammen Website-Builder ist.

MODX verwaltet Content und liefert ein Markup, das bis ins Detail festgelegt werden kann – und auch muss. Nach der Installation liefert MODX eine leere weiße Seite. Ein einfaches Template stelle ich euch hier vor. Es ist sehr leicht ein x-beliebiges Design nach zubauen oder ein CSS-Framework einzubauen -> Schlagwort: Responsive Webdesign. MODX ist also dein Backend – und DU bist das Frontend! MODX liefert die Strukturen mit denen der Content aufbereitet wird, so dass z.B eine jQuery Bildergalerie damit rennt.

MODX ist Multi-Domain fähig, früher hatte ich für jede Domain ein CMS installiert und mußte jede einzelne pflegen. Heute benutze ich nur wenige MODX Installationen dafür.

Meine Killer-Features sind TV's, Kontexte und natürlich die Output Filter von MODX!


1.) Download
MODX-Revolution 2.8.x - Traditional Installation Package - Link: modx.com


2.) Installation
Benötigt wird natürlich ein Webserver - oder installiert das CMF in einer lokalen xampp Umgebung (Apache for Linux, Windows + Mac) - der als Systemvoraussetzung mindestens Apache 2.2, PHP 5.6 und MySQL 5.6 hat; safe_mode=off und mod_rewrite, wenn benutzerfreundliche URLs verwendet werden sollen. Damit das Package Management funktioniert muss cUrl und zip auf dem Server installiert sein. Siehe auch Debian Webserver einrichten.

WICHTIG:

• Eintrag date.timezone = Europe/Berlin in der php.ini (ab PHP 5.3)
• Eintrag session.gc_probability = 1 in der php.ini (siehe unten Punkt 12)
• Eintrag suhosin.get.max_value_length = 4096 in der suhosin.ini - wenn das Schutzsystem Suhosin aktiviert ist
  (sonst gibt es Probleme mit gzip, die Settings compress_js=1 als auch compress_css=1 funktionieren dann nicht und der Manager liefert euch eine leere Seite)
  
• magic_quotes_gpc in der php.ini deaktivieren (magic_quotes_gpc = off)
• der Manager mag kein WHM ModSecurity, kann aber angepasst werden - siehe auch hier

Entpackt das ZIP-Archiv lokal und übertragt es sinnvollerweise in einem extra Ordner (z.B. /modx) per FTP-Programm (z.B. FileZilla) auf euren Webserver, dann ruft man per Browser den Ordner /setup auf.

Von Susan Ottwell gibt es auf github ein PHP Script das MODX Revolution lädt und installiert oder ein update mit einem Klick macht. Auch interessant: UpgradeMODX Package von Bob Ray.

Um Probleme mit Sonderzeichen zu vermeiden, stellt man als Datenbank-Kodierung "utf8_general_ci" ein (*Zeichensatz nachträglich konvertieren: siehe unten). In phpMyAdmin ist diese Einstellung unter "Kollation" zu finden. Ebenso lasse ich die Spracheinstellung auf Englisch - um in den englischen Foren von MODX die richtige Fragen stellen zu können. Hat alles geklappt, sollte aus Sicherheitsgründen das Setup-Verzeichnis gelöscht werden.

Die Login-Seite wird per Browser im Ordner /manager gestartet.
Dieser Pfad sollte aus Sicherheitsgründen geändert werden. Siehe dazu Hardening MODX Revolution.

Nachtrag:
Wem das wwwrun-Problem stört, welches bei vielen billigen Hostern in Verbindung mit CMS auftritt, sollte dieses beim Hoster nachfragen.
Systembedingt am sichersten ist es, wenn PHP unter einer einmaligen(!) uid/gid des jeweiligen Webs läuft. Dazu wird eine Wrappertechnik eingesetzt (suPHP, suEXEC, FastCGI, etc.). Im übrigen ist hier dann auch das gesamte "wwwrun-Problem" gelöst, weil es erst gar nicht auftritt. FTP-User, Web-User und PHP-User benutzen alle genau denselben Systemuser, welcher nur im eigenen Web sinnvollen Zugriff hat - sofern keine 777er-Rechte gesetzt werden!

Eure chmod-Rechte auf einem Linux-Server sollten dann immer für Ordner 0755 und für Dateien 0644 haben!


3.) Erste Schritte nach der Installation

Der Manager teilt sich in drei Bereiche auf: oben das Menü, links sind die Resources (eure Dokumente), Elements (Templates, TVs, Chunks, Snipptes) und Files.

a) Reiter Files
Standardmäßig verwendet MODX den Ordner "assets" als Ablage z.B. für Templates und Bilder. Zur besseren Übersicht lege ich hier auch "templates", "scripts", "content" und "content/images" an. Dieses ist alles per Kontext-Menü möglich, ebenso das Hochladen von Dateien. 

b) Webseitennamen ändern
Dazu rufen wir im Menü "System" -> "System Settings" auf. Unter dem Punkt "core" nach "Site" filtern und ändern den Eintrag "Site name", die Speicherung erfolgt automatisch.

c) 24h-Anzeige und deutsches Format (setlocale)
System Settings unter Area "Back-end Manager" die Einstellung manager_time_format auf "G:i" und manager_week_start auf 1 ändern. Ab Revo 2.2.x in der Area "Lexicon and Language" die Einstellung locale auf "de_DE.UTF-8" und in der Area "System and Server" die Einstellung date_timezone auf "Europe/Berlin".

d) Dateiauswahl Ordner (MODX >= 2.2.0)
Ab Revo 2.2 wird das per Media Sources gesteuert. Siehe auch: User Media Sources!



4.) Inhalte
OK, legen wir erste Inhalte im Reiter "Resourcen" im Container "Home" an. Alle neuen Resourcen unter einem Container sind Dokumente. Testet es einfach mal durch: umbenennen, verschieben, kopieren und neu anlegen - ich finde das alles sehr übersichtlich.


5.) Extras installieren
Wer Dokumente nicht als HTML-Code eingeben will, installiert sich als erstes den CKEditor oder TinyMCE - einen Rich-Text-Editor (RTE / wysiwyg) - per "Extras" -> "Installer".
Wichtig: wer UTF-8 benutzt sollte den TinyMCE im "System Settings" die Einstellung "Entity Encoding" auf "raw" umstellen (beim CKEditor ist UTF-8 Standard :- ).

Ebenso installiere ich als einer der ersten Extras natürlich den "wayfinder".
Der Wayfinder ist ein MODX-Snippet, dessen Hauptzweck die Erzeugung von Navigationsmenüs ist, die sich automatisch anpassen, wenn Änderungen am MODX-Dokumentenbaum vorgenommen werden.

Nachtrag: Das pdoMenu von pdoTools ist schneller als der Wayfinder und für neue Projekte benutze ich nur noch pdoTools. Siehe dazu auch meine Beispiele pdoTools.

Mehr Extras: Revolution Extras.


6.) Das erste Template
Baut euch ein komplettes HTML Grundgerüst - als Vorlage kann jede beliebige Seite dienen - oder benutzt ein Gridsystem wie z.B. 960gs. Für mich ist das eines der vielen Vorteile von MODX gegenüber anderen Systemen. Dann kopiert man das Grundgerüst in ein MODX Template und ersetzt alle dynamische Teile mit MODX Platzhaltern wie z.B. [[Wayfinder? &startId=`0`]] für die Navigation und [[*content]] für den Inhalt.

Einfaches xhtml Beispiel:
Erstellen im Reiter "Elements" unter "Templates", hier ein einfaches Standard Template:

Code Auswählen Erweitern

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>[[*pagetitle]] | [[++site_name]]</title>
<meta http-equiv="Content-Type" content="text/html; charset=[[++modx_charset]]" />
<meta name="keywords" content="blabla, blabla, blabla, blabla" />
<meta name="description" content="meine Homepage" />
<base href="[[!++site_url]]"></base>
<link rel="stylesheet" href="assets/templates/css/style.css" type="text/css" />
</head>

<body>
<div id="header">
<h1>[[++site_name]]</h1>
</div>
<div id="menu">
[[Wayfinder? &startId=`0` &level=`3`]]
</div>
<div id="content">
<h2>[[*pagetitle]]</h2>
[[*content]]
</div>
</body>
</html>
Das ist ein ausbaubares Template-Grundgerüst mit den Platzhaltern [[++site_url]], [[++site_name]], [[*pagetitle]] und [[*content]]. Ein ! vor dem Platzhalter deaktiviert den Cache (uncached). Damit die Webseite ein automatisches Menü erstellt, bauen wir das Snippet "Wayfinder" ein.
Mit [[++...]] lassen sich beliebige Systemeinstellungen einfügen. Die Platzhalternamen stehen unter "System" -> "System Settings" in der Spalte "Key". Auch Chunks und Template Variablen (TV's) werden auf diese Art eingefügt.

Was noch fehlt ist ein Stylesheet (CSS), z.B. mit dem Framework 960.gs.


HTML-Grundkenntnisse, wie z.B. die Struktur <html><head><body> oder der hexadezimale Farbcode (#000 = sw / #fff = ws) und etwas CSS wie margin+padding (Aussen+Innenabstand), sollte man kennen. Auch die css Identifizierung eines Elements sollten klar sein. Beispiel: Eine id (#header) darf nur einmal vorkommen und ist für eine eindeutige Identifizierung eines Elements gedacht. Eine class (.picture) kann mehreren Elementen zugeordnet werden. Auch ist es möglich beide zu benutzen, z.B:  <div id="footer" class="grid_16"> oder auch <div id="footer" class="grid_16 frame"> (also 2 Klassen).

Schickt eure Seite durch einen Validator - nur um sicher zu sein das auch andere Browser alles richtig verstehen.


7.) User als Editor anlegen und Rechte vergeben
Revolution Permissions

Rolle und User anlegen - Beispiel:

7a) Eine neue Rolle 'Editor' als 'Manager' anlegen
Security > Access Controls > TAB ROLES:
Name: "Editor" mit der Authority: '10'

  und

im TAB USER GROUPS > 'Manager' anlegen

dann im TAB USER GROUPS per Kontextmenu auf Manager > Update User Group

Dort auf "Add Context" klicken und folgende Settings eintragen:
    Context: mgr
    Minimum Role: Editor - 10
    Access Policy: Content Editor
    Save

  und

    Context: web
    Minimum Role: Editor - 10
    Access Policy: Content Editor
    Save

Dieser "Content Editor" kann unter Security > Access Controls > TAB ACCESS POLICY per Kontextmenu (Update Policy) mehr oder weniger Rechte erhalten.
Damit diese Access Policies nach einem Update nicht zurückgesetzt werden, sollte der "Content Editor" als Vorlage kopieren und umbenannt werden.


7b) User anlegen
Security > Manage Users > TAB GENERAL INFORMATIONEN:
Neuen User anlegen
und im TAB ACCESS PERMISSIONS > Add User to Group:
User Group: Manager
Role: Editor
dann SAVE!


7c) nur wenn MODX < 2.2.x (ab 2.2 wird das per per Media Sources gesteuert)
Security > Manage Users > den User per Kontextmenu > Update User
Im TAB SETTINGS > Create New
hier wenn gewollt - 2 Settings anlegen, damit der User nur auf einen bestimmten Ordner zugreifen kann:

Code Auswählen Erweitern

Key: filemanager_path
Name: setting_filemanager_path
Field Type: Textfield
Namespace: core
Area Lexicon Entry: file
Value: assets/content/images/user/
  und

Code Auswählen Erweitern

Key: filemanager_url
Name: setting_filemanager_url
Field Type: Textfield
Namespace: core
Area Lexicon Entry: file
Value: assets/content/images/user/

7d) Security > Flush Permissions!


8.) User nur Webzugriff auf bestimmte Ressourcen erlauben

Benutzergruppe erstellen: Security -> Resource Groups:

- Name eintragen
- Contexts: web (wenn mehr - mit einem Komma trennen)
- Create Parallel User Group anhaken
- speichern

Unter Security -> Access Controls, in Tab User Groups wird dann automatisch eine Ressourcengruppe mit dem gleichen Namen erstellt. Eigene Rollen (Roles) erstellen ist nicht notwendig.

Jetzt noch einfach die Benutzer mit der Rolle Member der Benutzergruppe zuweisen und die zu schützenden Ressourcen der Ressourcengruppe zuweisen.

Security > Flush Permissions!


9.) Eine Resource nur dem Admin anzeigen
a) Resource Groups: eine Group anlegen, z.B. "nurAdmin (mgr)"
b) User Group Administrator:
im TAB "Resource Group Access" legt ihr eine "Resource Group" an, z.B.:
nurAdmin (mgr) - Super User - Resource - mgr
(Context nur mgr, sonst wird die Resource auch im web gesperrt)
c) Flush Permissions
d) Per "Resource Groups" oder im jeweiligen Resource-TAB "Access Permissions" die Resource nur für den Admin sichtbar machen.


10.) Multi-Domain - das geht auch ohne XRouting oder ContextRouter mit einem eigenen Plugin
Using One Gateway Plugin to Manage Multiple Domains

Damit ein Anpassen der index.php nicht notwendig ist, benutze ich ein ganz einfaches ContextSwitch Plugin - Beispiel:

Code Auswählen Erweitern

<?php
# System Events: OnHandleRequest!

    if ($modx->context->get('key') == 'mgr') {return;}

       switch($modx->getOption('http_host')) {
            case 'www.deineDomain2.tdl:80':
            case 'www.deineDomain2.tdl':
                $modx->switchContext('web2');
                break;

            case 'www.deineDomain3.tdl:80':
            case 'www.deineDomain3.tdl':
                $modx->switchContext('web3');
                break;

            default:
                $modx->switchContext('web');
                break;
        }


11.) SEO-freundliche Seiten aktivieren
(wenn alles läuft)
System Settings -> core -> "Use Friendly URLs" und "Use Friendly Alias Path" aktivieren,
dann die ht.access in .htaccess umbenennen und den Cache leeren!

Damit die Webadresse immer mit www aufgerufen wird (SEO-freundlich umleiten) sollte sowas in der .htaccess Datei nicht fehlen:

Code Auswählen Erweitern

# FORCE WWW ON ALL URLs
RewriteEngine on
RewriteCond %{HTTP_HOST} !^www\.
RewriteRule ^(.*)$ http://www.%{HTTP_HOST}/$1 [R=301,L]

12.) Wenn in eurer php.ini der Eintrag "session.gc_probability = 0" ist, wird mit der Zeit die Tabelle modx_session sehr groß
Quelle: Sessions garbage collector not used?
Per default sollte der Wert 1 sein, keine Ahnung warum z.B. der Linux Ubuntu Server hier diesen Wert auf 0 gesetzt hat :-(

wenn die php.ini nicht geändert werden kann, hier 3 Alternativen:

• Im Manager -> Manage -> LOGOUT ALL USERS können alle SESSIONS in der DB sofort manuell gelöscht werden (modx_session)
• Das Package UpgradeMODX löscht bei einem Upgrade alle SESSIONS und die ~/core/cache Dateien
• erstellt euch ein Plugin delAllSessions welches alte SESSIONS z.B. bei einem Manager Login oder alle beim Clear Cache löscht:

Code Auswählen Erweitern

<?php
# delete sessions (sql-table modx_session)
# https://github.com/modxcms/revolution/issues/775
# System Events: OnManagerLogin, OnCacheUpdate

# delete old sessions after Manager Login
# this isn't necessary if php.ini "session.gc_probability = 1"
if ($modx->event->name == 'OnManagerLogin') {
    # $modx->log(modX::LOG_LEVEL_ERROR, '[delAllSessions] table old modx_session deleted');
    $gcMaxlifetime = (integer) $modx->getOption('session_gc_maxlifetime', null, @ini_get('session.gc_maxlifetime'), true);
    $access = time() - $gcMaxlifetime;
    $modx->exec("
        DELETE FROM {$modx->getTableName('modSession')} WHERE `access` < {$access};
        OPTIMIZE TABLE {$modx->getTableName('modSession')};
    ");
}

# ATTENTION! this delete all sessions by Menu -> Manage -> Clear Cache
# please use only if you know what you are doing!
if ($modx->event->name == 'OnCacheUpdate') {
    # $modx->log(modX::LOG_LEVEL_ERROR, '[delAllSessions] table all modx_session deleted');
    $modx->exec("
        DELETE FROM {$modx->getTableName('modSession')};
        OPTIMIZE TABLE {$modx->getTableName('modSession')};
    ");
}


MODX kann aber noch viel mehr -
die Grenzen gebt ihr vor, nicht das System!

Noch ein Beispiel für eine "globale Einstellungen Ressource":
Einfach eine mySettings Ressource anlegen ("Hide From Menus" aktivieren und "Published" deaktivieren!) und mit einem dummy Template die gewünschten TVs erstellen. Dann in euren Template an der Stelle wo das hin soll diese Ressource per getResourceField aufrufen:

Code Auswählen Erweitern

[[getResourceField? &id=`42` &field=`BannerText` &processTV=`1` &default=``]]oder mit dem FastField Plugin:

Code Auswählen Erweitern

[[#42.tv.BannerText]]

Die Backticks vor und hinter den Parametern findet man auf der Tastatur neben der Backspace-Taste (mit gedrückter SHIFT-Taste). Ein normales Hochkomma funktioniert nicht.



* MySQL Zeichensatz konvertieren:
(z.B.: latin1_swedish_ci nach utf8_general_ci)

• Backup erstellen!
• phpMyAdmin Kollation auf 'utf8_general_ci' stellen.
• Via phpMyAdmin die DB exportieren und mit einem Editor (UTF-8 ohne BOM) per suchen/ersetzten die Zeichenfolge 'latin1' in 'utf8' ändern. Alte DB löschen und diese Datei wieder per Import hochladen.