Concrete5: Entwicklung mit Concrete5: Blöcke verstehen: Eigene Blöcke erstellen

Durch Blöcke werden in Concrete5 Inhalte und Funktionalität in Ihre Seite eingebunden. Lernen Sie hier mehr darüber, wie der Endbenutzer Blöcke in Seiten hinzufügt.

Von Grund auf stellt Concrete5 eine Reihe von Blöcken zur Verfügung. Obwohl diese ausreichen um die meisten Webseiten aufzusetzen und zum Laufen zu bringen, wird meist das erste was viele Concrete5 Entwickler tun werden, mit der Blockarchitektur herumzuspielen. Das könnte lediglich eine Änderung der Block Präsentationsschicht sein; oder der Bedarf, etwas komplett neues, wie ein Event, ein Kalender oder einen Produktblock zu erstellen. Glücklicherweise ist das Arbeiten mit Blöcken in Concrete5 ein sehr einfacher Prozess.

Basic Block Template

Unter diesem Link[1] finden Sie einen einfachen Block zum Herunterladen und installieren. Er wird in den Entwicklertutorials verwendet. Hinweis: Es wird Version Concrete5.0.0b1 oder höher benötigt, um diesen verwenden zu können.

Einführung

Ein Block ist eine Sammlung von Dateien innerhalb eines bestimmtem Verzeichnis, welches sich seinerseits im "blocks/" Verzeichnis Ihres Webseitenroots befindet. (Ein weiteres Blockverzeichnis befindet sich innerhalb des "concrete/" Verzeichnis, welches Blöcke gepackt mit dem CMS enthält. Um das System für eventuelle Upgrades zu erhalten, ist es wahrscheinlich das Beste, diese unangetastet zu lassen - trotzdem kann ihre Präsentationsschicht durch Inkludieren von Templates innerhalb des Webseitenroot Verzeichnis überschrieben werden, aber dazu später mehr.)

Inhalte eines Blockverzeichnis

add.php

Notwendig. Diese Datei ist das Template, welches beim Hinzufügen dieses Blocks im CMS angezeigt wird.

edit.php

Optional, kann jedoch äußerst notwendig sein. Diese Datei wird angezeigt, wenn sich der Block im Editmodus befindet.

Beide, add.php and edit.php, sind nur einfache Formulare die in Concrete eingebettet werden. Normalerweise haben diese Formularelemente die identischen Namen wie ihre zugehörigen Datenbanktabellenspalten.

controller.php

Notwendig. Diese Datei enthält einige grundlegende Parameter über den jeweiligen Block (seinen Namen, eine Beschreibung, seine Interface Größe, etc...), ebenso jegliche programmiertechnisch erforderlichen Begriffe. Die Blockklasse ist zudem für das Speichern des Blocks zuständig, allerdings benötigen viele einfache Blöcke kein Spezifizieren wie sie gespeichert werden, solange die 'post' Variablen zu den Block Datenbanktabellenspalten verbunden werden.

db.xml

Für alle Blöcke die Daten in der Datenbank speichern (was für 99% zutrifft) notwendig. Diese Datei enthält Angaben, die zum Erstellen Ihrer Block Datenbanktabellen in der Datenbank, spezifiziert durch das ADOXMLS Format, benötigt werden.

auto.js

Optional. Falls diese Datei existiert wird sie automatisch im 'add' oder 'edit' Modus inkludiert.

icon.png

Optional. Diese Grafik wird wann immer der Block in Concrete's Interface aufgelistet wird, angezeigt.

tools/

Optional. Begriffe innerhalb dieses Verzeichnis können vom Block für alle möglichen Anwendungsfälle verwendet werden. Der auto_nav Block macht von diesem Funktionstyp Gebrauch.

templates/

Optional. In diesem Verzeichnis stehen alternative Ansichten für Instanzen des jeweiligen Blocks, welche als maßgeschneiderte Templates im CMS ausgewählt werden können. Beispielsweise formatiert ein standard auto_nav Block seine Einträge als ungeordnete Liste, aber das "Header Menu" Template kann für den auto_nav Block verwendet werden, welches das Menu dann mit 'DIV'-Tags restrukturiert.

