Scrivito SDK Basics

The Scrivito SDK lets you access and render your CMS content from within your Rails application. The Ruby API documentation of the SDK is available at www.rubydoc.info.

About object classes and models

Many things in the Rails world are designed to work by convention. If you follow the conventions, the tools just work without further configuration. The Scrivito SDK adopts this style in several places, too.

The content stored in the CMS is accessible in your Rails application through CMS objects, which are instances of object (model) classes, e.g. the Page class. An object class defines the properties of its instances, first and foremost their attributes.

The base class of all CMS objects is Obj. It is the class of which all object classes are subclasses. This principle is comparable to STI (single table inheritance) in the world of relational databases.

Model classes are usually located in app/models/, e.g. app/models/page.rb:

class Page < Obj
end

Widgets are instances of object model classes, too. Their base class, however, is Widget.

Loading an object

There are several ways to load a CMS object from the database, including the following ones:

# Find an object by its ID
Obj.find("55e783066434a5ba")

# Find an object by its path
Obj.find_by_path("/website/en/imprint")

# Find an object by its permalink
Obj.find_by_permalink("imprint")

Although these methods are defined on Obj, they are designed to return an instance of the specific subclass of Obj, e.g. Page.

Routing

As a default, the Scrivito SDK routing automatically matches all requests for CMS objects, based on a particular URL format. The URL contains some kind of identifier of the CMS object that was requested. Mostly, this identifier is the internal ID of the object in the CMS database. Sometimes it is a so-called permalink. Learn how to refine Scrivito's routing.

The routing first loads the requested CMS object. Then, based on the model class name, which is determined from the object, the SDK routing tries to find a matching controller to handle the request. For the Page model class, as an example, it looks up a controller named PageController. If this controller is missing, it falls back to CmsController, the superclass of all controllers that can handle CMS object requests. The Scrivito SDK automatically places the loaded object into the @obj instance variable of the controller so that the actions and the views can access it as well.

The controller classes are located in app/controllers/, e.g. app/controllers/page_controller.rb:

class PageController < CmsController
end

After the controller has been determined, the routing calls its index action. CmsController already defines this action. It can be overridden to provide more logic. The default implementation of the action is empty, which means that Rails then looks for a view file in app/views/, the standard Rails view search path.

Take a look at app/views/page/index.html.erb, as an example (the attributes may have different names):

<%= scrivito_tag(:h2, @obj, :title) %>
<%= scrivito_tag(:div, @obj, :body) %>

The scrivito_tag helper is provided by the SDK. @obj is the requested CMS object, that has already been loaded into this variable by the SDK routing. The helper calls display the values of the title and body attributes of the object and also let editors change the attribute values in place on the web page.

Attributes

Objects can have attributes. Attributes, sometimes also referred to as fields, are properties of an object that can be queried and set.

Every attribute has a type. Please refer to the API documentation for the available attribute types and their properties.

All objects have a set of built-in attributes such as _permalink or _path. They are accompanied by methods for retrieving their values easier, e.g. permalink or path. Please refer to the API documentation of BasicObj for a list of built-in attributes and methods.

In addition to the built-in attributes, objects can have as many custom attributes associated with them as needed. For creating object classes, two generators, one for CMS object classes and one for widget classes, are available.

Navigations

Navigations and other content elements require the application to load and display other objects next to the requested one that has already been made available as @obj in the controller and the view.

For the purpose of generating navigations but also for categorizing content in general, CMS objects can be organized or presented hierarchically. You can connect objects with each other using

For an in-depth evaluation of these techniques with respect to their application areas, see Building Navigations.