Module: ScrivitoHelper

Includes:
Scrivito::RoutingHelper
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::RoutingHelper

#scrivito_path, #scrivito_url

Instance Method Details

#scrivito_body_tags ⇒ Object

Renders all tags needed in the HTML body.



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

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



288
289
290
291
292
293
294
295
296
297
 
# File 'app/helpers/scrivito_helper.rb', line 288

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.



213
214
215
 
# File 'app/helpers/scrivito_helper.rb', line 213

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

#scrivito_head_tags ⇒ Object

Renders all tags needed in the HTML head.



346
347
348
349
350
351
352
 
# File 'app/helpers/scrivito_helper.rb', line 346

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)

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

Returns:

  • (String) —

    HTML image tag

Raises:

  • (ScrivitoError) —

    if field_name is not set and Obj is not binary



147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
 
# File 'app/helpers/scrivito_helper.rb', line 147

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_in_editable_view? ⇒ Boolean

Returns whether the GUI is in the editable view.

Returns:

  • (Boolean) —

    true if the current visitor is an authenticated editor, the selected workspace is editable and the display mode is editing.

  • false otherwise.



409
410
411
 
# File 'app/helpers/scrivito_helper.rb', line 409

def scrivito_in_editable_view?
  Scrivito::EditingContextHelper.new(request).in_editable_view?
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) 


312
313
314
 
# File 'app/helpers/scrivito_helper.rb', line 312

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) 


324
325
326
 
# File 'app/helpers/scrivito_helper.rb', line 324

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) 


336
337
338
 
# File 'app/helpers/scrivito_helper.rb', line 336

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.



247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
 
# File 'app/helpers/scrivito_helper.rb', line 247

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_user ⇒ Scrivito::User

Returns the current user.

Returns:



390
391
392
 
# File 'app/helpers/scrivito_helper.rb', line 390

def scrivito_user
  Scrivito::EditingContextHelper.new(request).scrivito_user
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



186
187
188
189
190
191
192
193
194
195
196
 
# File 'app/helpers/scrivito_helper.rb', line 186

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