Module: ScrivitoHelper

Includes:
Scrivito::ControllerHelper
Defined in:
app/helpers/scrivito_helper.rb

Overview

This module provides several helper methods for rendering the CMS contents and enabling the in-place editing.

Details Dialog Size collapse

Instance Method Summary collapse

Methods included from Scrivito::ControllerHelper

#scrivito_in_editable_view?, #scrivito_path, #scrivito_url, #scrivito_user

Instance Method Details

The scrivito_backlinks helper generates HTML markup for the list of backlinks of a given CMS object.

The helper is intended to be used on details views. The DOM structure it generates and the CSS classes it uses are compatible with the CSS of the SDK. This helper ensures that backlink lists fit into the design the SDK applies.

Examples:

scrivito_details_for "Backlinks:" do
  scrivito_backlinks @obj
end

Parameters:

See Also:



498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
 
# File 'app/helpers/scrivito_helper.rb', line 498

def scrivito_backlinks(obj)
  content_tag(:div, class: 'scrivito_backlinks_list') do
    backlinks = obj.backlinks.to_a

    if backlinks.any?
      content_tag(:ul) do
        capture do
          backlinks.each do |o|
            concat(content_tag(:li) {
              concat(content_tag(:i, nil, class: 'scrivito_icon scrivito_icon_link'))
              concat(link_to(o.description_for_editor, scrivito_path(o), target: :_blank))
            })
          end
        end
      end
    end
  end
end

#scrivito_body_tags ⇒ Object

Renders all tags needed in the HTML body.



406
407
408
409
410
 
# File 'app/helpers/scrivito_helper.rb', line 406

def scrivito_body_tags
  if scrivito_user
    Scrivito::LayoutTags.new(self).page_config(@obj)
  end
end

#scrivito_cache(key, options = {}, &block) ⇒ Object

This method wraps Rails’ built-in fragment caching to work with content delivered by Scrivito. Fragment caching applies to computed parts of views and helps to improve performance. The Rails guides provide an excellent introduction to caching if you haven’t used it yet.

The scrivito_cache method extends built-in fragment caching so that cached parts of a view are automatically recomputed when Scrivito content changes. The fragments are only cached for the published content. In editable working copies no caching takes place, and the fragments are computed for every request.

Parameters:

  • key (String) —

    a name describing the data to be cached.

  • options (Hash) (defaults to: {}) —

    a hash that enables further configuration of the fragment cache. The options are passed to the cache helper of Rails. See the Rails documentation for details.



455
456
457
458
 
# File 'app/helpers/scrivito_helper.rb', line 455

def scrivito_cache(key, options={}, &block)
  workspace = Scrivito::Workspace.current
  cache_if(workspace.published? && !scrivito_user, [workspace.cache_key, key], options, &block)
end

#scrivito_details_for(title = nil, &block) ⇒ Object

Attribute group helper generates HTML for page details dialog and widget details dialog. The generated HTML has appropriate DOM structure and CSS classes, which are compatible with the CSS of the SDK. By using this helper you ensure, that the look of your attribute groups fits into the SDK’s design.

Examples:

scrivito_details_for('Title and Category') do
  concat scrivito_tag(:div, @obj, :title)
  concat scrivito_tag(:div, @obj, :category)
end

scrivito_details_for do
  scrivito_tag(:div, @obj, :abstract)
end

Parameters:

  • title (String) (defaults to: nil) —

    title of the attribute group.

  • block (Proc) —

    content of the attribute group.



333
334
335
336
337
338
339
340
341
342
 
# File 'app/helpers/scrivito_helper.rb', line 333

def scrivito_details_for(title = nil, &block)
  content_tag(:div, class: 'scrivito_content_group') do
    capture do
      if title
        concat content_tag(:h3, title)
      end
      concat capture(&block)
    end
  end
end

#scrivito_field(obj, field_name) ⇒ Object

Note:

Content rendered using this method will not be editable in the Scrivito UI. If you want in-place editing, then please use #scrivito_tag instead.

Renders a field from the CMS.

Examples:

scrivito_field(@obj, :title)
scrivito_field(@obj, 'headline')

Parameters:

  • obj (Scrivito::BasicObj) —

    an Obj, whose field should be rendered.

  • field_name (String, Symbol) —

    the field of obj to be rendered.



253
254
255
 
# File 'app/helpers/scrivito_helper.rb', line 253

def scrivito_field(obj, field_name)
  scrivito_value(obj[field_name])
end

#scrivito_head_tags ⇒ Object

Renders all tags needed in the HTML head.



391
392
393
394
395
396
397
398
399
400
 
# File 'app/helpers/scrivito_helper.rb', line 391

