This guide assumes that Fiona 7 has been installed and initialized in legacy mode. In the following, the relevant steps for adapting an existing application so that it uses Fiona 7 technology are described.
The content stored as attribute values in the CMS can easily be made editable in place. For this, the
fiona7_tag helper is available. This API corresponds to
scrivito_tag, however, RailsConnector objects may be passed to it.
This makes it easy to replace RailsConnector code such as
<h1><%= display_field @obj, :title %></h1>
with Fiona 7 code:
<%= fiona7_tag(@obj, :title, :h1) %>
Navigations and object lists can be created using
fiona7_tag_list. This method displays a marker for creating a new page. Furthermore, the list can be sorted.
Initially, the list of available page types is empty. The available types can be defined using the
valid_page_classes_beneath method of the global
Obj class part of the Scrivito engine. So, create the “app/models/scrivito/obj.rb” file and add the following code to it:
class Obj < RailsConnector::BasicObj in_place do def valid_page_classes_beneath(parent_path) ['Publication'] end end end
This causes the
Publication type to be offered when creating a page. You can make the page types that should be available depend on the path of the parent object (
Each page type offered requires a thumbnail view for displaying a respective icon in the page type browser. Thumbnails are displayed by a Rails view located at “app/views/type_name/thumbnail.html.erb”. Thus, the
Publication type requires the “app/views/publication/thumbnail.html.erb” file:
<%= scrivito_thumbnail 'Publication', :content do %> General page <% end %>
For some attributes it doesn't make sense to edit them in place (e.g.
show_in_navigation). Editing controls for these attributes are best placed on the details view of the page. The details view can be opened via the corresponding item of the page menu.
This menu item is selectable if a
details view exists for the page type concerned. You might, for example, make the title of
Publication pages editable by placing the following code into the “app/views/publication/details.html.erb” file (named in accordance with the “app/views/type_name/details.html.erb” pattern):
<div> <h3>Page title</h3> <%= scrivito_tag :div, @obj, :title %> </div>
Do not use
fiona7_tag_list in details views. Also, in details views,
@obj is an instance of the
Scrivito::BasicObj class and not of
RailsConnector::BasicObj, causing the methods defined on
Publication not to be available. How these restrictions originating from compatibility with Scrivito can be dealt with is described in The Ruby API.
TextImageWidgetthat combines an image with a headline. Following a convention for Fiona 7 and Scrivito, widget names should be suffixed with
Widget, and page names with
Pageto be able to instantly identify the purpose of the corresponding object classes.
First, create the widget model in which all of the widget's attributes are defined. For this, create a file, “app/models/image_text_widget.rb”. The class needs to be derived from the
Widget class which is derived from
class ImageTextWidget < Widget attribute :headline, :html attribute :image, :reference end
If, as in the example above, a
Widget class references objects, they are always derived from
Scrivto::BasicObj and not from
RailsConnector::BasicObj. How this restriction originating from compatibility with Scrivito can be dealt with is described in The Ruby API.
The class makes the widget object class known to the system. The object class has two attributes,
headline for the headline, and
image for the image link.
Why are images linked in widgets?
If the type of the
image attribute were
:binary, the image data could be stored directly inside the widget. However, an image included in a widget in this manner would not be reusable because the image wouldn't exist as an individual object. For this reason it has become a common practice to create images as objects based on an object class named
Image and include them in widgets and pages using a reference.
For a widget to be usable on a web page, two views need to be created, “app/views/WidgetName/show.html.erb” for displaying its content, and “app/views/WidgetName/thumbnail.html.erb” for displaying an icon or an image in the widget selection dialog (also known as widget browser).
TextImageWidget the following files are used:
<%= scrivito_tag :h3, widget, :headline %> <%= scrivito_image_tag widget, :image %>
<%= scrivito_thumbnail 'Text Image Widget', :image do %> A widget with an image and text. <% end %>
fiona7_tag_listmust be used here.
The last step is to make widgets usable on pages. For this, the objects representing the pages require at least one attribute of the
widgetlist type. If you wish to include
TextImageWidgets in pages of the
Publication type, extend the class to include such an attribute as follows:
class Publication < Obj in_place do attribute :main_content, :widgetlist end end
To have the
main_content rendered and make it editable on
Publication pages, add the following line to the view of the
Publication object class:
<%= fiona7_tag :div, @obj, :main_content %>
Publication page now exhibits a marker for
main_content you can use to manipulate widgets. It still isn't possible to add widgets to the page, however, because the list of widgets in the widget selection dialog is empty, as initially was the case with page types in the page type browser.
The selection of widget types to be offered is controlled by the
valid_widget_classes_for instance method of the
Obj class. The extended definition of
Obj should read:
class Obj < RailsConnector::BasicObj in_place do def valid_page_classes_beneath(parent_path) ['Publication'] end def valid_widget_classes_for(attribute) ['TextImageWidget'] end end end
You can now use the
TextImageWidget in the
main_content attribute on pages of the
Publication type. The headline of such a widget can now be edited in place, and you can upload images using drag and drop.
As with pages, widgets may also have details views for editing widget attributes that cannot or should not be edited in place, e.g. an attribute for the background color. By convention, the details view of a widget type is rendered by a file located at “app/views/WidgetName/details.html.erb”.