Theme

Redaxo 5 AddOn zum Verwalten aller Projektdateien für Frontend und Backend.

Ordner

Nach der Installation kann auf der Seite Einstellungen des Theme-AddOns mit Klick auf den Button Theme-Ordner installieren eine Ordnerstruktur erstellt werden. Die Ordnerstruktur wird auf der Ebene des Ordners redaxo im Ordner theme erstellt.

Der Ordner theme enthält zwei Ordner: public und private:

• Im Ordner public können alle öffentlich zugänglichen Dateien, wie z.B. JavaScript und CSS abgelegt werden.
• Im Ordner private können alle Dateien abgelegt werden, die vor dem Zugriff von außen geschützt werden sollen. Er enthält eine .htaccess, die den Zugriff beschränkt.

Die weiteren Unterordner sind ein Vorschlag zur Strukturierung der Projektdateien. Jede andere Variante ist auch möglich.

Die vorgegebene Struktur hat den Vorteil, dass diese Ordner über PHP-Methoden ansprechbar sind, bzw. wie die entsprechenden Ordner eines AddOns automatisch eingebunden werden:

• Alle im Ordner lib enthaltenen PHP-Klassen werden automatisch über autoload eingebunden.
• Alle im Ordner lang enthaltenen Dateien mit der Endung .lang werden automatisch über i18n eingebunden.
• Alle Dateien mit der Endung .php im Ordner inc werden per include_once in der boot.php des AddOns eingebunden.
• Der Ordner fragments wird über rex_fragment::addDirectory eingebunden.
• Der Ordner ytemplates wird über rex_yform::addTemplatePath eingebunden, wenn YForm installiert ist.
• Der Ordner redaxo ist ein Platzhalter für die Synchronisierungsdaten des AddOns Developer.

Dateien

Neben der .htaccess werden weitere Dateien erstellt, die - sofern sie nicht gelöscht wurden - vom AddOn automatisch eingebunden werden:

• backend.css und backend.js werden auf jeder Seite des Redaxo-Backends geladen. So können auf einfache Weise zusätzliche Scripte, Stile oder Webfonts für das Backend eingebunden werden. Diese Funktion kann in den Einstellungen des Theme-AddOns aktiviert oder deaktiviert werden.
• functions.php wird im Ordner inc angelegt (siehe oben) und dient nur als schnelle Starthilfe. Sie kann auch umbenannt, gelöscht oder durch andere Dateien ersetzt werden.

Developer

Wenn das AddOn Developer installiert ist, gibt es die zusätzliche Option, die Synchronisierung der Templates, Module, Actions und YForm-E-Mail-Templates in den Theme-Ordner umzuleiten. Die Synchronisierung in den Data-Ordner wird dadurch deaktiviert.

PHP-Methoden

Pfade / URL

theme_url

Analog zu rex_url werden relative URLs zurückgegeben.

// $filename ist immer optional und kann auch ein Pfad sein. 
$filename = "path/to/file";

// Gibt eine URL im Ordner "theme" zurück. 
$url = theme_url::base($filename);

// Gibt eine URL im Ordner "theme/public/assets" zurück. 
$url = theme_url::assets($filename);

theme_path

Analog rex_path werden absolute Serverpfade zurückgegeben.

// $filename ist immer optional und kann auch ein Pfad sein. 
$filename = "path/to/file";

// Gibt einen Pfad im Ordner "theme" zurück.
$path = theme_path::base($filename);

// Gibt einen Pfad im Ordner "theme/private/fragments" zurück.
$path = theme_path::fragments($filename);

// Gibt einen Pfad im Ordner "theme/private/inc" zurück.
$path = theme_path::inc($filename);

// Gibt einen Pfad im Ordner "theme/private/lang" zurück.
$path = theme_path::lang($filename);

// Gibt einen Pfad im Ordner "theme/private/lib" zurück.
$path = theme_path::lib($filename);

// Gibt einen Pfad im Ordner "theme/private/views" zurück.
$path = theme_path::views($filename);

// Gibt einen Pfad im Ordner "theme/private/ytemplates" zurück.
$path = theme_path::ytemplates($filename);

// Gibt einen Pfad im Ordner "theme/public/assets" zurück.
$path = theme_path::assets($filename);

Daten

theme_setting