def scrivito_head_tags
  layout_tags = Scrivito::LayoutTags.new(self)
  capture do
    concat layout_tags.editing_auth_warning
    concat layout_tags.generator_meta_tag
    if scrivito_user
      concat javascript_include_tag('scrivito_ui_redirect')
    end
  end
end

#scrivito_image_tag(obj, field_name_or_tag_options = nil, tag_or_editing_options = {}, editing_options = {}) ⇒ String

Note:

If you do not specify an HTML alt attribute, the helper method will use Obj#alt_description of the target object.

Calculates an HTML image tag of an image stored in the CMS for inplace editing.

Examples:

scrivito_image_tag(@obj, :my_linklist)
scrivito_image_tag(@obj, :my_linklist, alt: 'Interesting picture', class: 'my_image')
scrivito_image_tag(@obj, :my_linklist, {}, placeholder: image_path('my_placeholder.png'))
scrivito_image_tag(@obj, :my_linklist, {class: 'my_image'}, placeholder: 'http://placehold.it/350x150')

Render an image tag for a reference attribute.

scrivito_image_tag(@obj, :my_reference)

Render an image tag for a link attribute.

scrivito_image_tag(@obj, :my_link)

Render an image tag for a binary attribute

scrivito_image_tag(@obj, :my_binary)

Render an image tag for a binary Obj

scrivito_image_tag(@image)

Render an image tag with an on-the-fly calculated thumbnail

scrivito_image_tag @obj, :my_binary, {}, transform: {width: 50, height: 50}

Parameters:

  • obj (Obj) —

    Obj with a link_list, reference, link or binary attribute

  • field_name_or_tag_options (String, Symbol, Hash) (defaults to: nil) —

    Name of link_list, reference, link, or binary attribute, which contains the image or additional HTML attributes for the tag. The field_name can be omitted for binary Objs and blob will be used as default.

  • tag_or_editing_options (Hash) (defaults to: {}) —

    Additional HTML attributes for the tag or the editing options if no field_name was given

  • editing_options (Hash) (defaults to: {}) —

    Additional options for inplace editing

Options Hash (editing_options):

  • :placeholder (String) — default: 'scrivito/image_placeholder.gif' —

    URL or path to image to be displayed if target is missing

  • :transform (Hash) —

    if set, the displayed image will be transformed using the definition in the given hash, see Scrivito::Binary#transform.

Returns:

  • (String) —

    HTML image tag

Raises:

  • (ScrivitoError) —

    if field_name is not set and Obj is not binary



188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
 
# File 'app/helpers/scrivito_helper.rb', line 188

def scrivito_image_tag(obj, field_name_or_tag_options=nil,
                       tag_or_editing_options = {}, editing_options = {})
  field_name, tag_options, editing_options =
    if field_name_or_tag_options.is_a?(Hash)
      [nil, field_name_or_tag_options, tag_or_editing_options]
    else
      [field_name_or_tag_options, tag_or_editing_options, editing_options]
    end

  if field_name.blank?
    if obj.binary?
      field_name = :blob
    else
      raise Scrivito::ScrivitoError,
          "when omitting `field_name' you have to pass a binary obj"
    end
  end

  options = Scrivito::ImageTag.new(self).options(obj, field_name,
      tag_options.with_indifferent_access, editing_options.with_indifferent_access)
  scrivito_tag('img', obj, field_name, options)
end

#scrivito_large_dialog(&block) ⇒ String

Set the size of the page and widget details dialog to large.

Examples:

scrivito_large_dialog do
  scrivito_details_for('Title and Category') do
    concat scrivito_tag(:div, @obj, :title)
    concat scrivito_tag(:div, @obj, :category)
  end
end

Parameters:

  • block (Proc) —

    Block to render inner HTML.

Returns:

  • (String) 


357
358
359
 
# File 'app/helpers/scrivito_helper.rb', line 357

def scrivito_large_dialog(&block)
  Scrivito::DialogSizeHelper.render_dialog_with_size(self, 'large', &block)
end

#scrivito_medium_dialog(&block) ⇒ String

Set the size of the page and widget details dialog to medium (default).

Examples:

scrivito_medium_dialog do
  # see scrivito_large_dialog example
end

Parameters:

  • block (Proc) —

    Block to render inner HTML.

Returns:

  • (String) 


369
370
371
 
# File 'app/helpers/scrivito_helper.rb', line 369

def scrivito_medium_dialog(&block)
  Scrivito::DialogSizeHelper.render_dialog_with_size(self, 'medium', &block)
end

#scrivito_small_dialog(&block) ⇒ String

Set the size of the page and widget details dialog to small.

Examples:

scrivito_small_dialog do
  # see scrivito_large_dialog example
end

Parameters:

  • block (Proc) —

    Block to render inner HTML.

Returns:

  • (String) 


381
382
383
 
