nanoc 3.2.4 → 3.3.0

data/lib/nanoc/helpers/breadcrumbs.rb

@@ -0,0 +1,40 @@
+# encoding: utf-8
+
+module Nanoc::Helpers
+
+  # Provides support for breadcrumbs, which allow the user to go up in the
+  # page hierarchy.
+  module Breadcrumbs
+
+    # Creates a breadcrumb trail leading from the current item to its parent,
+    # to its parent’s parent, etc, until the root item is reached. This
+    # function does not require that each intermediate item exist; for
+    # example, if there is no `/foo/` item, breadcrumbs for a `/foo/bar/` item
+    # will contain a `nil` element.
+    #
+    # @return [Array] The breadcrumbs, starting with the root item and ending
+    #   with the item itself
+    def breadcrumbs_trail
+      breadcrumbs_for_identifier(@item.identifier)
+    end
+
+    def item_with_identifier(identifier)
+      @identifier_cache ||= {}
+      @identifier_cache[identifier] ||= begin
+        @items.find { |i| i.identifier == identifier }
+      end
+    end
+
+    def breadcrumbs_for_identifier(identifier)
+      @breadcrumbs_cache ||= {}
+      @breadcrumbs_cache[identifier] ||= begin
+        head = (identifier == '/' ? [] :  breadcrumbs_for_identifier(identifier.sub(/[^\/]+\/$/, '')) )
+        tail = [ item_with_identifier(identifier) ]
+
+        head + tail
+      end
+    end
+
+  end
+
+end

data/lib/nanoc/helpers/capturing.rb

@@ -0,0 +1,138 @@
+# encoding: utf-8
+
+module Nanoc::Helpers
+
+  # Provides functionality for “capturing” content in one place and reusing
+  # this content elsewhere.
+  #
+  # For example, suppose you want the sidebar of your site to contain a short
+  # summary of the item. You could put the summary in the meta file, but
+  # that’s not possible when the summary contains eRuby. You could also put
+  # the sidebar inside the actual item, but that’s not very pretty. Instead,
+  # you write the summary on the item itself, but capture it, and print it in
+  # the sidebar layout.
+  #
+  # This helper has been tested with ERB and Haml. Other filters may not work
+  # correctly.
+  #
+  # @example Capturing content for a summary
+  #
+  #   <% content_for :summary do %>
+  #     <p>On this item, nanoc is introduced, blah blah.</p>
+  #   <% end %>
+  #
+  # @example Showing captured content in a sidebar
+  #
+  #   <div id="sidebar">
+  #     <h3>Summary</h3>
+  #     <%= content_for(@item, :summary) || '(no summary)' %>
+  #   </div>
+  #
+  # @example Showing captured content in a sidebar the old, deprecated way (do not use or I will become very angry)
+  #
+  #   <div id="sidebar">
+  #     <h3>Summary</h3>
+  #     <%= @item[:content_for_summary] || '(no summary)' %>
+  #   </div>
+  module Capturing
+
+    # @api private
+    class CapturesStore
+
+      require 'singleton'
+      include Singleton
+
+      def initialize
+        @store = {}
+      end
+
+      def []=(item, name, content)
+        @store[item.identifier] ||= {}
+        @store[item.identifier][name] = content
+      end
+
+      def [](item, name)
+        @store[item.identifier] ||= {}
+        @store[item.identifier][name]
+      end
+
+    end
+
+    # @overload content_for(name, &block)
+    #
+    #   Captures the content inside the block and stores it so that it can be
+    #   referenced later on. The same method, {#content_for}, is used for
+    #   getting the captured content as well as setting it. When capturing,
+    #   the content of the block itself will not be outputted.
+    #
+    #   For backwards compatibility, it is also possible to fetch the captured
+    #   content by getting the contents of the attribute named `content_for_`
+    #   followed by the given name. This way of accessing captures is
+    #   deprecated.
+    #
+    #   @param [Symbol, String] name The base name of the attribute into which
+    #     the content should be stored
+    #
+    #   @return [void]
+    #
+    # @overload content_for(item, name)
+    #
+    #   Fetches the capture with the given name from the given item and
+    #   returns it.
+    #
+    #   @param [Nanoc::Item] item The item for which to get the capture
+    #
+    #   @param [Symbol, String] name The name of the capture to fetch
+    #
+    #   @return [String] The stored captured content
+    def content_for(*args, &block)
+      if block_given? # Set content
+        # Get args
+        if args.size != 1
+          raise ArgumentError, "expected 1 argument (the name " + 
+            "of the capture) but got #{args.size} instead"
+        end
+        name = args[0]
+
+        # Capture and store
+        content = capture(&block)
+        CapturesStore.instance[@item, name.to_sym] = content
+      else # Get content
+        # Get args
+        if args.size != 2
+          raise ArgumentError, "expected 2 arguments (the item " +
+            "and the name of the capture) but got #{args.size} instead"
+        end
+        item = args[0]
+        name = args[1]
+
+        # Get content
+        CapturesStore.instance[item, name.to_sym]
+      end
+    end
+
+    # Evaluates the given block and returns its contents. The contents of the
+    # block is not outputted.
+    #
+    # @return [String] The captured result
+    def capture(&block)
+      # Get erbout so far
+      erbout = eval('_erbout', block.binding)
+      erbout_length = erbout.length
+
+      # Execute block
+      block.call
+
+      # Get new piece of erbout
+      erbout_addition = erbout[erbout_length..-1]
+
+      # Remove addition
+      erbout[erbout_length..-1] = ''
+
+      # Done
+      erbout_addition
+    end
+
+  end
+
+end

