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

#scrivito_body_tags ⇒ Object

Renders all tags needed in the HTML body.



395
396
397
 
# File 'app/helpers/scrivito_helper.rb', line 395

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

#scrivito_cache(key, options = nil, &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: nil) —

    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.



442
443
444
445
 
# File 'app/helpers/scrivito_helper.rb', line 442

def scrivito_cache(key, options=nil, &block)
  workspace = Scrivito::Workspace.current
  cache_if(workspace.published?, [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.



325
326
327
328
329
330
331
332
333
334
 
# File 'app/helpers/scrivito_helper.rb', line 325

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.



250
251
252
 
# File 'app/helpers/scrivito_helper.rb', line 250

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

#scrivito_head_tags ⇒ Object

Renders all tags needed in the HTML head.



383
384
385
386
387
388
389
 
# File 'app/helpers/scrivito_helper.rb', line 383

def scrivito_head_tags
  layout_tags = Scrivito::LayoutTags.new(self)
  capture do
    concat layout_tags.editing_auth_warning
    concat layout_tags.generator_meta_tag
  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



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

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) 


349
350
351
 
# File 'app/helpers/scrivito_helper.rb', line 349

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) 


361
362
363
 
# File 'app/helpers/scrivito_helper.rb', line 361

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) 


373
374
375
 
# File 'app/helpers/scrivito_helper.rb', line 373

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.

Returns:

  • (String) —

    The rendered HTML tag.

Raises:

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



70
71
72
73
74
75
76
 
# File 'app/helpers/scrivito_helper.rb', line 70

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:



134
135
136
 
# File 'app/helpers/scrivito_helper.rb', line 134

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 specyfied icon is unknown, then the default icon (:scrivito) will be displayed. If you are speifying your own HTML string, then make sure it is HTML safe.

  • block (Proc) —

    the description of the thumbnail.



284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
 
# File 'app/helpers/scrivito_helper.rb', line 284

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, class: 'scrivito_editing_widget_preview') do
    capture do
      concat content_tag(:div, icon, class: 'scrivito_editing_widget_visualization')
      concat content_tag(:div, title, class: 'scrivito_editing_widget_title')
      concat content_tag(:div, class: 'scrivito_editing_widget_description', &block)
    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)



223
224
225
226
227
228
229
230
231
232
233
 
# File 'app/helpers/scrivito_helper.rb', line 223

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