Eine einfache Registry mit der Möglichkeit, beim Abruf Default-Werte zu definieren. Damit ist es z.B. möglich, in der Datei functions.php zentral Einstellungen zu definieren, die in Modulen oder Templates abgerufen werden können.

// Erstellt einen Eintrag.
// Die Daten müssen immer als Array mit alphanumerischen Schlüsseln übergeben werden. 
// Wird die Methode mehrfach mit dem gleichen Schlüssel aufgerufen, 
// werden die Daten über array_merge zusammengeführt.
theme_setting::setKey($key, [
    'index1' => 'data1', 
    'index2' => 'data2', 
    ...
]);

// Holt einen Eintrag. Dabei kann ein Array mit Vorgabe-Werten übergeben werden.
// Die Arrays werden über array_merge() zusammengeführt. 
// Ist ein Schlüssel in beiden Arrays vorhanden, wird der des Default-Arrays 
// mit denen des ausgelesenen Arrays überschrieben.
$data = theme_setting::getKey($key, [
    'index1' => 'data1', 
    'index2' => 'data2', 
    ...
]);

Assets

theme_assets

Eine Klasse zum Verwalten und Einbinden der CSS-Stylesheets und JavaScript-Dateien einer Website zur Laufzeit.

Anwendung

Es ist möglich, Assets über verschiedene Instanzen der Klasse zu gruppieren. Die Asset-Gruppen können entweder über Methoden der Klasse oder mithilfe einer eigenen REX_VAR an beliebiger Stelle im Quellcode der Website ausgegeben werden.

Wichtig: einige Komfortfunktionen stehen nur bei Nutzung der REX_VAR zur Verfügung.

// Erzeugt eine Instanz der Klasse. In der Regel genügt eine Instanz zur Verwaltung aller Assets einer Website.
// Bei Bedarf kann durch die Angabe von $id zwischen verschiedenen Instanzen unterschieden werden. 
// - $id (string) optional, ist $id nicht angegeben, wird 'default' verwendet.
$assets = theme_assets::getInstance($id);

// Beispiele
$assets = theme_assets::getInstance(); // Verwenden der Instanz 'default'

$assets = theme_assets::getInstance('assets'); // Verwenden der Instanz 'assets'

Cache-Buster

Der Cache-Buster hilft, das Browser-Caching einer Website zu beeinflussen. Es handelt sich dabei um einen String, der als Query an die URL einer Asset-Datei angehängt wird.

Wichtig: Der Cache-Buster wird für eine komplette Instanz gesetzt.

// 1. Aktuelle Systemzeit
// Damit wird die Asset-Datei bei jedem Ladevorgang neu vom Server geholt.
// Der Dateiname wird um die Zeichenfolge '?t=XXXXXXXXXX' ergänzt. XXXXXXXXXX entspricht dabei dem Timestamp der aktuellen Systemzeit.
// ACHTUNG: Diese Einstellung ist nur während Entwicklung und Debugging sinnvoll.
$assets->setCacheBuster('time')

// 2. Änderungsdatum einer Datei
// Damit wird die Datei neu vom Server geladen, wenn sie geändert wurde. 
// Der Dateiname wird um die Zeichenfolge '?f=XXXXXXXXXX' ergänzt. XXXXXXXXXX entspricht dabei dem Timestamp des Änderungsdatums der Datei.
$assets->setCacheBuster('filetime')

// 3. individueller String 
// Damit ist eine manuelle Versionierung der Assets möglich. 
// Der Dateiname wird um die Zeichenfolge '?v=XXXXXXXXXX' ergänzt. XXXXXXXXXX entspricht dabei dem angegebenen String.
$assets->setCacheBuster('1.0.0')

// 4. Cache-Buster löschen
$assets->setCacheBuster('')

CSS-Daten

Es können sowohl URL von CSS-Dateien übergeben werden, als auch Inline-Styles.

// Setzt die URL einer Datei
// - $id (string) ein String zur Kennung der Datei
// - $data (string) die URL der Datei. Hierfür kann auch theme_url verwendet werden
// - $media (string) das Media-Attribut der Datei, optional
// - $attributes (array) ein Array mit zusätzlichen Attributen, im Format ['Attribut' => 'Wert'], optional
$assets->setCss($id, $data, $media, $attributes);

