SetaSite Manuals

Blöcke

In SetaSite werden fast alle Seiteninhalte auf sogenannten Blöcke aufgeteilt. Ein Block ist lediglich eine PHP-Klasse, welche ein bestimmtes Interface implementiert und dadurch bestimmt Funktionen zur Verfügung stellt.

Interfaces

BlockInterface

BlockInterface ist lediglich das Interface, welches von sämtlichen Blöcken implementiert werden muss.

ControllerBlockInterface

Falls ein Block in der Lage sein soll auf Controller-Seiten auf zusätzliche Parameter zu reagieren, muss dieser Block das ControllerBlockInterface implementieren.

Der Block bekommt die "params" über die Methode "setParams()" von außen gesetzt. Alles was nach dem Pfad zur Controllerseite kommt wird am Slash "/" aufgetrennt und als string[] übergeben. Beispiel: Auf der Seite "/manuals/api/" wird beim Aufrufen von "/manuals/api/somenamespace/someclass/somemethod/something-else/" folgendes Array an setParams() übergeben "['somenamespace', 'someclass', 'somemethod', 'something-else']".

MultiBlockInterface

Falls ein Block mehrere Blöck unter sich haben kann, muss der Block das MultiBlockInterface implementieren.

HasCacheInterface

Falls ein Block gecacht werden kann muss der Block dieses implementieren. 

AnchorInterface

Falls ein Block Anker hinzufügt kann der Block das Anchor-Interface implementieren. Wenn das Interface implementiert wird, werden über die GUI die verfügbaren Anker angezeigt.

BlockActionInterface

Es ist möglich, dass ein Block per Ajax eine Action im Block aufruft. Dies ist möglich über sogenannte BlockActions. Eine Standardimplementierung kann im BlockActionTrait gefunden werden. 

Um die Block-Action anschließend per JS aufrufen zu können muss auf die URL der Seite ein Request gemacht werden mit den Parametern "block_uid" und "action", als Json, POST oder GET (Priorisierung in dieser Reihenfolge). Der Response wird immer ein JSON-Response sein (ausser ForceResponseException wird verwendet).

Ein View Template Verwendungsbeispiel:

<div id="block-<?=$this->_uid?>">
    <button class="somebutton">Some button</button>

<script>
    var myBlock = $('#<?=$this->_uid?>');
    $('.somebutton', myBlock).click(function() {
        $.ajax({
            type: 'POST',
            cache: false,
            dataType: 'json',
            data: {
                block_uid: '<?=$this->_uid?>',
                action: 'sendSomething'
            }
        }).done(function (result) {
            if (result === false || !result.result || !!result.root.error) {
                console.error('Error: ', result.error || result.root.error || result);
            } else {
                console.info('success!');
            }
        }).fail(function (error) {
            console.error(error.responseText);
        });
    });
</script>

</div>

Abstrakte Blöcke

Die viele Logiken immer wieder gleich sind besitzt SetaSite einige Standardimplementierung der meisten Interfaces und stellt diese Abstrakte Klassen zur Verfügung.

AbstractBlock

AbstractBlock bietet eine Standardimplementierung vom BlockInterface an. Die abstrakte Klasse implementiert bereits die Standardfunktionen. AbstractBlock implementiert bereits BlockInterface und HasCacheInterface.

AbstractBlock sollte eher selten direkt verwendet werden, da noch keinerlei Logik zum rendern vom Inhalt implementiert ist. Hierfür können folgende Klassen verwendet werden:

• AbstractTwigBlock & AbstractViewBlock - Implementiert Render-Logik
• AbstractTwigControllerBlock & AbstractViewControllerBlock - Implementiert zusätzlich noch das ControllerBlockInterface

Diese abstrakten Klassen gleichen sich alle in der Struktur. Beim rendern wird IMMER zu Beginn die "init" Method aufgerufen (falls vorhanden - Parameter werden per DI injektet). Anschließend wird überprüft ob der Block becacht werden kann (siehe AbstractBlock::getBlockCache() - im Backend wird nie gecacht). Falls ein gültiger Cache vorhanden ist wird dieser sofort zurückgeben und der nächste Block gerendert. Falls kein gültiger Cache vorhanden ist wird die View gerendert. Falls die Method "preRender" vorhanden ist, wird diese aufgerufen (Param werden per DI injektet). Anschließend werden alle Property Objekte vom Block an die View oder Twig übergeben und anschließend das View-Skript gerendert. Danach wird falls die Method "postRender" vorhanden ist, diese aufgerufen (Param werden per DI injektet).

Konfiguration

Im AbstractBlock ist zusätzlich bereits implementiert wie die Konfiguration geladen werden soll. Hierfür wird im Ordner vom Block in folgender Reihenfolge geguckt ob eine Konfigurationsdatei gefunden werden kann: "config.ini", "config.json", "config.php", "config.xml". Falls nichts hiervon gefunden werden kann gibt es einen Fehler!

Folgende Konfigurationsmöglichkeiten gibt es momentan:

• name - multilangstring
• description - multilangstring
• private - Block wird nicht mehr in der Liste der verfügbaren Blöcke angezeigt. Anzeigen in der GUI nur noch möglich falls der Block innerhalb eines MultiBlocks explizit erlaubt wird
• icon - Falls nicht vorhanden wird im Blockordner nach einer "icon.png"-Datei gesucht
• cache.enabled = 1 - Aktiviert den Blockcache
• misc.rerender.onPagePropertiesChange = true - Triggert innerhalb der GUI ein neurendern vom Block falls die Seiteneigenschaften verändert werden
• properties - Property Container Config (mehr dazu hier)

AbstractMultiBlock

Der AbstractMultiBlock erweitert den AbstractBlock und implementiert zusätzlich bereits die Logik für MultiBlöcke. Er implementiert zusätzlich bereits alle oben genannten Interfaces, jedoch lediglich als Art Weiterleitung - z.B. die Methoden für das ControllerBlockInterface suchen nur in den untergeordneten Blöcken nach einen Block der das ControllerBlockInterface implementiert. 

Standardblöcke

BlockContainer

Einem BlockContainer konfiguriert man eine Seite und kann anschließend einen oder mehrere Blöcke von der Seite kopieren.

Eigene Blöcke

Es gibt zwei Stellen an denen man eigene Blöcke unterbringen kann. 

• Direkt im blocks-Ordner von SetaSite - der Namespace ist hierbei \com\setasign\SetaSite\Block\CustomBlocks
• Innerhalb eines Modules - der Namespace und Ordner wird hierbei vom Modul vorgegeben

In dem entsprechendem Ordner muss ein Ordner angelegt werden mit dem Namen vom Block, innerhalb des Blocks muss es eine Klasse mit dem Namen "\full-namespace\BlockName\BlockName" geben (beachte dass der Blockname der Klassenname UND innerhalb des Namespaces sein muss). Neben der Blockklasse muss es noch eine Konfigurationsdatei geben - bevorzugt "config.ini".