README.md

Outline

REDAXO AddOn :: MBlock

Mit MBlock ist es moglich, innerhalb eines Moduls beliebig viele Datenblocke zu erzeugen. Diese konnen dann einfach per Button oder Drag & Drop sortiert werden. Die erweiterte Version bietet Copy & Paste Funktionalitat und einen Offline/Online Toggle fur einzelne Blocke.

English: MBlock lets you create an unlimited number of data blocks within a single module. These data blocks can be sorted per click or drag & drop. The enhanced version provides copy & paste functionality and an offline/online toggle for individual blocks.

Please note: The examples are valid for MForm version 8 and higher. MBlock now requires the bloecks addon (^5.2.0) for modern drag & drop functionality.

Hinweis fur markitup- und ckeditor-Nutzer

Copy & Paste funktioniert leider nicht!

Es sollte in den betreffenden Modulen deaktiviert werden.

Beispiel

1, // Minimale Anzahl Items (werden initial angezeigt) 'max' => 10, // Maximale Anzahl Items 'template' => 'modern', // Template-Name 'copy_paste' => false, // Copy & Paste aktivieren 'online_offline' => true // Online/Offline Toggle , hidden field muss angelegt sein. ]);">echo MBlock::show(1, $form, [
'min' => 1, // Minimale Anzahl Items (werden initial angezeigt)
'max' => 10, // Maximale Anzahl Items
'template' => 'modern', // Template-Name
'copy_paste' => false, // Copy & Paste aktivieren
'online_offline' => true // Online/Offline Toggle , hidden field muss angelegt sein.
]);


Features / Funktionen

Grundfunktionen / Core Features

• Beliebig viele Datenblocke pro Modul erstellen
• Drag & Drop Sortierung mit bloecks addon (^5.2.0)
• Minimale/Maximale Anzahl von Blocken definierbar
• MForm Integration fur professionelle Formulare
• Template System mit Prioritatsladung
• Mehrsprachigkeit (DE/EN)

Erweiterte Funktionen / Advanced Features (MBlock 4.0)

• Online/Offline Toggle - Blocke aktivieren/deaktivieren ohne loschen
• Copy & Paste - Komfortable Duplizierung von Inhalten
• Frontend API Methoden - filterByField(), sortByField(), groupByField()
• Schema.org Support - SEO-optimierte JSON-LD Generierung
• Erweiterte Datenabfrage - Online/Offline/All Modi
• Template-Prioritat - Custom templates uberschreiben defaults
• Media-ID Konflikt-Schutz - Bessere Warnung bei ID-Uberschneidungen

Editor Support (MBlock 4.5)

• TinyMCE Support - Volle Unterstutzung fur TinyMCE (v4-v8)
• CKEditor 5 - Verbesserte Copy & Paste Funktionalitat

Namespace Migration (Version 4.0)

MBlock fuhrt Namespaces ein! Fur neue Projekte wird die Verwendung des Namespace empfohlen:

// Empfohlen: Neue Namespace-Syntax
use FriendsOfRedaxo\MBlock\MBlock;

$items = MBlock::getDataArray("REX_VALUE[1]");
echo MBlock::show(1, $mform->show());

Vollstandig ruckwartskompatibel! Bestehende Module funktionieren weiterhin ohne Anderungen:

// Weiterhin unterstutzt: Legacy-Syntax (fur Bestandscode)
$items = MBlock::getDataArray("REX_VALUE[1]");
echo MBlock::show(1, $mform->show());

Migration Guide

• Neue Module: Verwenden die use FriendsOfRedaxo\MBlock\MBlock; Syntax
• Bestehende Module: Funktionieren ohne Anderungen weiter
• Deprecated-Warnung: Alte Syntax wird in Version 5.0 entfernt

Installation

MBlock erfordert:

# Via REDAXO Installer
# 1. Gehe zu System > Installer
# 2. Suche nach "mblock"
# 3. Installiere mblock zusammen mit bloecks

API & Datenabfrage

Zentrale getDataArray() Methode

Mit Namespace (empfohlen fur neue Projekte):

use FriendsOfRedaxo\MBlock\MBlock;

// Alle MBlock-Daten abrufen
$allItems = MBlock::getDataArray("REX_VALUE[1]");

// Nur Online-Blocke (fur Frontend) - EMPFOHLEN
$onlineItems = MBlock::getDataArray("REX_VALUE[1]", 'online');