// Setzt einen CSS-String
// - $id (string) ein String zur Kennung der Daten
// - $data (string) der CSS-String. Der String wird innerhalb von <style>-Tags ausgegeben 
// - $media (string) das Media-Attribut der Daten, optional
$assets->setCssInline($id, $data, $media);

// Löscht die URL einer Datei
// - $id (string) eine zuvor gesetzte Kennung der Datei
$assets->unsetCss($id);

// Löscht einen CSS-String
// - $id (string) eine zuvor gesetzte Kennung der Daten
$assets->unsetCssInline($id);

// Gibt die gesammelten CSS-Dateien der Instanz als <link>-Tags aus
// HINWEIS: im Normalfall ist es komfortabler die REX_VAR REX_THEME_ASSETS[] zu nutzen
echo $assets->getCss();

// Gibt die gesammelten CSS-Daten der Instanz als <link>-Tags aus
// HINWEIS: im Normalfall ist es komfortabler die REX_VAR REX_THEME_ASSETS[] zu nutzen
echo $assets->getCssInline();

JavaScript-Daten

Es können sowohl URL von JavaScript-Dateien übergeben werden, als auch Inline-Skripte.

// Setzt die URL einer Datei
// - $id (string) ein String zur Kennung der Datei
// - $data (string) die URL der Datei. Hierfür kann auch theme_url verwendet werden
// - $header (bool) Flag zur Ausgabe im Header. true gibt die Datei im Header aus, false im Footer, optional - default ist false
// - $attributes (array) ein Array mit zusätzlichen Attributen, im Format ['Attribut' => 'Wert'], optional
$assets->setJs($id, $data, $header, $attributes);

// Setzt einen JavaScript-String
// - $id (string) ein String zur Kennung der Daten
// - $data (string) der JavaScript-String. Der String wird innerhalb von <script>-Tags ausgegeben 
// - $header (bool) Flag zur Ausgabe im Header. true gibt die Datei im Header aus, false im Footer, optional - default ist false
// - $attributes (array) ein Array mit zusätzlichen Attributen, im Format ['Attribut' => 'Wert'], optional
$assets->setJsInline($id, $data, $header, $attributes);

// Löscht die URL einer Datei
// - $id (string) eine zuvor gesetzte Kennung der Datei
// - $header (bool) Flag zur Ausgabe im Header. true entfernt die Datei im Header, false im Footer, optional - default ist false
$assets->unsetJs($id, $header);

// Löscht einen JavaScript-String
// - $id (string) eine zuvor gesetzte Kennung der Daten
// - $header (bool) Flag zur Ausgabe im Header. true entfernt die Daten im Header, false im Footer, optional - default ist false
$assets->unsetJsInline($id, $header);

// Gibt die gesammelten JavaScript-Dateien der Instanz zurück
// HINWEIS: im Normalfall ist es komfortabler die REX_VAR REX_THEME_ASSETS[] zu nutzen
// - $header (bool) Flag zur Ausgabe im Header. true gibt die zum Header zugeordneten Daten aus, false die zum Footer zugeordneten, optional - default ist false
echo $assets->getJs($header);

// Gibt die gesammelten JavaScript-Daten der Instanz zurück
// HINWEIS: im Normalfall ist es komfortabler die REX_VAR REX_THEME_ASSETS[] zu nutzen
// - $header (bool) Flag zur Ausgabe im Header. true gibt die zum Header zugeordneten Daten aus, false die zum Footer zugeordneten, optional - default ist false
echo $assets->getJsInline($header);

HTML-Daten

Es können HTML-Strings übergeben werden. Nützlich, um z.B. zusätzliche Meta-Tags zu setzen

// - $id (string) ein String zur Kennung der Daten
// - $data der HTML-String. Der String wird unverändert ausgegeben.  
// - $header (bool) Flag zur Ausgabe im Header. true gibt die Datei im Header aus, false im Footer, optional - default ist false
$assets->setHtml($id, $data, $header);

// Löscht einen HTMl-String
// - $id (string) eine zuvor gesetzte Kennung der Daten
// - $header (bool) Flag zur Ausgabe im Header. true entfernt die Datei im Header, false im Footer, optional - default ist false
$assets->unsetHtml($id, $header);

// Gibt die HTML-Daten der Instanz zurück
// HINWEIS: im Normalfall ist es komfortabler die REX_VAR REX_THEME_ASSETS[] zu nutzen
// - $header (bool) Flag zur Ausgabe im Header. true gibt die Datei im Header aus, false im Footer, optional - default ist false
echo $assets->getHtml($header);