# File 'app/helpers/scrivito_helper.rb', line 381

def scrivito_small_dialog(&block)
  Scrivito::DialogSizeHelper.render_dialog_with_size(self, 'small', &block)
end

#scrivito_tag(tag_name, obj_or_widget, field_name, html_options = {}, editing_options = {}, &block) ⇒ String

Note:

If the param field_name is of type widget, then tag_name must be a block tag, like div or h1. An inline tag like p or span could result in broken HTML output, since the widgets are rendered within block tags.

Renders a field within the given HTML tag.

This method also renders additional attributes, which are needed for in-place editing. These attributes are only rendered when appropriate, i.e. not for a regular visitor.

The helper is similar to (and internally uses) api.rubyonrails.org/classes/ActionView/Helpers/TagHelper.html#method-i-content_tag. You can add additional HTML attributes by passing them in html_options.

Examples:

Renders an <h2> tag containing the text of the headline attribute of @obj and assigns the tag a css class called very_important

scrivito_tag(:h2, @obj, :headline, class: "very_important")

Renders an <h2> tag containing a truncated headline of the widget

scrivito_tag(:h2, widget, :headline) do
  truncate(widget.headline)
end

Render a download link for a PDF document

scrivito_tag(:div, @obj, :pdf) do
  if @obj.pdf
    "Download: #{link_to(@obj.pdf.filename, @obj.pdf.url)}"
  elsif scrivito_user
    "Drop PDF here to upload"
  end
end

Render widgetlist inside an ul tag with the individual widgets inside of li tags.

scrivito_tag(:ul, @obj, :body, {}, inner_tag: :li)

Parameters:

  • tag_name (String, Symbol) —

    Name of the HTML tag (e.g. :h1 or :div). If the param field_name is of type widget, then tag_name must be a block tag, like div or h1. An inline tag like p or span could result in broken HTML output, since the widgets are rendered within block tags.

  • obj_or_widget (Scrivito::BasicObj, Scrivito::BasicWidget) —

    A Scrivito::BasicObj or Scrivito::BasicWidget from which the field_name is read.

  • field_name (String, Symbol) —

    Which field of the Obj should be rendered.

  • html_options (Hash) (defaults to: {}) —

    HTML options to be passed to content_tag.

  • editing_options (Hash) (defaults to: {}) —

    Additional editing options for widgets (e.g. :inner_tag)

  • block (Proc) —

    Optional block to render inner HTML. If none given the value of attribute will be rendered instead. block is not allowed for fields of type widget.

Options Hash (editing_options):

  • :inner_tag (Symbol) —

    Wraps widgets inside specified tag

  • :editor (String, Symbol) —

    Name of the JavaScript editor to be used for this field. Normally, the name of the editor to be used for a field is determined by the scrivito.select_editor JavaScript API. The option :editor should only be used if setting the editor via the JavaScript API is not feasible. Specifying editor: false disables in-place editing.

  • :disable_margins (Boolean) —

    If true, no margins are attached to the widgets contained in a widgetlist attribute. In this case, the in-place editing controls of widgets may overlap which can be handled by using suitable CSS. Defaults to false.

Returns:

  • (String) —

    The rendered HTML tag.

Raises:

  • ArgumentError if the field behind field_name is of type widget and a block is given.



73
74
75
76
77
78
79
 
# File 'app/helpers/scrivito_helper.rb', line 73

def scrivito_tag(tag_name, obj_or_widget, field_name,
                 html_options = {}, editing_options = {}, &block)
  Scrivito::CmsFieldTag.new(self, tag_name, obj_or_widget, editing_options.merge(
    widget_render_context: @scrivito_widget_render_context,
    field_name: field_name.to_s
  )).render(html_options, &block)
end

#scrivito_tag_list(tag_name, obj, method_name, options = {}) {|list, child| ... } ⇒ String

Renders a navigation ready for in-place editing.

If a navigation is rendered using this helper method, a special menu is attached to it that lets you change the order of the child pages or insert a new child.

For making the child pages sortable, the parent Obj requires a referencelist attribute named child_order. When creating a page model using the page generator, such an attribute is automatically added to the model.

Examples:

Renders a navigation for an @obj with two children in its toclist, whose titles are “Toys” and “Electronics” respectively:

scrivito_tag_list(:ul, @obj, :toclist, class: "my_list") do |list, child|
  list.tag(:li, class: "my_list_element") do
    link_to(scrivito_path(child)) do
      scrivito_tag(:span, child, :title)
    end
  end
end

#
# Basically, the rendered HTML will look like this:
#
# <ul class="my_list">
#   <li class="my_list_element">
#     <a href="/toys-902b3e8d6ec861c1">
#       <span>Toys</span>
#     </a>
#   </li>
#   <li class="my_list_element">
#     <a href="/electronics-59c6995988ce78f4">
#       <span>Electronics</span>
#     </a>
#   </li>
# </ul>
#

