scrivito_helper.rb in scrivito_sdk-1.1.0.rc1

- old
+ new

@@ -74,42 +74,67 @@
       field_name: field_name.to_s
     )).render(html_options, &block)
   end
 
   #
+  # Renders a navigation ready for in-place editing.
+  #
   # @api public
   #
-  # @param tag_name [String, Symbol] Name of the html tag (e.g. +:h1+ or +:div+).
-  # @param obj [Scrivito::BasicObj] A {Scrivito::BasicObj} from which field_name is read.
-  # @param field_name [String, Symbol] Which field_name of the Obj should be rendered. Currently
-  #   only +toclist+ is supported
-  # @param options [Hash] Additional options, which are passed to +content_tag+. Use them to add
-  #   HTML attributes to the tag
+  # 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.
   #
-  # @yieldparam [Scrivito::ChildListTag::ObjTag] list An instance, where +tag+ should be called once.
-  # @yieldparam [Scrivito::BasicObj] child Each child of +toclist+
+  # For making the child pages sortable, the parent {Scrivito::BasicObj 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.
   #
-  # @return [String] The rendered html tag
+  # @param tag_name [String, Symbol] Name of the outer HTML tag (e.g. +:ul+ or +:div+).
+  # @param obj [Scrivito::BasicObj] The parent {Scrivito::BasicObj Obj}, on which +method_name+ will
+  #   be called in order to fetch the children.
+  # @param method_name [String, Symbol] Name of the method to be called on the parent
+  #   {Scrivito::BasicObj Obj} in order to fetch the children. Currently, only +toclist+ is
+  #   supported.
+  # @param options [Hash] Options to be passed to +content_tag+. Use them to add HTML attributes to
+  #   the tag.
   #
-  # @example
-  #   scrivito_tag_list(:div, @obj, :toclist, class: "very_important") do |list, child|
-  #     list.tag(:div, class: "also_important") do
+  # @yieldparam [Scrivito::ChildListTag::ObjTag] list An object on which the
+  #   {Scrivito::ChildListTag::ObjTag#tag tag} method should be called once per child to enable
+  #   in-place editing.
+  # @yieldparam [Scrivito::BasicObj] child Each child of +toclist+.
+  #
+  # @return [String] The rendered HTML string.
+  #
+  # @see Scrivito::ChildListTag::ObjTag#tag
+  #
+  # @example 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
   #
-  #   # 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>
+  #   # 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>
+  #   #
   #
-  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)
+  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
 
   #
   # Calculates an HTML image tag of an image stored in the CMS for inplace editing.
   #
@@ -179,34 +204,33 @@
         tag_options.with_indifferent_access, editing_options.with_indifferent_access)
     scrivito_tag('img', obj, field_name, options)
   end
 
   #
-  # Renders an attribute <em>value</em> of a CMS model.
+  # Renders an attribute value of a CMS model, taking its type into account.
   #
-  #   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
+  # @api public
   #
-  # @note Content rendered using this method
-  #   will not be editable in the Scrivito UI.
-  #   If you want In-Place-Editing, use {ScrivitoHelper#scrivito_tag} instead.
+  # 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.
   #
-  # @api public
+  # @example
+  #   scrivito_value(@obj.title)
   #
+  # @note Content rendered using this method will not be editable in the Scrivito UI. If you want
+  #   in-place editing, use {ScrivitoHelper#scrivito_tag} instead.
+  #
   def scrivito_value(value)
+    renderer = Scrivito::AttributeValueRenderer.new(self)
+
     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.show_view_path, locals: {widget: value})
-      else 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
 
   #
   # Renders a field from the CMS.
@@ -395,7 +419,28 @@
   def inplace_editing_allowed?
     raise %{
       The helper method `inplace_editing_allowed?' has been removed.
       Please use helper method `scrivito_user` instead.
     }
+  end
+
+  # @api public
+  #
+  # 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.
+  #
+  # @param key [String] a name describing the data to be cached.
+  # @param options [Hash] a hash that enables further configuration of the fragment
+  #   cache. The options are passed to the +cache+ helper of Rails. See the Rails
+  #   {http://api.rubyonrails.org/classes/ActionView/Helpers/CacheHelper.html#method-i-cache documentation}
+  #   for details.
+  def scrivito_cache(key, options=nil, &block)
+    workspace = Scrivito::Workspace.current
+    cache_if(workspace.published?, [workspace.cache_key, key], options, &block)
   end
 end