Extension Points

Die Klasse theme_assets bietet mehrere Extension Points zur Beeinflussung der Ausgabe:

• THEME_ASSETS_CSS
• THEME_ASSETS_CSS_INLINE
• THEME_ASSETS_JS
• THEME_ASSETS_JS_INLINE
• THEME_ASSETS_HTML

Über sie kann z.B. die Minifizierung der Asset-Dateien umgesetzt werden.

Steuerung der Extensions

// Es ist möglich pro Instanz eine Aktion zu definieren, die an die __Extension Points__ übergeben wird.   
$assets->setAction($action);

REX_VAR REX_THEME_ASSETS[]

REX_THEME_ASSETS[] kann statt der Getter-Methoden von theme_assets innerhalb von Templates und Modulen verwendet werden.

Sie hat gegenüber den Klassenmethoden den Vorteil, dass sie das Einschleusen von Daten in Header und Footer erleichtern. So ist es z.B. möglich, in Modulen Assets anzugeben, die im HTML-Header eines Templates eingebunden werden. Dafür wird intern der Extension-Point OUTPUT_FILTER genutzt.

// - "id" die Kennung der Instanz, wie bei theme_assets::getInstance() angegeben, optional - default ist 'default'
// - "type" der Typ der Ausgabe. Er entspricht den Methodennamen in Kleinbuchstaben, also: 'css', 'cssinline', 'js', 'jsinline' oder 'html'
// - "header" Flag für die Header- oder Footer-Gruppe. 1 für Header, 0 für Footer, optional - default ist 0
REX_THEME_ASSETS[id=instanz type=typ header=1]

// Beispiele
REX_THEME_ASSETS[type=js] // JavaScript der Instanz 'default' im Footer ausgeben

REX_THEME_ASSETS[id=assets type=js header=1] // JavaScript der Instanz 'assets' im Header ausgeben

REX_THEME_ASSETS[id=assets type=css] // CSS der Instanz 'assets' ausgeben

FriendsOfREDAXO/minify

Das AddOn FriendsOfREDAXO/minify zur Minifizierung von CSS- und JavaScript-Dateien wird über eine zusätzliche Klasse unterstützt.

// Aktiviert die Unterstützung des AddOns FriendsOfREDAXO/minify.
// Es werden automatisch die Dateien einer Instanz gruppiert und minifiziert. 
// Muss vor theme_assets::getInstance() aufgerufen werden. Am besten am Anfang der Datei functions.php platzieren. 
theme_minify::init();

$assets = theme_assets::getInstance();
// Nach der Aktivierung stehen diese Aktionen zur Verfügung:
// CSS und JavaScript minifizieren
$assets->setAction(`minify`);
// Nur CSS und minifizieren
$assets->setAction(`minify_css`);
// Nur JavaScript minifizieren
$assets->setAction(`minify_js`);

Beispiele

Beispiel 1: eine Instanz

functions.php

theme_assets::getInstance()
    // Styles
    ->setCss('styles', theme_url::assets('styles/main.css'))
    // JavaScript im Header
    ->setJs('jquery', theme_url::assets('vendor/jquery/jquery.min.js'), true)
    ->setJsInline('inline', 'alert("Dies ist ein Beispiel!");', true)
    // JavaScript im Footer
    ->setJs('demo', theme_url::assets('vendor/demo/scripts/demo.js'))
    ->setJs('scripts', theme_url::assets('scripts/main.js'));

Template

Die Ausgabe richtet sich nach der Position der REX_VARs.

<!DOCTYPE html>
<html>
    <head>
        ...
        REX_THEME_ASSETS[type=css]
        REX_THEME_ASSETS[type=js header=1]
        REX_THEME_ASSETS[type=jsinline header=1]
    </head>
    <body>
        ...
        REX_THEME_ASSETS[type=js]
    </body>
</html>

HTML

<!DOCTYPE html>
<html>
    <head>
        ...
        <link media="all" href="/theme/public/assets/styles/main.css" rel="stylesheet" type="text/css" />
        <script src="/theme/public/assets/vendor/jquery/jquery.min.js"></script>
        <script>/*<![CDATA[*/
            alert("Dies ist ein Beispiel!");
        /*]]>*/</script>
    </head>
    <body>
        ...
        <script src="/theme/public/assets/vendor/demo/scripts/demo.js"></script>
        <script src="/theme/public/assets/scripts/main.js"></script>
    </body>