data/lib/nanoc/helpers/filtering.rb

@@ -0,0 +1,50 @@
+# encoding: utf-8
+
+module Nanoc::Helpers
+
+  # Provides functionality for filtering parts of an item or a layout.
+  module Filtering
+
+    require 'nanoc/helpers/capturing'
+    include Nanoc::Helpers::Capturing
+
+    # Filters the content in the given block and outputs it. This function
+    # does not return anything; instead, the filtered contents is directly
+    # appended to the output buffer (`_erbout`).
+    #
+    # This function has been tested with ERB and Haml. Other filters may not
+    # work correctly.
+    #
+    # @example Running a filter on a part of an item or layout
+    #
+    #   <p>Lorem ipsum dolor sit amet...</p>
+    #   <% filter :rubypants do %>
+    #     <p>Consectetur adipisicing elit...</p>
+    #   <% end %>
+    #
+    # @param [Symbol] filter_name The name of the filter to run on the
+    #   contents of the block
+    #
+    # @param [Hash] argument Arguments to pass to the filter
+    #
+    # @return [void]
+    def filter(filter_name, arguments={}, &block)
+      # Capture block
+      data = capture(&block)
+
+      # Find filter
+      klass = Nanoc::Filter.named(filter_name)
+      raise Nanoc::Errors::UnknownFilter.new(filter_name) if klass.nil?
+      filter = klass.new(@item_rep.assigns)
+
+      # Filter captured data
+      filtered_data = filter.run(data, arguments)
+
+      # Append filtered data to buffer
+      buffer = eval('_erbout', block.binding)
+      buffer << filtered_data
+    end
+
+  end
+
+end

data/lib/nanoc/helpers/html_escape.rb

