Page and Widget Views Explained

Page and Widget Views Explained

Pages and widgets have a lot in common. Both are meant to contain content. And, both pages and widgets are based on object classes that define the types of content the actual pages or widgets, respectively, are meant to contain. Thus, we are actually talking about page types and widget types, not the pages and widgets based on these types.

Page and widget types are different, however, regarding the structures produced when you create instances of them. While a page is represented by an individual CMS object, a widget is stored inside an attribute of such a CMS object. Thus, a page type requires a controller while a widget type doesn't.

Looking at the /app/views directory of a Scrivito Rails app reveals directories named after page and widget types. After creating an object class, put the views for it into a new folder here.

Note that there are generators for creating page and widget types including their views:

Be sure to stick to the convention of using Page and Widget as the last part of your object class names (e.g. ContactPage, or HeadlineWidget), so you'll be able to identify them quickly.

Note that the Widget part is appended automatically if it's omitted, but the Page part isn't.

Views for rendering pages and widgets

The standard views for rendering pages and widgets of a particular type are index.html.* and show.html.*, respectively. This is how a minimal standard view for a page might look:

And this is the corresponding view for a widget:

There are several CMS tag helpers available for rendering content and making it editable in place.

Details

Helpers part of the Scrivito SDK:

  • scrivito_details_for(title = nil, &block)
  • scrivito_tag(tag_name, obj_or_widget, field_name, options = {}, &block)
  • scrivito_tag_list(tag_name, obj, method_name, options = {}) {|list, child| … }
  • scrivito_image_tag(obj, linklist, tag_options = {}, editing_options = {})

When editing content in place, however, two more views come into play, details.html.* and thumbnail.html.*.

Details views

The details view is rendered after Page properties or Widget properties has been selected from the page or widget menu, respectively. The properties window should enable an editor to change at least those page or widget properties that cannot be altered in place.

To render attribute values in a details view and to make them editable, you can use the same CMS helpers as you would in a standard view. The markup below, for example, renders the value of the “title” attribute in the details view of a page:

<%= scrivito_tag :div, @obj, :title %>

Analogously for the “headline” attribute of a widget, but this time, the scrivito_details_for helper is used to render the attribute as part of a group titled “Headline”:

You can control the size of the details dialog by rendering the details inside of a call to the scrivito_large_dialog, scrivito_medium_dialog, or scrivito_small_dialog helper:

Thumbnail views

The thumbnail.html.* view, finally, is rendered whenever a thumbnail representing a page or widget type is to be displayed. This happens, for example, when the page or widget browser is opened for choosing the type of a new page or widget, respectively.

To have a thumbnail displayed, use the “scrivito_thumbnail” helper, like so:

There is a nice set of widget thumbnails you can download from the widget gallery.