scrivito_helper.rb in scrivito_sdk-0.41.0.rc1

- old
+ new
@@ -6,45 +6,56 @@
 #
 module ScrivitoHelper
   include Scrivito::RoutingHelper
 
   #
-  # Returns an HTML block tag containing content from an Obj.
-  # Add HTML attributes by passing an attributes hash to options.
-  # The helper method is somewhat similar to (and internally uses)
+  # 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)
   # http://api.rubyonrails.org/classes/ActionView/Helpers/TagHelper.html#method-i-content_tag.
+  # You can add additional HTML attributes by passing them in +html_options+.
   #
   # @api public
   #
-  # This helper method also renders additional data attributes, which are needed for inplace editing.
-  # These attributes are only rendered when appropriate, i.e. not for a regular visitor.
+  # @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.
   #
-  # @param tag_name [String, Symbol] Name of the html tag (e.g. +:h1+ or +:div+).
+  # @param 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.
   # @param obj_or_widget [Scrivito::BasicObj, Scrivito::BasicWidget] A {Scrivito::BasicObj}
   #   or {Scrivito::BasicWidget} from which the +field_name+ is read.
   # @param field_name [String, Symbol] Which field of the Obj should be rendered.
   # @param html_options [Hash] HTML options to be passed to +content_tag+.
   # @param 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+.
+  #
   # @raise ArgumentError if the field behind +field_name+ is of type +widget+ and a +block+ is given.
-  # @return [String] The rendered html tag
   #
-  # @example Renders an <h2> tag containing the text of the +headline+ attribute of +@obj+ and assigns the tag a css class called +very_important+.
+  # @return [String] The rendered HTML tag.
+  #
+  # @example 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" %>
   #
-  # @example Renders an <h2> tag containing an escaped +headline+.
-  #     <%= scrivito_tag :h2, @obj, :headline do %>
-  #       <%= strip_tags @obj.headline %>
+  # @example Renders an <h2> tag containing a truncated +headline+ of the +widget+
+  #     <%= scrivito_tag :h2, widget, :headline do %>
+  #       <%= truncate widget.headline %>
   #     <% end %>
   #
   # @example 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 %>
+  #
   def scrivito_tag(tag_name, obj_or_widget, field_name, html_options = {}, &block)
     Scrivito::CmsFieldTag.new(
       self, tag_name, obj_or_widget, field_name.to_s
     ).render(html_options, &block)
   end