Einen Block installieren

Bevor man einen Block erstellt, hilft es einen möglichst einfachen existierenden Block zu verwenden. Dafür wurde von den Entwicklern ein sehr einfacher Musterblock zum Herunterladen erstellt, siehe oben.

Um diesen Block zu installieren geht man wie folgt vor:

Entpacken Sie den Block.
Legen Sie diesen in Ihrem Concrete5 "blocks/" Verzeichnis ab, welches voraussichtlich leer ist.
Loggen Sie sich ein und navigieren Sie innerhalb des Dashboards zu "Funktionen hinzufügen".
Der neue Block sollte nun als zur Installation verfügbar angezeigt werden (unterhalb der aktuell installierten Blöcke.)
Klicken Sie auf Installieren.

Das sollte alles sein, was es da gibt. Der Block wird automatisch seine Datenbanktabellen erstellen und sein Datensatz zu Concrete5 hinzugefügt, wobei man an diesem Punkt in der Lage sein wird, diesen in der Webseite einzubinden.

Aber wie weiss unser Block, dass er als "Basic Test" benannt werden soll? Und wie erstellt er Datenbanktabellen während der Installation? Die Antwort findet sich in "controller.php"

Installation Information 1: Eigenschaften in Controller.php

Controller.php enthält Daten über unseren Block, genauso wie Methoden, die automatisch ablaufen, wenn verschieden Dinge mit unsere Block geschehen.

Notwendige Eigenschaften

btDescription: Dies ist die Beschreibung, was der Block tut. Sie wird im Dashboard und im add Block Interface angezeigt.

btName: Der Name des Blocks.

Optional Properties

btTable: Des Blocks primäre Datenbanktabelle. Falls angegeben, und falls der Block nur diese eine Datenbanktabelle verwendet, dann wird der Block in der Lage sein, seine Informationen in dieser Tabelle zu speichern, sofern des Blocks Formularfelder direkt zu den Spalten in der Datenbank verknüpft sind.

btInterfaceWidth: Die Breite des modalen Popup Dialogs, der diesen Block beim Hinzufügen oder Editieren anzeigt.

btInterfaceHeight: Die Höhe des modalen Popup Dialogs, der diesen Block beim Hinzufügen oder Editieren anzeigt.

Somit sieht man, wie unser Block wusste, dass er als "Basic Test" benannt werden sollte: es ist innerhalb unserer Blockklassen Datei enthalten. Wie man sehen kann, ist das der Wertebereich unseres Test Block controller. Weitere Informationen könnten in diesem controller stecken, allerdings gibt es weitere Beispiele für validierte controller Methoden folgend.

Installation Information 2: db.xml

Jetzt da wir wissen, wie unser Block zu seinem Namen und seiner Beschreibung während der Installation kommt, sehen wir mal wie er seine Datenbanktabellen erstellt. In unserem basis Test Block, wurde die Datenbanktabelle als "btBasicTest" definiert. Öffnen Sie nun die Datei db.xml im Block Verzeichnis. Darin wird man unsere "btBasicTest" Datenbanktabelle als XML definiert wiederfinden:

<?xml version="1.0"?>
<schema version="0.3">
    <table name="btBasicTest">
        <field name="bID" type="I">
            <key ></key>
            <unsigned ></unsigned>
        </field>
            <field name="content" type="X2">
        </field>
    </table>
</schema>

Dies sollte recht einfach zu verstehen sein: zuerst definieren wir die Tabelle genannt als "btBasicTest". Als nächstes definieren wir unser erstes Feld, welches als bID bezeichnet wird und ein Integer Typ ist. Er ist zudem als vorzeichenlos definiert, und der primäre Schlüssel der Tabelle. Anschließend wird eine Spalte mit dem Namen "content" als longtext Typ (das ist, was "X2" bedeutet) definiert.

Das Schema für diese Datei ist AXMLS. Folgen Sie diesem Link[2] um mehr darüber zu erfahren, unter anderem wie unterschiedliche Spaltentypen spezifiziert werden können.