@@ -0,0 +1,55 @@
+# encoding: utf-8
+
+module Nanoc::Helpers
+
+  # Contains functionality for HTML-escaping strings.
+  module HTMLEscape
+
+    require 'nanoc/helpers/capturing'
+    include Nanoc::Helpers::Capturing
+
+    # Returns the HTML-escaped representation of the given string or the given
+    # block. Only `&`, `<`, `>` and `"` are escaped. When given a block, the
+    # contents of the block will be escaped and appended to the output buffer,
+    # `_erbout`.
+    #
+    # @example Escaping a string
+    #
+    #     h('<br>')
+    #     # => '&lt;br&gt;'
+    #
+    # @example Escaping with a block
+    #
+    #     <% h do %>
+    #       <h1>Hello <em>world</em>!</h1>
+    #     <% end %>
+    #     # The buffer will now contain “&lt;h1&gt;Hello &lt;em&gt;world&lt;/em&gt;!&lt;/h1&gt;”
+    #
+    # @param [String] string The string to escape
+    #
+    # @return [String] The escaped string
+    def html_escape(string=nil, &block)
+      if block_given?
+        # Capture and escape block
+        data = capture(&block)
+        escaped_data = html_escape(data)
+
+        # Append filtered data to buffer
+        buffer = eval('_erbout', block.binding)
+        buffer << escaped_data
+      elsif string
+        string.gsub('&', '&amp;').
+               gsub('<', '&lt;').
+               gsub('>', '&gt;').
+               gsub('"', '&quot;')
+      else
+        raise RuntimeError, "The #html_escape or #h function needs either a " \
+          "string or a block to HTML-escape, but neither a string nor a block was given"
+      end
+    end
+
+    alias h html_escape
+
+  end
+
+end

data/lib/nanoc/helpers/link_to.rb

