Diese Anleitung setzt voraus, dass Fiona 7 im Legacy-Modus installiert und initialisiert wurde. Im Folgenden werden die wesentlichen Schritte zur Umstellung einer bestehenden Anwendung auf Fiona-7-Technik beschrieben.
Die als Attributwerte im CMS abgelegten Inhalte können sehr leicht an Ort und Stelle („in place“) bearbeitbar gemacht werden. Hierfür steht der Helper „fiona7_tag“ zur Verfügung. Das API folgt sehr stark dem API von „scrivito_tag“, lässt jedoch RailsConnector-Objekte als Argument zu.
Man kann also RailsConnector-Code wie beispielsweise
<h1><%= display_field @obj, :title %></h1>
leicht durch Fiona-7-Code ersetzen:
<%= fiona7_tag(@obj, :title, :h1) %>
Navigationen und Listen von Objekten können mit „fiona7_tag_list“ erstellt werden. Diese Methode blendet einen Marker ein, mit dem eine neue Seite angelegt werden kann. Zusätzlich kann die Liste sortiert werden.
Die Liste der verfügbaren Seitenvorlagen ist anfangs leer. Die verfügbaren Vorlagen können mit Hilfe der Methode „valid_page_classes_beneath“ der globalen „Obj“-Klasse in der Scrivito-Engine definiert werden.
Legen Sie also eine Datei mit dem Pfad „app/models/scrivito/obj.rb“ an und geben Sie ihr den folgenden Inhalt:
module Scrivito class Obj < BasicObj def self.valid_page_classes_beneath(parent_path) ['Publication'] end end end
Dadurch wird beim Anlegen einer neuen Seite die Vorlage „Publication“ angeboten. Sie können abhängig vom Pfad des übergeordneten Objekts („parent_path“) unterschiedliche Vorlagen zur Verfügung stellen.
Achtung! Zu jeder angebotenen Seitenvorlage muss es einen Thumbnail-View geben, damit im Auswahldialog je Vorlage ein Piktogramm angezeigt werden kann. Thumbnails werden von einem Rails-View mit dem Pfad „app/views/Vorlagenname/thumbnail.html.erb“ angezeigt. Für die Vorlage „Publication“ benötigen Sie also eine Datei mit dem Pfad „app/views/publication/thumbnail.html.erb“:
<%= scrivito_thumbnail 'Publication', :content do %> Allgemeine Seite <% end %>
Manche Attribute (z.B. „show_in_navigation“) können nicht sinnvoll in-place bearbeitet werden. Für sie bietet sich die Detailansicht an, auf der Sie die benötigten Bearbeitungselemente unterbringen können. Die Detailansicht kann über den entsprechenden Befehl im Menü der jeweiligen Seite geöffnet werden.
Der Menübefehl ist verfügbar, wenn es einen „details“-View für die betreffende Vorlage gibt. Beispielsweise kann in der Detailansicht für die „Publication“-Vorlage unter „app/views/publication/details.html.erb“ (nach dem Schema „app/views/Vorlagenname/details.html.erb“) mit folgendem Code eine Eingabemöglichkeit für den Seitentitel geschaffen werden:
<div> <h3>Seitentitel</h3> <%= scrivito_tag :div, @obj, :title %> </div>
Achtung! In den Details-Views darf weder „fiona7_tag“ noch „fiona7_tag_list“ verwendet werden. Ferner ist dort die Instanzvariable „@obj“ eine Instanz der Klasse „Scrivito::BasicObj“ und nicht von „RailsConnector::BasicObj“. Folglich sind dort die Methoden, die in „Obj“ oder „Publication“ definiert wurden, nicht verfügbar. Diese Einschränkungen ergeben sich aus der Kompatibilität mit Scrivito. Wie sie sich handhaben lassen, ist im Abschnitt Das Ruby-API beschrieben.
In einer Fiona-7-Anwendung können Widgets auf genau dieselbe Art und Weise erstellt werden wie in einer Scrivito-Anwendung. Im Folgenden wird die Vorgehensweise anhand eines „TextImageWidget“ beschrieben, das ein Bild und dessen Überschrift zusammenfasst. Der Konvention bei Fiona 7 und Scrivito folgend, sollten Widgets stets „Widget“ und Seiten „Page“ als Namenssuffix haben, damit beispielsweise der Verwendungszweck der entsprechenden Objektklassen sofort erkennbar ist. Es kann jedoch Gründe geben, von dieser Konvention abzuweichen, etwa bei einer Migration von Boxen zu Widgets.
Vorlagen und Attribute im CMS können mit Hilfe von Migrationen angelegt werden. In einer Fiona-7-Applikation ist es üblich, die Vorlagen stets programmgesteuert anzulegen, anstatt dafür die administrative Oberfläche zu verwenden.
Erstellen Sie also als ersten Schritt eine Migration für die Vorlage, indem Sie auf der Rails-Konsole den folgenden Befehl ausführen:
rails generate scrivito:migration CreateTextImageWidget
Dies legt unter „scrivito/migrate/zeitstempel_create_text_image_widget_migration.rb“ eine leere Migration an. Geben Sie der Datei den folgenden Inhalt:
class CreateTextImageWidgetMigration < Scrivito::Migration def up Scrivito::ObjClass.create(name: 'TextImageWidget', attributes: [ {name: 'header', type: :html}, {name: 'image', type: :reference} ]) Scrivito::ObjClass.find('Image').attributes.add(name: 'blob', type: :binary) end end
Mit dem ersten Block wird die Widget-Vorlage dem System bekannt gemacht. Sie hat zwei Attribute, „header“ für die Überschrift und „image“ für die Verlinkung des Bildes.
Weshalb werden Bilder in Widgets verlinkt?
Hätte das Attribut „image“ den Typ „:binary“, könnten die Bilddaten direkt im Widget gespeichert werden. Allerdings wäre ein auf diese Weise in ein Widget aufgenommenes Bild nicht wiederverwendbar, weil das Bild nicht als eigenständiges Objekt existiert. Aus diesem Grund hat sich die Konvention etabliert, Bilder als Objekte mit der Vorlage „Image“ anzulegen und sie in Widgets und auch Seiten mittels Referenz einzubinden.
Der zweite Block erweitert die bestehende Vorlage „Image“ um ein „blob“-Attribut, das für Binärdaten vorgesehen ist.
Achtung! Fiona-7-„blob“-Attribute sind nicht mit den klassischen „blob“-Attributen kompatibel. Letztere sind für Fiona 7 unsichtbar, wodurch bestehende Bilder nicht ohne Weiteres in Fiona 7 verwendet werden können.
Nachdem Sie die Migration angelegt haben, können Sie sie mit dem folgenden Befehl ausführen:
bundle exec rake scrivito:migrate
Damit ein Widget auf Webseiten genutzt werden kann, müssen zwei Views angelegt werden, „app/views/WidgetName/show.html.erb“ für die Anzeige seines Inhalts und „app/views/WidgetName/thumbnail.html.erb“ für die Anzeige eines Icons oder Bildes im Widget-Auswahldialog.
Für das TextImageWidget werden die folgenden Dateien verwendet:
app/views/text_image_widget/show.html.erb:
<%= scrivito_tag :h3, widget, :header %> <%= scrivito_image_tag widget, :image %>
app/views/text_image_widget/thumbnail.html.erb:
<%= scrivito_thumbnail 'Text Image Widget', :image do %> Ein Widget mit einem Bild und einer Überschrift. <% end %>
Achtung! Wie beim Details-View einer Seite darf hier weder „fiona7_tag“ noch „fiona7_tag_list“ verwendet werden.
Der letzte Schritt besteht darin, Widgets auf einer Seite überhaupt verfügbar zu machen. Hierzu benötigt das Objekt, das die Seite repräsentiert, mindestens ein Attribut vom Typ „widget“. Wenn Sie TextImageWidgets in Seiten vom Typ „Publication“ aufnehmen möchten, erstellen Sie eine Migration, die ein solches Attribut vom Typ „widget“ zu der „Publication“-Objektklasse hinzufügt:
rails generate scrivito:migration AddMainContentAttributeToPublication
Geben Sie der generierten Migrationsdatei den folgenden Inhalt, um das Attribut „main_content“ vom Typ „widget“ zur Vorlage „Publication“ hinzuzufügen:
class AddMainContentAttributeToPublicationMigration < ::Scrivito::Migration def up Scrivito::ObjClass.find('Publication').attributes.add(name: 'main_content', type: :widget) end end
Führen Sie nun die Migration aus:
bundle exec rake scrivito:migrate
Um „main_content“ auf Seiten vom Typ „Publication“ zu rendern und bearbeitbar zu machen, fügen Sie in den View für die „Publication“-Vorlage die folgende Zeile ein:
<%= fiona7_tag :div, @obj, :main_content %>
Wenn man nun eine Seite mit der Vorlage „Publication“ aufruft, wird für „main_content“ ein Marker eingeblendet, mit dem man Widgets manipulieren kann. Noch ist es jedoch nicht möglich, Widgets zur Seite hinzuzufügen, weil die Liste der angebotenen Widgets im Auswahldialog leer ist – wie anfänglich beim Auswahldialog für Seitenvorlagen.
Die zur Auswahl anzubietenden Widgets wird über die Instanzmethode „valid_widget_classes_for“ in der Klasse „Scrivito::Obj“ gesteuert. Erweiterte Definition von Scrivito::Obj soll nun wie folgt aussehen:
module Scrivito class Obj < BasicObj def self.valid_page_classes_beneath(parent_path) ['Publication'] end def valid_widget_classes_for(attribute) ['TextImageWidget'] end end end
Das TextImageWidget kann jetzt auf Seiten mit der Vorlage „Publication“ im Attribut „main_content“ verwendet werden. Die Überschrift eines solchen Widgets lässt sich nun in-place bearbeiten, und ein Bild kann per Drag-and-Drop hochgeladen werden.
Analog zu Seiten können Widgets auch Detailansichten haben, um Widget-Attribute bearbeiten zu können, die in-place nicht zugänglich gemacht werden können oder sollen, etwa ein Attribut für die Hintergrundfarbe. Die Detailansicht eines Widgets wird per Konvention von dem View unter „app/views/WidgetName/details.html.erb“ gerendert.
Im Legacy-Modus (in Gegensatz zum Standalone-Modus) muss zu einem Widget nicht zwingend eine eigene Ruby-Klasse gehören. Es ist jedoch manchmal von Vorteil, eine solche zu haben, um beispielsweise ein Widget mit eigenen Methoden ausstatten zu können.
Beim Legacy-Modus gibt es zwei Möglichkeiten, eine Ruby-Klasse für ein Widget anzulegen:
Für das TextImageWidget heißt das: Sie können entweder die Datei „app/models/text_image_widget.rb“ mit dem Inhalt
class TextImageWidget < Scrivito::BasicWidget end
oder die Datei „app/models/scrivito/text_image_widget.rb“ mit dem Inhalt
module Scrivito class TextImageWidget < BasicWidget end end
anlegen. Die zweite Variante (Scrivito-Namespace) ist insbesondere interessant, wenn man bestehende Klassen und Objekte (z.B. Boxen in einem Boxen-Modell) in Widgets umwandeln möchte und die Anwendung weiterhin abwärtskompatibel bleiben soll. Damit ließen sich also Boxen und bereits in Widgets umgewandelte Boxen parallel nutzen.
Übrigens können auf die gleiche Art und Weise auch Klassen für andere Vorlagen angelegt werden. Mehr dazu im Abschnitt Das Ruby-API.