</html>

Beispiel 2: mehrere Instanzen

functions.php

theme_assets::getInstance('libraries')
    ->setJs('jquery', theme_url::assets('vendor/jquery/jquery.min.js'), true)
    ->setJs('demo', theme_url::assets('vendor/demo/scripts/demo.js'));
    
theme_assets::getInstance('inline')->setJsInline('inline', 'alert("Dies ist ein Beispiel!");', true);
    
theme_assets::getInstance()
    ->setCss('styles', theme_url::assets('styles/main.css'))
    ->setJs('scripts', theme_url::assets('scripts/main.js'));

Template

Die Ausgabe richtet sich nach der Position der REX_VARs. Einige REX_VARs finden keine Werte.

<!DOCTYPE html>
<html>
    <head>
        ...
        <!--Instanz "libraries"-->
        REX_THEME_ASSETS[id=libraries type=css]
        REX_THEME_ASSETS[id=libraries type=js header=1]
        <!--Instanz "default"-->
        REX_THEME_ASSETS[type=css]
        REX_THEME_ASSETS[type=js header=1]
        <!--Instanz "inline"-->
        REX_THEME_ASSETS[id=inline type=cssinline]
        REX_THEME_ASSETS[id=inline type=jsinline header=1]
    </head>
    <body>
        ...
        <!--Instanz "libraries"-->
        REX_THEME_ASSETS[id=libraries type=js]
        <!--Instanz "default"-->
        REX_THEME_ASSETS[type=js]
    </body>
</html>

HTML

Leere REX_VARs werden übersprungen und erzeugen keine Ausgabe.

<!DOCTYPE html>
<html>
    <head>
        ...
        <!--Instanz "libraries"-->
        <script src="/theme/public/assets/vendor/jquery/jquery.min.js"></script>
        <!--Instanz "default"-->
        <link media="all" href="/theme/public/assets/styles/main.css" rel="stylesheet" type="text/css" />
        <!--Instanz "inline"-->
        <script>/*<![CDATA[*/
            alert("Dies ist ein Beispiel!");
        /*]]>*/</script>
    </head>
    <body>
        ...
        <!--Instanz "libraries"-->
        <script src="/theme/public/assets/vendor/demo/scripts/demo.js"></script>
        <!--Instanz "default"-->
        <script src="/theme/public/assets/scripts/main.js"></script>
    </body>
</html>

Beispiel 3: Varianten

Einträge können ergänzt, überschrieben oder gelöscht werden.

functions.php

theme_assets::getInstance()
    ->setJs('jquery', theme_url::assets('vendor/jquery/jquery.min.js'), true)
    ->setJs('scripts-main', theme_url::assets('scripts/main.js'))
    ->setJs('scripts-sub', theme_url::assets('scripts/sub.js'))
    ->setCss('styles', theme_url::assets('styles/main.css'));

Modul

• der Eintrag styles-module wird ergänzt
• der Eintrag scripts-sub wird überschrieben
• der Eintrag jquery wird gelöscht

theme_assets::getInstance()
    ->setCss('styles-module', theme_url::assets('styles/module.css'))
    ->setJs('scripts-sub', theme_url::assets('scripts/module.js'))
    ->unset('jquery', true);

Template

Die Ausgabe richtet sich nach der Position der REX_VARs.

<!DOCTYPE html>
<html>
    <head>
        ...
        REX_THEME_ASSETS[type=css]
        REX_THEME_ASSETS[type=js header=1]
        REX_THEME_ASSETS[type=jsinline header=1]
    </head>
    <body>
        ...
        REX_THEME_ASSETS[type=js]
    </body>
</html>

HTML

<!DOCTYPE html>
<html>
    <head>
        ...
        <link media="all" href="/theme/public/assets/styles/main.css" rel="stylesheet" type="text/css" />
        <link media="all" href="/theme/public/assets/styles/module.css" rel="stylesheet" type="text/css" />
    </head>
    <body>
        ...
        <script src="/theme/public/assets/scripts/main.js"></script>
        <script src="/theme/public/assets/scripts/module.js"></script>
    </body>
</html>