// Nur Offline-Blocke (fur Backend-Previews)
$offlineItems = MBlock::getDataArray("REX_VALUE[1]", 'offline');

// Convenience-Methoden
$onlineItems = MBlock::getOnlineDataArray("REX_VALUE[1]");
$offlineItems = MBlock::getOfflineDataArray("REX_VALUE[1]");

Legacy-Syntax (weiterhin unterstutzt):

// Alle MBlock-Daten abrufen
$allItems = MBlock::getDataArray("REX_VALUE[1]");

// Nur Online-Blocke (fur Frontend) - EMPFOHLEN
$onlineItems = MBlock::getDataArray("REX_VALUE[1]", 'online');

// Nur Offline-Blocke (fur Backend-Previews)
$offlineItems = MBlock::getDataArray("REX_VALUE[1]", 'offline');

// Convenience-Methoden
$onlineItems = MBlock::getOnlineDataArray("REX_VALUE[1]");
$offlineItems = MBlock::getOfflineDataArray("REX_VALUE[1]");

Frontend API - Datenverarbeitung

Mit Namespace (empfohlen):

$categoryItems) { echo "

" . rex_escape($category) . "

"; foreach ($categoryItems as $item) { echo "

" . rex_escape($item['title']) . "

"; } } // Anzahl begrenzen (Pagination) $topItems = MBlock::limitItems($items, 5); $nextItems = MBlock::limitItems($items, 5, 5); // SEO Schema.org JSON-LD generieren $schema = MBlock::generateSchema($items, 'Person', [ 'name' => 'name', 'jobTitle' => 'position', 'image' => 'photo', 'email' => 'email' ]); echo '';">
use FriendsOfRedaxo\MBlock\MBlock;

$items = MBlock::getOnlineDataArray("REX_VALUE[1]");

// Nach Feld filtern
$newsItems = MBlock::filterByField($items, 'category', 'news');
$activeItems = MBlock::filterByField($items, 'status', 'active');

// Nach Feld sortieren
$sortedByName = MBlock::sortByField($items, 'name', 'ASC');
$sortedByDate = MBlock::sortByField($items, 'date', 'DESC', 'date');
$sortedByPrice = MBlock::sortByField($items, 'price', 'DESC', 'numeric');

// Nach Feld gruppieren
$grouped = MBlock::groupByField($items, 'category');
foreach ($grouped as $category => $categoryItems) {
echo "

" . rex_escape($category) . "

";
foreach ($categoryItems as $item) {
echo "

" . rex_escape($item['title']) . "

";
}
}

// Anzahl begrenzen (Pagination)
$topItems = MBlock::limitItems($items, 5);
$nextItems = MBlock::limitItems($items, 5, 5);

// SEO Schema.org JSON-LD generieren
$schema = MBlock::generateSchema($items, 'Person', [
'name' => 'name',
'jobTitle' => 'position',
'image' => 'photo',
'email' => 'email'
]);
echo '';

Legacy Array-Filterung (falls Array schon vorhanden)

$data = rex_var::toArray("REX_VALUE[1]");

// Online/Offline Check (MBlock 4.0)
foreach ($data as $item) {
if (MBlock::isOnline($item)) {
// Item ist online
echo rex_escape($item['title']);
}
}

// Legacy-Methoden (deprecated, bitte getDataArray() verwenden)
$onlineItems = MBlock::getOnlineItems($data);
$offlineItems = MBlock::getOfflineItems($data);

Templates & Theming

Template-System mit Dropdown-Auswahl

MBlock bietet ein modernes Template-System mit grafischer Auswahl uber ein Dropdown-Menu in den AddOn-Einstellungen. Das System kopiert automatisch die CSS-Dateien in den assets/ Ordner und sorgt fur optimale Performance.

Template-Auswahl

Die Template-Auswahl erfolgt uber die MBlock-Einstellungen:

1. Gehe zu Addons > MBlock > Einstellungen
2. Wahle ein Template aus der Dropdown-Liste
3. Klicke "Speichern" - Das CSS wird automatisch kopiert
4. Das Template ist sofort aktiv

Dark Mode Support

Die mitgelieferten Templates unterstutzen Dark Mode:

• REDAXO Theme Detection (body.rex-theme-dark)
• Browser Preference (@media (prefers-color-scheme: dark))
• Bootstrap 5 Dark Mode ([data-bs-theme="dark"])

Custom Templates erstellen

Eigene Templates konnen im data/ Ordner erstellt werden:

redaxo/data/addons/mblock/templates/
+-- my_custom_theme/
| +-- template.ini # Template-Konfiguration
| +-- mblock_wrapper.ini # HTML-Wrapper fur alle Items
| +-- mblock_element.ini # HTML-Template fur einzelne Items
| +-- my_custom_theme.css # Template-Styling (gleicher Name wie Ordner!)

Wichtig: Die CSS-Datei muss den gleichen Namen wie der Template-Ordner haben!

Modulbeispiele / Module examples

MBlock enthalt einige Modulbeispiele. Diese finden sich auf der MBlock-Seite im REDAXO-Backend. An dieser Stelle werden nur zwei Beispiele aufgelistet -- mit Unterstutzung durch MForm und ohne --, um zu zeigen, wie MBlock funktioniert.

English: MBlock contains several module examples. You'll find them on the MBlock page within the REDAXO backend. At this point, we want to show two examples only -- one with MForm support and another one without -- to demonstrate how MBlock works.

Example 1: team members (requires MForm addon)

Input:

addTextField("$id.0.name", array('label'=>'Name')); // media button $mform->addMediaField(1, array('label'=>'Avatar')); // Online/Offline Status (hidden field fur Toggle-Funktion) $mform->addHiddenField("$id.0.mblock_offline", '0'); // MBlock anzeigen (Copy & Paste ist automatisch aktiv) echo MBlock::show($id, $mform->show(), array( 'min' => 2, 'max' => 4 ));">
// Modernisiertes Beispiel mit MForm

use FriendsOfRedaxo\MForm;

// base ID
$id = 1;

// init mform mit moderner MForm Syntax
$mform = MForm::factory();

// fieldset
$mform->addFieldsetArea('Team member');

// textinput
$mform->addTextField("$id.0.name", array('label'=>'Name'));

// media button
$mform->addMediaField(1, array('label'=>'Avatar'));

// Online/Offline Status (hidden field fur Toggle-Funktion)
$mform->addHiddenField("$id.0.mblock_offline", '0');

// MBlock anzeigen (Copy & Paste ist automatisch aktiv)
echo MBlock::show($id, $mform->show(), array(
'min' => 2,
'max' => 4
));

Output:

'; if ($name) { echo '

' . $name . '

'; } if ($mediaId) { $media = rex_media::get($mediaId); if ($media) { echo ''; } } echo '

'; } // Debug (nur wahrend Entwicklung) // echo '

';
// dump(MBlock::getDataArray("REX_VALUE[1]")); // Alle Items inkl. Offline
// echo '

';">
use FriendsOfRedaxo\MBlock\MBlock;
// Verbesserte Ausgabe
$items = MBlock::getOnlineDataArray("REX_VALUE[1]"); // Nur Online-Items

foreach ($items as $item) {
$name = rex_escape($item['name'] ?? '');
$mediaId = $item['REX_MEDIA_1'] ?? '';

echo '

';
if ($name) {
echo '

' . $name . '

';
}
if ($mediaId) {
$media = rex_media::get($mediaId);
if ($media) {
echo '
alt="' . rex_escape($media->getTitle()) . '" />';
}
}
echo '

';
}

// Debug (nur wahrend Entwicklung)
// echo '

';
// dump(MBlock::getDataArray("REX_VALUE[1]")); // Alle Items inkl. Offline
// echo '

';

Example 2: team members (without MForm)

Input:

true, 'copy_paste' => true ));">
use FriendsOfRedaxo\MBlock\MBlock;
// base ID
$id = 1;