Parameters:

  • tag_name (String, Symbol) —

    Name of the outer HTML tag (e.g. :ul or :div).

  • obj (Scrivito::BasicObj) —

    The parent Obj, on which method_name will be called in order to fetch the children.

  • method_name (String, Symbol) —

    Name of the method to be called on the parent Obj in order to fetch the children. Currently, only toclist is supported.

  • options (Hash) (defaults to: {}) —

    Options to be passed to content_tag. Use them to add HTML attributes to the tag.

Yield Parameters:

Returns:

  • (String) —

    The rendered HTML string.

See Also:



137
138
139
 
# File 'app/helpers/scrivito_helper.rb', line 137

def scrivito_tag_list(tag_name, obj, method_name, options = {}, &block)
  Scrivito::ChildListTag.new(tag_name, obj, method_name.to_s, self).render(options, &block)
end

#scrivito_thumbnail(title, icon = :scrivito, &block) ⇒ Object

Thumbnail helper generates HTML for the page class selection dialog and the widget class selection dialog. The generated HTML has appropriate DOM structure and CSS classes, which are compatible with the CSS of the SDK. By using this helper you ensure, that the look of your thumbnails fits into the SDK’s design.

Examples:

A simple thumbnail

scrivito_thumbnail('Content Page') do
  'A content page.'
end

A thumbnail with a built-in icon

scrivito_thumbnail('Image Widget', :image) do
  'An image widget.'
end

A thumbnail with custom icon HTML

scrivito_thumbnail('Blog', content_tag(:i, '', class: 'thumbnail-blog')) do
  'A blog post.'
end

Parameters:

  • title (String) —

    title of the thumbnail, e.g. “Content Page” or “Image Widget”.

  • icon (Symbol, String) (defaults to: :scrivito) —

    icon of the thumbnail. You can use one of the built-in icons or specify your own HTML. There are following built-in icons: :content, :headline, :image, :scrivito and :text. If the name of the specified icon is unknown, then the default icon (:scrivito) will be displayed. If you are specifying your own HTML string, then make sure it is HTML safe.

  • block (Proc) —

    the description of the thumbnail.



287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
 
# File 'app/helpers/scrivito_helper.rb', line 287

def scrivito_thumbnail(title, icon = :scrivito, &block)
  if icon.is_a?(Symbol)
    icon_code = {
      content:  '&#xf122;',
      headline: '&#xf102;',
      image:    '&#xf101;',
      scrivito: '&#xf000;',
      text:     '&#xf100;',
    }.fetch(icon, '&#xf000;')
    icon = content_tag(:i, icon_code.html_safe, class: 'scrivito_icon')
  end

  content_tag(:div, 'data-scrivito-private-thumbnail-title' => title) do
    capture do
      concat content_tag(:div, icon, class: 'thumbnail')
      concat content_tag(:div, title, class: 'title')

      if block_given?
        concat content_tag(:div, class: 'description', &block)
      else
        concat content_tag(:div, nil, class: 'description')
      end
    end
  end
end

#scrivito_value(value) ⇒ Object

Note:

Content rendered using this method will not be editable in the Scrivito UI. If you want in-place editing, use #scrivito_tag instead.

Renders an attribute value of a CMS model, taking its type into account.

Links inside html attributes are rendered using the routing of the application. Values from string attributes are escaped. For other attribute types, a simple default representation is rendered.

Examples:

scrivito_value(@obj.title)


226
227
228
229
230
231
232
233
234
235
236
 
# File 'app/helpers/scrivito_helper.rb', line 226

def scrivito_value(value)
  renderer = Scrivito::AttributeValueRenderer.new(self)

  case value
  when Scrivito::BasicWidget then render(template: value.show_view_path, locals: {widget: value})
  when Scrivito::HtmlString  then renderer.render_as_html(value)
  when String                then renderer.render_as_string(value)
  when Time                  then renderer.render_as_date(value)
  else value
  end
end

#scrivito_widget_tag(html_options, &block) ⇒ Object

This helper can be used in the show.html.* template of widgets. It allows you to specify attributes (including CSS classes) for the tag enclosing the widget.

Examples:

It should be wrapped around the entire template like this:

<%= scrivito_widget_tag class: 'my_class', data-very-funky: true do %>
  <%= scrivito_image_tag widget, :image %>
<% end %>

Parameters:

  • html_options (Hash) —

    attributes for this tag.



473
474
475
476
477
 
# File 'app/helpers/scrivito_helper.rb', line 473

def scrivito_widget_tag(html_options, &block)
  capture(&block).tap do
    @scrivito_widget_tag_html_options = html_options
  end
end