Scrivito Editors Overview

The Scrivito Editors gem is a collection of useful standard JavaScript editors based on the Scrivito SDK. By means of these editors, CMS attributes of any type can be edited. They also provide helpers for the property view of pages and widgets. A browser for adding, updating, and deleting content, the content browser gem, is included as well.

The following editors are included:

Installation

  1. The Scrivito editors gem is automatically added to your application. Just follow the instructions for integrating Scrivito into your Rails application.
  2. The date editor requires you to set a time zone for your application in config/application.rb.
    config.time_zone = 'Berlin'

Usage

As a default, all editors are configured to be automatically triggered for CMS attributes rendered by means of the scrivito_tag SDK method. The editors also bind to the editor option, so that you can customize any CMS attribute and use whatever editor you like. For example,

scrivito_tag(:span, @widget, :my_date, {}, editor: 'my_fancy_date_editor')

does not trigger any of the standard CMS in-place editors provided by this gem, so you can bind to it in your own JavaScript files.

Placeholder for empty attributes

By default, a placeholder is displayed for empty CMS attributes to notify the user of how to edit the attribute. The placeholder can be customized by providing a data-scrivito-editors-placeholder HTML attribute.

For example, to change the placeholder to My custom placeholder text, you can adjust the call to scrivito_tag in your views like shown below:

scrivito_tag(:div, @obj, :my_attribute, data: { scrivito_editors_placeholder: 'My custom placeholder text' })

String editing and line breaks

The string editor provides two modes:

  • Editing a single line of text. Pressing enter finishes editing: data-scrivito-editors-multiline="false"
  • Multiline text. Pressing enter adds a new line: data-scrivito-editors-multiline="true"

If data-scrivito-editors-multiline has not been specified, Scrivito automatically chooses one of these modes by inspecting the element: Multiple lines are enabled for tags that preserve line breaks, i. e. elements with white-space: prepre-wrap, pre-line.

Examples:

Copy
<%# By default, multiple lines can be entered into PRE elements: %>
<%= scrivito_tag(:pre, @obj, :my_multiline_string) %>

<%# By default, only one line of text can be entered into other elements: %>
<%= scrivito_tag(:h1, @obj, :my_string) %>

<%# We don't want multiline input for these two fields within PRE: %>
<pre>
  Author: <%= scrivito_tag(:span, @obj, :author, data: {scrivito_editors_multiline: false}) %>
  ISBN:   <%= scrivito_tag(:span, @obj, :isbn, data: {scrivito_editors_multiline: false}) %>
<pre>

Please note that specifying data-scrivito-editors-multiline="true" for non-preformatted elements will be confusing to users, since line breaks would only be visible while editing.

Reload after saving a string attribute

Some editors provide an option for enabling a reload event that reloads the widget, modal dialog, or page after successfully saving the changes made to it. By default, the reload event is not triggered. To enable it, use the data-scrivito-editors-reload HTML attribute, like in the following example:

scrivito_tag(:div, @obj, :my_string_attribute, data: { scrivito_editors_reload: true })

The Content Browser

The Content Browser lets you manage and select all kinds of content for placing it onto pages, for example. The Content Browser is opened automatically for link, linklist, reference, and referencelist attributes. For details regarding the Content Browser, please refer to the content browser documentation.

The HTML editors

MediumEditor

Scrivito uses MediumEditor as the default editor for HTML attributes.

MediumEditor options can be set globally by means of a JavaScript property:

Copy
scrivito.editors.medium_editor.options = function() {
  return {
    toolbar: {
      buttons: ['bold', 'italic', 'scrivito_anchor', 'removeFormat']
    }
  };
};

See the MediumEditor options documentation for an overview of the available settings. We recommend to use MediumEditor in conjunction with a div element, like so: scrivito_tag(:div, my_widget, :my_html_attribute)

CodeMirror

If you want to give your power users the full flexibility of HTML, you can provide HTML source editing in detail views.

For this purpose, Scrivito integrates CodeMirror through the scrivito_codemirror_editor gem.

Deprecated as of 1.6.0: Redactor 10

Scrivito also offers Redactor 10 as an alternative HTML editor. Please note that this editor is deprecated as of Scrivito 1.6.0. There won't be any updates in future Scrivito versions.

You can enable Redactor globally by requesting redactor from the select_editor JavaScript callback, or individually per Scrivito tag:

Copy
scrivito_tag(:div, obj, :my_html, {}, editor: :redactor) # deprecated

Redactor options can be set globally through JavaScript. For example:

Copy
// Example: hide the HTML source button for HTML fields
scrivito.editors.redactor_editor.options = { buttonSource: false }

See the Redactor 10 documentation for an overview of the available settings.

The number editor

The number editor supports Scrivito's numeric attribute types, integer and float. When rendering an attribute of one of these types, options for specifying a range and a step size, and for making the attribute value mandatory (i.e. disallowing an empty value) are available:

Copy
<%= scrivito_details_for("Float attribute") do %>
  <%= scrivito_tag(:div, obj, :float_attribute, 
    {data: {
      scrivito_editors_min: 0,
      scrivito_editors_max: 10,
      scrivito_editors_step: 0.1,
      scrivito_editors_allow_delete: false,
      }
    }) %>
<% end %>

Setting scrivito_editors_allow_delete to false causes the editor to reject the empty value which it indicates by setting the input field color to red. Making a numeric attribute mandatory should be accompanied by specifying a default attribute value for it in the object class concerned.

The binary editor

Binary content, e.g. an image or a PDF file, is usually included on a page by means of a reference attribute. The image widget, for example, has such a reference attribute for storing the ID of the image object to display. This allows an editor to edit a page without having to worry about which other pages they might change by replacing an image.

The binary editor, however, lets you exchange the binary content itself, meaning that all occurrences of this content on other pages are changed as well. No new CMS object is created, the values of the reference attributes pointing to this content aren't modified and don't become outdated. You can thus update your quarterly report, for example, and all references to it will point to the new version. Including a binary editor is easy:

Copy
# For an image
scrivito_image_tag(@obj, :my_image_attribute)

# For binary data other than image data
scrivito_tag(:div, @obj, :my_binary_attribute) do
  @obj.my_binary_attribute.try(:filename)
end

To prevent editors from inadvertently modifying other pages, we recommend to not include binary attributes on content pages and restrict their use to details views. The example app uses the binary editor to allow exchanging images using the content browser:

By default, the binary editor won't let you remove the contents of a binary attribute. To enable deletion, pass the data-scrivito-editors-allow-delete option to the scrivito_tag, and a small trash can icon will be displayed in the upper right corner. Clicking this icon causes the binary data of the corresponding attribute to be deleted. To display an image with the option to delete its content, use the following code:

Copy
# Make binary image data deletable
scrivito_image_tag(@obj, :my_image_attribute, data: { scrivito_editors_allow_delete: true })

# For binary data other than image data
scrivito_tag(:div, @obj, :my_binary_attribute, data: { scrivito_editors_allow_delete: true }) do
  @obj.my_binary_attribute.try(:filename)
end

Note that if your application relies on the presence of binary data, making the data deletable requires adapting the application accordingly.

The image editor

The image editor lets you enhance, crop, and rotate photos, as well as apply various filter effects to image content.

Making an image editable is easy:

Copy
# For an image
scrivito_image_tag(@obj)

# For an image attribute
scrivito_image_tag(@obj, :my_binary_attribute)

To prevent editors from inadvertently modifying other pages, we recommend to not include scrivito_image_tag(@obj) on content pages and restrict its use to the details view of images.

Data attributes overview

Name and description Values Applicable to
data-scrivito-editors-autosave

You can disable save as you type by setting this attribute to false.
Default: true.

true, false string
data-scrivito-editors-date-format

Date format, passed on to the jQuery UI datepicker.
Default: yy-mm-dd.

Everything supported by jQuery UI datepicker. date
data-editor

Deprecated as of 0.71.0. Please use the editor option of the scrivito_tag helper.

Enforce an editor. The value can be one of the predefined editors, or any custom or third-party editor name.

binary, date, enum, html, image, image_drop, link, linklist, multienum, reference, referencelist, slider, string, stringlist, custom
data-scrivito-editors-filter-context, data-scrivito-editors-filter-context-*

Set a context property for the Content Browser. Filter context attributes are passed on to the filter function configured for the Content Browser.

Everything natively supported by data attributes. E.g. {"example": [1, 2, 3]}, my_value, true
Note that if you specify the top level attribute, data-scrivito-editors-filter-context, it is expected to be a hash.
link, linklist, reference, referencelist, html
data-scrivito-editors-filters

Pass custom filters to the Content Browser when editing references.

{"example": {
  "field": "_obj_class",
  "options": {"Image": {}}
}}
link, linklist, reference, referencelist, html
data-scrivito-editors-max

The maximum value. The default is 10 for the slider editor.

A number
number, slider
data-scrivito-editors-min

The minimum value. The default is 1 for the slider editor.

A number
number, slider
data-scrivito-editors-multiline

Enforce single-line or multi-line text input. Default: automatic.

true, false string
data-scrivito-editors-placeholder

Change the placeholder text shown if the field is empty.

A string date, enum, multienum, html, reference, slider, string
data-scrivito-editors-reload

Force the field to be reloaded after editing. Default: false

true, false date, enum, html, slider, string
data-scrivito-editors-allow-delete

float and integer attributes: Allow users to clear a number. Default: true

binary and reference attributes: Display a delete button. Default: false

true, false binary, float, integer, reference
data-scrivito-editors-binary-filename

Starting at version 1.2, this shows an input field and a button for renaming the file associated with a binary attribute. Default: true

true, false binary
data-scrivito-editors-step

The slider/spinner increment value. Default: 1

A number
number, slider
data-scrivito-editors-time-format

Time format, passed on to the jQuery UI timepicker.

Everything supported by jQuery UI timepicker. date