Zu guter letzt: jede Tabelle die durch die Eigenschaft btTable des controllers spezifiziert wurde, muss bID als seinen primär Schlüssel haben. Das ist ein Integer (der nicht auf gesetzt auto_increment wird). Dieser Schlüssel ist mit einem Eintrag in Concrete5's Kernblocktabelle verknüpft, und wird zum Kombinieren Ihrer block-spezifischen Daten mit Concrete5 Daten über den Block (Metadaten, Positionierung, Versionen, etc...) verknüpft.

Werfen wir nun einen Blick darauf, wie unser Block arbeitet. Versuchen Sie ihn einer Seite hinzuzufügen. Sie sollten nun ein einfaches Formular sehen. Um zu lernen wie dieses Formular aufgebaut wird, sehen Sie in add.php

add.php

Das erste was wir in add.php bemerken, ist das hier nicht viel steht.

<p>Einführende paragraphischer Text...</p>

<?=$form->label('content', 'Name');?>
<?=$form->text('content', array(
   'style' => 'width: 320px'
));?>

Zuerst findet sich ein Einführungsabsatz. Danach steht ein Label für unser eines Formularfeld, als Ausgabe des HTML Helfers. Als nächstes gibt der HTML Helfer ein Textfeld mit dem Namen "content" aus. Um das Texteingabefeld zu entwerfen, übergeben wir ein assoziatives Array als zweite Option mit einigen Design Informationen.

