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.



364
365
366
 
# File 'app/helpers/scrivito_helper.rb', line 364

def scrivito_body_tags
  Scrivito::LayoutTags.new(self).page_config(@obj)
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.



294
295
296
297
298
299
300
301
302
303
 
# File 'app/helpers/scrivito_helper.rb', line 294

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
      yield
    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.



219
220
221
 
# File 'app/helpers/scrivito_helper.rb', line 219

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

#scrivito_head_tags ⇒ Object

Renders all tags needed in the HTML head.



352
353
354
355
356
357
358
 
# File 'app/helpers/scrivito_helper.rb', line 352

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: '/assets/scrivito/image_placeholder.png' —

    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



153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
 
# File 'app/helpers/scrivito_helper.rb', line 153

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) 


318
319
320
 
# File 'app/helpers/scrivito_helper.rb', line 318

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) 


330
331
332
 
# File 'app/helpers/scrivito_helper.rb', line 330

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) 


342
343
344
 
# File 'app/helpers/scrivito_helper.rb', line 342

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

Returns:

  • (String) —

    The rendered HTML tag.

Raises:

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



63
64
65
66
67
68
69
 
# File 'app/helpers/scrivito_helper.rb', line 63

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_template_name: @scrivito_default_widget_template || :show,
    field_name: field_name.to_s
  )).render(html_options, &block)
end

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

Returns The rendered html tag.

Examples:

scrivito_tag_list(:div, @obj, :toclist, class: "very_important") do |list, child|
  list.tag(:div, class: "also_important") do
    link_to(scrivito_path(child)) do
      scrivito_tag(:span, child, :title)
    end
  end
end

# result for an obj with two children:
#
# <div class="very_important">
#   <div class="also_important"><a href="/child1"><span>Child 1</span></a></div>
#   <div class="also_important"><a href="/child2"><span>Child 2</span></a></div>
# </div>

Parameters:

  • tag_name (String, Symbol) —

    Name of the html tag (e.g. :h1 or :div).

  • obj (Scrivito::BasicObj) —

    A Scrivito::BasicObj from which field_name is read.

  • field_name (String, Symbol) —

    Which field_name of the Obj should be rendered. Currently only toclist is supported

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

    Additional options, which are passed to content_tag. Use them to add HTML attributes to the tag

Yield Parameters:

Returns:

  • (String) —

    The rendered html tag



102
103
104
 
# File 'app/helpers/scrivito_helper.rb', line 102

def scrivito_tag_list(tag_name, obj, field_name, options = {}, &block)
  Scrivito::ChildListTag.new(tag_name, obj, field_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.



253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
 
# File 'app/helpers/scrivito_helper.rb', line 253

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.

scrivito_value(@obj.title)

Renders the value, taking its type into account.

  • An HtmlString will be exported by converting its links

  • A Time will be exported in an international form: Year-Month-Day Hour:Minutes

  • A non-HTML String will be quoted

  • other values will be rendered unchanged



192
193
194
195
196
197
198
199
200
201
202
 
# File 'app/helpers/scrivito_helper.rb', line 192

def scrivito_value(value)
  case value
    when Scrivito::HtmlString
      Scrivito::CmsRouting.new(request, main_app, scrivito_engine).convert_links(value).html_safe
    when String then h(value)
    when Time then h(l(value))
    when Scrivito::BasicWidget
      render(template: value.to_show_view_path, locals: {widget: value})
    else value
  end
end