@@ -0,0 +1,151 @@
+# encoding: utf-8
+
+module Nanoc::Helpers
+
+  # Contains functions for linking to items and item representations.
+  module LinkTo
+
+    require 'nanoc/helpers/html_escape'
+    include Nanoc::Helpers::HTMLEscape
+
+    # Creates a HTML link to the given path or item representation, and with
+    # the given text. All attributes of the `a` element, including the `href`
+    # attribute, will be HTML-escaped; the contents of the `a` element, which
+    # can contain markup, will not be HTML-escaped. The HTML-escaping is done
+    # using {Nanoc::Helpers::HTMLEscape#html_escape}.
+    #
+    # @param [String] text The visible link text
+    #
+    # @param [String, Nanoc::Item, Nanoc::ItemRep] target The path/URL,
+    #   item or item representation that should be linked to
+    #
+    # @param [Hash] attributes A hash containing HTML attributes (e.g.
+    #   `rel`, `title`, …) that will be added to the link.
+    #
+    # @return [String] The link text
+    #
+    # @example Linking to a path
+    #
+    #   link_to('Blog', '/blog/')
+    #   # => '<a href="/blog/">Blog</a>'
+    #
+    # @example Linking to an item
+    #
+    #   about = @items.find { |i| i.identifier == '/about/' }
+    #   link_to('About Me', about)
+    #   # => '<a href="/about.html">About Me</a>'
+    #
+    # @example Linking to an item representation
+    #
+    #   about = @items.find { |i| i.identifier == '/about/' }
+    #   link_to('My vCard', about.rep(:vcard))
+    #   # => '<a href="/about.vcf">My vCard</a>'
+    #
+    # @example Linking with custom attributes
+    #
+    #   link_to('Blog', '/blog/', :title => 'My super cool blog')
+    #   # => '<a title="My super cool blog" href="/blog/">Blog</a>'
+    def link_to(text, target, attributes={})
+      # Find path
+      if target.is_a?(String)
+        path = target
+      else
+        path = target.path
+        raise RuntimeError, "Cannot create a link to #{target.inspect} because this target is not outputted (its routing rule returns nil)" if path.nil?
+      end
+
+      # Join attributes
+      attributes = attributes.inject('') do |memo, (key, value)|
+        memo + key.to_s + '="' + h(value) + '" '
+      end
+
+      # Create link
+      "<a #{attributes}href=\"#{h path}\">#{text}</a>"
+    end
+
+    # Creates a HTML link using {#link_to}, except when the linked item is
+    # the current one. In this case, a span element with class “active” and
+    # with the given text will be returned. The HTML-escaping rules for
+    # {#link_to} apply here as well.
+    #
+    # @param [String] text The visible link text
+    #
+    # @param [String, Nanoc::Item, Nanoc::ItemRep] target The path/URL,
+    #   item or item representation that should be linked to
+    #
+    # @param [Hash] attributes A hash containing HTML attributes (e.g.
+    #   `rel`, `title`, …) that will be added to the link.
+    #
+    # @return [String] The link text
+    #
+    # @example Linking to a different page
+    #
+    #   link_to_unless_current('Blog', '/blog/')
+    #   # => '<a href="/blog/">Blog</a>'
+    #
+    # @example Linking to the same page
+    #
+    #   link_to_unless_current('This Item', @item)
+    #   # => '<span class="active" title="You\'re here.">This Item</span>'
+    def link_to_unless_current(text, target, attributes={})
+      # Find path
+      path = target.is_a?(String) ? target : target.path
+
+      if @item_rep && @item_rep.path == path
+        # Create message
+        "<span class=\"active\" title=\"You're here.\">#{text}</span>"
+      else
+        link_to(text, target, attributes)
+      end
+    end
+
+    # Returns the relative path from the current item to the given path or
+    # item representation. The returned path will not be HTML-escaped.
+    #
+    # @param [String, Nanoc::Item, Nanoc::ItemRep] target The path/URL,
+    #   item or item representation to which the relative path should be
+    #   generated
+    #
+    # @return [String] The relative path to the target
+    #
+    # @example
+    #
+    #   # if the current item's path is /foo/bar/
+    #   relative_path_to('/foo/qux/')
+    #   # => '../qux/'
+    def relative_path_to(target)
+      require 'pathname'
+
+      # Find path
+      if target.is_a?(String)
+        path = target
+      else
+        path = target.path
+        raise RuntimeError, "Cannot get the relative path to #{target.inspect} because this target is not outputted (its routing rule returns nil)" if path.nil?
+      end
+
+      # Get source and destination paths
+      dst_path   = Pathname.new(path)
+      raise RuntimeError, "Cannot get the relative path to #{path} because the current item representation, #{@item_rep.inspect}, is not outputted (its routing rule returns nil)" if @item_rep.path.nil?
+      src_path   = Pathname.new(@item_rep.path)
+
+      # Calculate the relative path (method depends on whether destination is
+      # a directory or not).
+      if src_path.to_s[-1,1] != '/'
+        relative_path = dst_path.relative_path_from(src_path.dirname).to_s
+      else
+        relative_path = dst_path.relative_path_from(src_path).to_s
+      end
+
+      # Add trailing slash if necessary
+      if dst_path.to_s[-1,1] == '/'
+        relative_path << '/'
+      end
+
+      # Done
+      relative_path
+    end
+
+  end
+
+end

data/lib/nanoc/helpers/rendering.rb