// html form
$form = <<

Team member

Name

Avatar

REX_MEDIA[id="1" widget="1"]

EOT;

// MBlock mit Features
echo MBlock::show($id, $form, array(
'online_offline' => true,
'copy_paste' => true
));

Output:

'; echo '

' . $name . '

'; if ($mediaId && ($media = rex_media::get($mediaId))) { echo ''; } echo '

'; }">
use FriendsOfRedaxo\MBlock\MBlock;
// Sicher und modern
$items = MBlock::getOnlineDataArray("REX_VALUE[1]");

foreach ($items as $item) {
$name = rex_escape($item['name'] ?? '');
$mediaId = $item['REX_MEDIA_1'] ?? '';

echo '

';
echo '

' . $name . '

';

if ($mediaId && ($media = rex_media::get($mediaId))) {
echo '
alt="' . rex_escape($media->getTitle()) . '" />';
}
echo '

';
}

MBlock verwendet eine modulare JavaScript-Architektur, die den Code in drei logische Module aufteilt:

• mblock-core.js - Base utilities, Validierung, Ubersetzungen (384 Zeilen)
• mblock-management.js - DOM-Manipulation, Sortable-Handling (1008 Zeilen)
• mblock-features.js - Copy/Paste, Online/Offline Toggle, REDAXO Widgets (815 Zeilen)