Wird ein Block dieses Typs nun im CMS hinzugefügt, wird dieser ganze Block aus PHP und HTML in ein Formular gepackt, welches das Übergeben der Inhalte an Concrete kontrolliert. Um sicherzustellen, dass die Inhalte des Formulars korrekt zu den Datenbanktabellen des Blocks geroutet wird, sollte das erste Formularfeld wie die Datenbanktabellen Spalte genannt werden. (Hinweis: Das ist eine Hilfestellung, aber am Ende handelt es sich nur um ein Formular. Sie können diese wie sie möchten benennen. Sie müssen nicht auf Concrete's Formular Helferbegriffe zurückgreifen - obwohl diese eines Tages nicht mehr optional sein könnten.)

Übermitteln des "Add Block" Formulars

Wenn Ihr Block im CMS hinzugefügt wird, werden Sie einen "Add" Button neben dem Hauptinhaltsbereich Ihres Templates sehen. Beim klicken dieses Buttons, routet Concrete die Anfrage an den controller Ihres Blocks, und ruft automatisch die save() Methode auf.

Sofern Ihr Block einfach gestrickt ist, und nichts weiter benötigt außer die übermittelten Felder so wie diese sind in die Datenbank zu übertragen, ist es nicht nötig eine eigene save() Methode zu implementieren - Concrete5's Block controller wird dies für Sie erledigen. Darum werden Sie beim Austesten des Controllers für den Testblock überhaupt keine save() Methode sehen.

Bearbeiten eines Blocks mit edit.php

Edit.php ist die PHP Datei die beim platzieren eines Blocks im Editiermodus angezeigt wird. Die meiste Zeit ist diese sehr, sehr ähnlich zu add.php, mit einigen geringfügigen Erweiterungen um den existierenden Werten der Blockfelder den Übergang zu den Formularelementen zu gestatten.

Hier sind einige Inhalte unseres Basistestblocks Bearbeitungstemplate:

<?=$form->label('content', 'Name');?>
<?=$form->text('content', $content, 
    array('style' => 'width: 320px')
);?>

Dies sieht weitgehend so aus wie das Template zum Hinzufügen aus, allerdings kommt hier der $content Parameter vor. In unserem typischen Blockcontroller, werden die Werte der Datenbankspalten automatisch ausgewählt und im lokalen Sichtbarkeitsbereich platziert. Anschließend werden diese Daten an den Formularhelfer weitergereicht, damit diese im Editiermodus angezeigt werden können.

Was bedeutet das genau? Dadurch wird per default jede Spalte in Ihrer Datenbank mit der aktuellen bID, als PHP Variable in Ihrem Editier- und Ansichtstemplate verfügbar sein.

Betrachten Ihres Blocks

Das Ansichtstemplate für Ihren Block ist ganz wie Ihr Editiertemplate, aber etwas einfacher. Es gibt die aktuell gespeicherten Werte zusammen mit jeglichen spezifischen Blockpräsentationen für einen Block aus. Für einen HTML Inhaltsblock, mag dies nur die Ausgabe der exakten $content Variablen eines Block sein. Für eine Autonavigation, kann es das Parsen der gespeicherten Einstellungen und das erstellen eines Baums auf Basis dieser sein. Für ein Ereignis kann dies das Parsen der gespeicherten Einstellungen in ein Kalenderinterface sein.

Einstellen eigener Präsentationsschichten für vorhandene Blöcke

Für viele Seiten reichen die schon vorhanden Blöcke aus. Und für andere wird das Erstellen eines eigenen komplett veränderten von Nöten sein. Dennoch, falls Sie einen schon vorhandenen Block mit einem eigenen Template versehen möchten, ist dies der richtige Abschnitt für Sie.

Aktualisieren des globalen Templates für einen eingebauten Block

Sagen wir, Sie möchten, dass ihr "autonav" Block immer "DIV"-Tags anstelle von Listenelementen verwenden soll. Anstelle des Aktuallisieren in blocks/content/autonav/view.php (welches beim nächsten Upgrade überschrieben wäre), erstellen Sie blocks/autonav.php in Ihrem Webseiten Root Verzeichnis. Dieses Template wird dann automatisch von Ihrem autonav Block verwendet.

Erstellen von maßgeschneiderten Templates für Blöcke

Um ein maßgeschneidertes Template für einen Block der dann unter der Dialog Box "Choose Custom Template" verfügbar ist zu kreieren, erstellen Sie ein "templates/" Verzeichnis innerhalb eines zu Ihrem Block korrespondierenden Verzeichnisses. Hier ein Beispiel:

Sagen wir, Sie möchten ein neues Template für Ihren autonav Block erstellen. Das installierte autonav Template ist oft klasse, aber Sie brauchen ebenso ein "breadcrump" Template. In Ihrem lokalen "blocks/" Verzeichnis (welches nach der Installation von Concrete5 normal leer ist) erstellen Sie nun "autonav/templates/breadcrumb.php".

Kopieren Sie den Code von "concrete/blocks/autonav/view.php" in diese Datei und modifiezieren Sie diese wei benötigt. Um das Template zu verwenden, klicken Sie auf den Block den Sie modifizieren möchten, und selektieren Sie "Choose Custom Template" im Menu. Ihr "Breadcrumb" Template sollte im Selektiermenu erscheinen.

Zusätzliche optionale Methoden in Ihrem Block controller

Für viele Blöcke wird es keinen Bedarf geben diese Methoden in Ihrem controller zu überschreiben. Falls Ihr Block allerdings sehr komplex ist, werden Sie dies tun müssen. Die folgenden Methoden werden von Ihrem Block in bestimmten Situationen verwendet:

install()

Diese wird automatisch beim Installieren eines Blocks ausgeführt. Typischerweise parst es des Block's db.xml Datei, aber falls es von nöten ist neue Verzeichnisse zu erstellen oder einige andere Dinge in die Datenbank zu schreiben, ist dies der richtige Ansatzpunkt.

save($args)

Diese Methode wird automatisch beim Hinzufügen oder Editieren eines Blocks, mit einem assoziativem Array aus Schlüsseln und Werten aufgerufen.

duplicate($newBlockID)

Diese wird auf einen vorhandenen Block aufgerufen und vergibt eine neue Block ID, und ist dann für das Verwenden all der Daten über die aktuelle Instanz und das Sicherstellen, dass Daten zu einer neuen Instanz des Blocks verknüpft werden, verantwortlich.

delete()

Diese Methode ist für das Löschen aller Informationen über einen Block beim Entfernen verantwortlich.

WICHTIGER HINWEIS: Stellen Sie sicher das parent::__Methodenname() aufgerufen wird, wenn Sie mit Ihrem eigenen Code fertig sind.

Zurück zu 'Blöcke verstehen' |

Hoch zu 'Inhaltsverzeichnis' |

Vor zu 'Anpassen von Blockdesigns'