@@ -0,0 +1,140 @@
+# encoding: utf-8
+
+module Nanoc::Helpers
+
+  # Provides functionality for rendering layouts as partials.
+  module Rendering
+
+    include Nanoc::Helpers::Capturing
+
+    # Renders the given layout. The given layout will be run through the first
+    # matching layout rule.
+    #
+    # When this method is invoked _without_ a block, the return value will be
+    # the rendered layout (a string)  and `_erbout` will not be modified.
+    #
+    # When this method is invoked _with_ a block, an empty string will be
+    # returned and the rendered content will be appended to `_erbout`. In this
+    # case, the content of the block will be captured (using the
+    # {Nanoc::Helpers::Capturing} helper) and this content will be made
+    # available with `yield`. In other words, a `yield` inside the partial
+    # will output the content of the block passed to the method.
+    #
+    # (For the curious: the reason why {#render} with a block has this
+    # behaviour of returning an empty string and modifying `_erbout` is
+    # because ERB does not support combining the `<%= ... %>` form with a
+    # method call that takes a block.)
+    #
+    # The assigns (`@item`, `@config`, …) will be available in the partial. It
+    # is also possible to pass custom assigns to the method; these assigns
+    # will be made available as instance variables inside the partial.
+    #
+    # @param [String] identifier The identifier of the layout that should be
+    #   rendered
+    #
+    # @param [Hash] other_assigns A hash containing extra assigns that will be
+    #   made available as instance variables in the partial
+    #
+    # @example Rendering a head and a foot partial around some text
+    #
+    #   <%= render 'head' %> - MIDDLE - <%= render 'foot' %>
+    #   # => "HEAD - MIDDLE - FOOT" 
+    #
+    # @example Rendering a head partial with a custom title
+    #
+    #   # The 'head' layout
+    #   <h1><%= @title %></h1>
+    #
+    #   # The item/layout where the partial is rendered
+    #   <%= render 'head', :title => 'Foo' %>
+    #   # => "<h1>Foo</h1>"
+    #
+    # @example Yielding inside a partial
+    #
+    #   # The 'box' partial
+    #   <div class="box">
+    #     <%= yield %>
+    #   </div>
+    #
+    #   # The item/layout where the partial is rendered
+    #   <% render 'box' do %>
+    #     I'm boxy! Luvz!
+    #   <% end %>
+    #
+    #   # Result
+    #   <div class="box">
+    #     I'm boxy! Luvz!
+    #   </div>
+    #
+    # @raise [Nanoc::Errors::UnknownLayout] if the given layout does not
+    #   exist
+    #
+    # @raise [Nanoc::Errors::CannotDetermineFilter] if there is no layout
+    #   rule for the given layout
+    #
+    # @raise [Nanoc::Errors::UnknownFilter] if the layout rule for the given
+    #   layout specifies an unknown filter
+    #
+    # @return [String, nil] The rendered partial, or nil if this method was
+    #   invoked with a block
+    def render(identifier, other_assigns={}, &block)
+      # Find layout
+      layout = @site.layouts.find { |l| l.identifier == identifier.cleaned_identifier }
+      raise Nanoc::Errors::UnknownLayout.new(identifier.cleaned_identifier) if layout.nil?
+
+      # Visit
+      Nanoc::NotificationCenter.post(:visit_started, layout)
+      Nanoc::NotificationCenter.post(:visit_ended,   layout)
+
+      # Capture content, if any
+      captured_content = block_given? ? capture(&block) : nil
+
+      # Get assigns
+      assigns = {
+        :content    => captured_content,
+        :item       => @item,
+        :item_rep   => @item_rep,
+        :items      => @items,
+        :layout     => layout,
+        :layouts    => @layouts,
+        :config     => @config,
+        :site       => @site
+      }.merge(other_assigns)
+
+      # Get filter name
+      filter_name, filter_args = @site.compiler.rules_collection.filter_for_layout(layout)
+      raise Nanoc::Errors::CannotDetermineFilter.new(layout.identifier) if filter_name.nil?
+
+      # Get filter class
+      filter_class = Nanoc::Filter.named(filter_name)
+      raise Nanoc::Errors::UnknownFilter.new(filter_name) if filter_class.nil?
+
+      # Create filter
+      filter = filter_class.new(assigns)
+
+      begin
+        # Notify start
+        Nanoc::NotificationCenter.post(:processing_started, layout)
+
+        # Layout
+        result = filter.run(layout.raw_content, filter_args)
+
+        # Append to erbout if we have a block
+        if block_given?
+          # Append result and return nothing
+          erbout = eval('_erbout', block.binding)
+          erbout << result
+          ''
+        else
+          # Return result
+          result
+        end
+      ensure
+        # Notify end
+        Nanoc::NotificationCenter.post(:processing_ended, layout)
+      end
+    end
+
+  end
+
+end