Dies verbessert die Wartbarkeit, reduziert Code-Redundanz und ermoglicht besseres Debugging.

Das Build-System kombiniert automatisch die modularen Dateien und erstellt optimierte Versionen:

• Node.js (Version 14 oder hoher)
• npm (wird normalerweise mit Node.js installiert)

1. Terminal offnen und in das Build-Verzeichnis wechseln:

   cd redaxo/src/addons/mblock/build

2. Build-Script ausfuhren:

   ./build.sh

3. Automatischer Prozess:

   • Kombiniert die 3 modularen Dateien zu einer einzigen Datei
   • Erstellt mblock-combined.js (Zwischenergebnis)
   • Aktualisiert mblock.js (Development-Version)
   • Erstellt mblock.min.js (Production-Version mit Terser-Minifizierung)
   • Generiert Source Map fur Debugging

Das System unterstutzt verschiedene Asset-Loading Modi (konfigurierbar in boot.php):

• auto (Standard) - Automatische Erkennung basierend auf Debug-Modus

  • Development: mblock.js (kombinierte Datei)
  • Production: mblock.min.js (minifiziert)

• modular - Ladt 3 separate Dateien (erweiterte Debugging-Moglichkeiten)

  • mblock-core.js - mblock-management.js - mblock-features.js

• combined - Immer kombinierte Datei (mblock.js)

• prod - Immer minifizierte Datei (mblock.min.js)

Die modulare Architektur bringt folgende Verbesserungen:

Code-Reduktion: ~200 Zeilen Redundanz eliminiert
Reusable Functions: MBlockUtils, MBlockClipboard, MBlockOnlineToggle
Unified Event Handling: Zentralisierte Event-Konfiguration
Better Error Handling: Konsistente Fehlerbehandlung
Memory Management: Automatisches Event-Cleanup
Performance: Cached Selectors und optimierte Algorithmen

Das neue System bietet verbesserte REDAXO Widget-Unterstutzung:

• REX_LINK Copy/Paste - Artikel-IDs und Namen werden korrekt kopiert
• REX_MEDIA Copy/Paste - Media-Dateien mit Metadaten
• Widget-Reinitialization - Onclick-Handler werden automatisch aktualisiert
• Auto Name Fetching - Artikel-Namen werden automatisch per AJAX geholt

• Smart Combining - Intelligente Kombination der modularen Dateien
• Advanced Minification - Terser mit optimierten Settings (2 Compression-Passes)
• Source Maps - Fur einfaches Debugging der minifizierten Datei
• Performance Stats - Detaillierte Grossen- und Kompressions-Statistiken
• Error Handling - Robuste Fehlerbehandlung und Validierung
• Auto-Update - Synchronisation zwischen Development- und Production-Dateien

Falls Probleme auftreten:

1. Node.js Version prufen:

   node --version # sollte >= 14.0.0 sein

2. Dependencies neu installieren:

   cd redaxo/src/addons/mblock/build
   rm -rf node_modules
   npm install

3. Modulare Dateien prufen:

   ls -la ../assets/mblock-*.js
   # Sollte alle 3 modularen Dateien anzeigen

4. Manuelle Terser Installation:

   npm install terser

Fur MBlock-Entwicklung:

1. Bearbeite die modularen Dateien:

   • assets/mblock-core.js
   • assets/mblock-management.js
   • assets/mblock-features.js

2. Build ausfuhren nach Anderungen:

   cd build && ./build.sh

3. Testen in REDAXO (Debug-Modus nutzt automatisch die Development-Version)

4. Production-Deploy: Die minifizierte Version wird automatisch generiert

Friends Of REDAXO

• REDAXO
• FriendsOfREDAXO

Project Leads

• Joachim Dorr
• Thomas Skerbis