Installation

This guide refers to a Fiona-on-Rails application meant to be operated with Fiona 7 in legacy mode.

Prerequisites

The starting point of the installation is a Rails application using Rails 4.2. This may be a RailsConnector application or a pure Rails application. For the Fiona 7 gem to work as intended, the following components are mandatory:

  • Rails 4.2
  • jQuery and jQuery-ujs
  • CMS Fiona, including activated XML access, railsified using version 6.9.0 or later
  • MySQL database 5.5.x, starting at version 5.5.29 or 5.6.x
  • Search Cartridge for CMS Fiona
  • ImageMagick
Optionally, the FionaConnector may be used. It's always installed through the Fiona 7 gem dependencies.

Step 1: Install the gem

Add the Fiona 7 gem to the “Gemfile” in the main directory of the application:

gem 'infopark_fiona7'

In case you are using “turbolinks“, please remove it because Scrivito does not support it. This affects:

  • The corresponding entry in the Gemfile
  • JavaScript assets in app/assets/javascripts/application.js
  • The application layout in app/views/layouts/application.html.erb
    (remove the “data-turbolinks-track“ HTML attributes)

The Fiona 7 gem (as well as the RailsConnector, now FionaConnector) is published at RubyGems.org, so it can be installed using the following command:

bundle install

The components required for compatibility with Scrivito are automatically taken account of.

The following steps serve to configure the application for interoperating with the Fiona 7 gem.

Step 2: Include CSS and JavaScript

To enable the full functionality of the gem, the application needs to include CSS and JavaScript components.

CSS components

This guide assumes that neither SCSS or LESS nor any other similar solution is used in the “application.css" file. Add the following line to the “app/assets/stylesheets/application.css" file, preferredly above or below “*= require_self”:

*= require fiona7

JavaScript components

This guide also assumes that no extensions such as CoffeeScript are used in the “application.js” file. Add the following line to the “app/assets/javascripts/application.js” file:

//= require fiona7

This line must be placed directly below the following lines:

//= require jquery
//= require jquery_ujs

Step 3: Implement base class

To be able to work with Fiona 7 in your application, the Obj class needs to be implemented. For this, please create this class, which inherits from RailsConnector::BasicObj, in “app/models/obj.rb”:

class Obj < RailsConnector::BasicObj
end

Step 4: Implement base controller

To enable access to objects based on the Obj class, please include Scrivito::ControllerActions in the CmsController, in “app/controllers/cms_controller.rb”:

class CmsController < ApplicationController
  include Scrivito::ControllerActions
end

Step 5: Configure connections

For an application using the Fiona 7 gem, three connections need to be configured:

  • A direct connection to the MySQL database used by the CMS
  • A connection to the XML interface of the CMS
  • A connection to the XML interface of the CMS-SES

The MySQL configuration is fully identical to the one the RailsConnector (or FionaConnector) uses, meaning that the “cms:” entry in the “config/database.yml” file needs to be the same.

Specify the access parameters for the XML interface in the “config/initializers/fiona7.rb” file. The following example illustrates the configuration keys and the format of their values:

Fiona7.configure do |config|        # 1
  config.instance = 'playland'      # 2
  config.host = '33.33.33.10'       # 3
  config.port = 7001                # 4
  config.username = 'root'          # 5
  config.secret = 'MYSECRET'        # 6
  config.mode = :legacy             # 7
end
Fiona7::VeritySearchEngine::VeritySearchRequest.configured_host = '33.33.33.10' # 8 Fiona7::VeritySearchEngine::VeritySearchRequest.configured_port = 7011 # 9

The lines above mean or cause:

  1. The configuration call
  2. The instance name, usually ‘default’.
  3. The hostname or the IP address of the CMS server.
  4. The port number of the XML interface of the CM; see the “config/server.xml” CMS file.
  5. The login of a user having “permissionGlobalRoot”.
  6. The instance “secret"; see the “config/server.xml” file.
  7. The application mode, “:legacy" or “:standalone.” This setting is explained in the section Two Operation Modes.
  8. The hostname or the IP address of the CMS server.
  9. The port number of the XML interface of the SES; see the “config/server.xml” CMS file.

The credentials, consisting of the username and the secret, represent a CMS user with root access. For this reason, these credentials should never be published or checked in to a repository. We recommend using Rails Secrets for persisting them. Furthermore, access to the XML interface should be restricted to the known IP addresses using a firewall.

Step 6: Enable the user interface

Enable the user interface by adding

<%= fiona7_head_tags %>

to the HEAD section of the layout and

<%= fiona7_body_tags %>

to the BODY section of the layout.

Optionally enable or disable workflows or the Content Browser's tag filtering function.

Step 7: Provide log-in link

Editors need to log in to be able to edit content in the preview. As a default, the log-in form is hidden and needs to be enabled first. To do this, insert the following line into the layout where appropriate to have the log-in button show up:

<%= fiona7_login_button %>

Step 8: Launch the web application

Starting a Fiona-7-based application for the first time causes the CMS instance belonging to it to be automatically initialized. In this process, the connections, structures, and settings of the CMS are checked for compatibility with Fiona 7 and adjusted if required.

After launching the app and opening the site in the browser, you can log in and create or edit content in editing mode.