nanoc2 2.2.3

data/lib/nanoc2/helpers/capturing.rb

@@ -0,0 +1,63 @@
+module Nanoc2::Helpers
+
+  # Nanoc2::Helpers::Capturing provides a content_for method, which allows
+  # content to be "captured" on one page and reused elsewhere.
+  #
+  # = Example
+  #
+  # For example, suppose you want the sidebar of your site to contain a short
+  # summary of the page. 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 page, but that’s not very pretty. Instead,
+  # you write the summary on the page itself, but capture it, and print it in
+  # the sidebar layout.
+  #
+  # Captured content becomes part of the page. For example, a sidebar layout
+  # could look like this:
+  #
+  #   <div id="sidebar">
+  #     <h3>Summary</h3>
+  #     <%= @page.content_for_summary || '(no summary)' %>
+  #   </div>
+  #
+  # To put something inside that content_for_summary variable, capture it
+  # using the content_for function. In the about page, for example:
+  #
+  #   <% content_for :summary do %>
+  #     <p>On this page, nanoc is introduced, blah blah.</p>
+  #   <% end %>
+  #
+  # When the site is compiled, the sidebar of the about page will say “On
+  # this page, the purpose of nanoc is described, blah blah blah,” as
+  # expected.
+  #
+  # To activate this helper, +include+ it, like this:
+  #
+  #   include Nanoc2::Helpers::Capturing
+  module Capturing
+
+    # Captures the content inside the block into a page attribute named
+    # "content_for_" followed by the given name. The content of the block
+    # itself will not be outputted.
+    def content_for(name, &block)
+      eval("@page[:content_for_#{name.to_s}] = capture(&block)")
+    end
+
+  private
+
+    def capture(*args, &block)
+      buffer = eval('_erbout', block.binding)
+
+      pos = buffer.length
+      block.call(*args)
+
+      data = buffer[pos..-1]
+
+      buffer[pos..-1] = ''
+
+      data
+    end
+
+  end
+
+end

data/lib/nanoc2/helpers/filtering.rb

@@ -0,0 +1,54 @@
+module Nanoc2::Helpers
+
+  # Nanoc2::Helpers::Filtering provides a filter method, which allows parts of
+  # a page to be filtered.
+  #
+  # For example, the following piece of code only runs the "rubypants" filter
+  # on the second paragraph:
+  #
+  #   <p>Lorem ipsum dolor sit amet...</p>
+  #   <% filter :rubypants do %>
+  #     <p>Consectetur adipisicing elit...</p>
+  #   <% end %>
+  #
+  # This helper likely only works with ERB (and perhaps Erubis).
+  #
+  # To activate this helper, +include+ it, like this:
+  #
+  #   include Nanoc2::Helpers::Filtering
+  module Filtering
+
+    # Filters the content in the given block and outputs it.
+    def filter(filter_name, &block)
+      # Capture block
+      data = capture(&block)
+
+      # Find filter
+      filter = Nanoc2::Filter.named(filter_name).new(@_obj_rep)
+
+      # Filter captured data
+      filtered_data = filter.run(data)
+
+      # Append filtered data to buffer
+      buffer = eval('_erbout', block.binding)
+      buffer << filtered_data
+    end
+
+  private
+
+    def capture(*args, &block)
+      buffer = eval('_erbout', block.binding)
+
+      pos = buffer.length
+      block.call(*args)
+
+      data = buffer[pos..-1]
+
+      buffer[pos..-1] = ''
+
+      data
+    end
+
+  end
+
+end

data/lib/nanoc2/helpers/html_escape.rb

@@ -0,0 +1,25 @@
+module Nanoc2::Helpers
+
+  # Nanoc2::Helpers::HTMLEscape contains functionality for HTML-escaping
+  # strings.
+  #
+  # This helper is activated automatically.
+  module HTMLEscape
+
+    # Returns the HTML-escaped representation of the given string. Only &, <,
+    # > and " are escaped.
+    def html_escape(string)
+      string.gsub('&', '&amp;').
+             gsub('<', '&lt;').
+             gsub('>', '&gt;').
+             gsub('"', '&quot;')
+    end
+
+    alias h html_escape
+
+  end
+
+end
+
+# Include by default
+include Nanoc2::Helpers::HTMLEscape

data/lib/nanoc2/helpers/link_to.rb

@@ -0,0 +1,113 @@
+module Nanoc2::Helpers
+
+  # Nanoc2::Helpers::LinkTo contains functions for linking to pages.
+  #
+  # To activate this helper, +include+ it, like this:
+  #
+  #   include Nanoc2::Helpers::LinkTo
+  module LinkTo
+
+    require 'nanoc2/helpers/html_escape'
+    include Nanoc2::Helpers::HTMLEscape
+
+    # Creates a HTML link to the given path or page/asset representation, and
+    # with the given text.
+    #
+    # +path_or_rep+:: the URL or path (a String) that should be linked to, or
+    #                 the page or asset representation that should be linked
+    #                 to.
+    #
+    # +text+:: the visible link text.
+    #
+    # +attributes+:: a hash containing HTML attributes that will be added to
+    #                the link.
+    #
+    # Examples:
+    #
+    #   link_to('Blog', '/blog/')
+    #   # => '<a href="/blog/">Blog</a>'
+    #
+    #   page_rep = @pages.find { |p| p.page_id == 'special' }.reps(:default)
+    #   link_to('Special Page', page_rep)
+    #   # => '<a href="/special_page/">Special Page</a>'
+    #
+    #   link_to('Blog', '/blog/', :title => 'My super cool blog')
+    #   # => '<a href="/blog/" title="My super cool blog">Blog</a>
+    def link_to(text, path_or_rep, attributes={})
+      # Find path
+      path = path_or_rep.is_a?(String) ? path_or_rep : path_or_rep.path
+
+      # Join attributes
+      attributes = attributes.inject('') do |memo, (key, value)|
+        memo + key.to_s + '="' + h(value) + '" '
+      end
+
+      # Create link
+      "<a #{attributes}href=\"#{path}\">#{text}</a>"
+    end
+
+    # Creates a HTML link using link_to, except when the linked page is the
+    # current one. In this case, a span element with class "active" and with
+    # the given text will be returned.
+    #
+    # Examples:
+    #
+    #   link_to_unless_current('Blog', '/blog/')
+    #   # => '<a href="/blog/">Blog</a>'
+    #
+    #   link_to_unless_current('This Page', @page_rep)
+    #   # => '<span class="active">This Page</span>'
+    def link_to_unless_current(text, path_or_rep, attributes={})
+      # Find path
+      path = path_or_rep.is_a?(String) ? path_or_rep : path_or_rep.path
+
+      if @page_rep and @page_rep.path == path
+        # Create message
+        "<span class=\"active\" title=\"You're here.\">#{text}</span>"
+      else
+        link_to(text, path_or_rep, attributes)
+      end
+    end
+
+    # Returns the relative path from the current page to the given path or
+    # page/asset representation.
+    #
+    # +path_or_rep+:: the URL or path (a String) to where the relative should
+    #                 point, or the page or asset representation to which the
+    #                 relative should point.
+    #
+    # Example:
+    #
+    #   # if the current item's path is /foo/bar/
+    #   relative_path('/foo/qux/')
+    #   # => '../qux/'
+    def relative_path_to(path_or_rep)
+      require 'pathname'
+
+      # Find path
+      path = path_or_rep.is_a?(String) ? path_or_rep : path_or_rep.path
+
+      # Get source and destination paths
+      dst_path   = Pathname.new(path)
+      src_path   = Pathname.new((defined?(@page) ? @page : @asset).path)
+
+      # Calculate elative 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/nanoc2/helpers/render.rb

@@ -0,0 +1,49 @@
+module Nanoc2::Helpers
+
+  # Nanoc2::Helpers::Render provides functionality for rendering layouts as
+  # partials.
+  #
+  # This helper is activated automatically.
+  module Render
+
+    # Returns a string containing the rendered given layout.
+    #
+    # +name_or_path+:: the name or the path of the layout that should be
+    #                  rendered.
+    #
+    # +other_assigns+:: a hash containing assigns that will be made available
+    #                   as instance variables.
+    #
+    # Example 1: a layout 'head' with content "HEAD" and a layout 'foot' with
+    # content "FOOT":
+    #
+    #   <%= render 'head' %> - MIDDLE - <%= render 'foot' %>
+    #   # => "HEAD - MIDDLE - FOOT" 
+    #
+    # Example 2: a layout named 'head' with content "<h1><%= @title %></h1>":
+    #
+    #   <%= render 'head', :title => 'Foo' %>
+    #   # => "<h1>Foo</h1>"
+    def render(name_or_path, other_assigns={})
+      # Find layout
+      layout = @_obj.site.layouts.find { |l| l.path == name_or_path.cleaned_path }
+      raise Nanoc2::Errors::UnknownLayoutError.new(name_or_path.cleaned_path) if layout.nil?
+
+      # Find filter
+      klass = layout.filter_class
+      raise Nanoc2::Errors::CannotDetermineFilterError.new(layout.path) if klass.nil?
+      filter = klass.new(@_obj_rep, other_assigns)
+
+      # Layout
+      @_obj.site.compiler.stack.push(layout)
+      result = filter.run(layout.content)
+      @_obj.site.compiler.stack.pop
+      result
+    end
+
+  end
+
+end
+
+# Include by default
+include Nanoc2::Helpers::Render

data/lib/nanoc2/helpers/tagging.rb

@@ -0,0 +1,56 @@
+module Nanoc2::Helpers
+
+  # Nanoc2::Helpers::Tagging provides some support for managing tags added to
+  # pages. To add tags to pages, set the +tags+ page attribute to an array of
+  # tags that should be applied to the page. For example:
+  #
+  #   tags: [ 'foo', 'bar', 'baz' ]
+  #
+  # To activate this helper, +include+ it, like this:
+  #
+  #   include Nanoc2::Helpers::Tagging
+  module Tagging
+
+    # Returns a formatted list of tags for the given page as a string. Several
+    # parameters allow customization:
+    #
+    # :base_url:: The URL to which the tag will be appended to construct the
+    #             link URL. This URL must have a trailing slash. Defaults to
+    #             "http://technorati.com/tag/".
+    #
+    # :none_text:: The text to display when the page has no tags. Defaults to
+    #              "(none)".
+    #
+    # :separator:: The separator to put between tags. Defaults to ", ".
+    def tags_for(page, params={})
+      base_url  = params[:base_url]  || 'http://technorati.com/tag/'
+      none_text = params[:none_text] || '(none)'
+      separator = params[:separator] || ', '
+
+      if page.tags.nil? or page.tags.empty?
+        none_text
+      else
+        page.tags.collect { |tag| link_for_tag(tag, base_url) }.join(separator)
+      end
+    end
+
+    # Returns all pages with the given tag.
+    def pages_with_tag(tag)
+      @pages.select { |p| (p.tags || []).include?(tag) }
+    end
+
+    # Returns a link to to the specified tag. The link is marked up using the
+    # rel-tag microformat.
+    #
+    # +tag+:: The name of the tag, which should consist of letters and numbers
+    #         (no spaces, slashes, or other special characters).
+    #
+    # +base_url+:: The URL to which the tag will be appended to construct the
+    #              link URL. This URL must have a trailing slash.
+    def link_for_tag(tag, base_url)
+      %[<a href="#{base_url}#{tag}" rel="tag">#{tag}</a>]
+    end
+
+  end
+
+end

data/lib/nanoc2/helpers/text.rb

@@ -0,0 +1,38 @@
+module Nanoc2::Helpers
+
+  # Nanoc2::Helpers::Text contains several useful text-related helper functions.
+  module Text
+
+    # Returns an excerpt for the given string. HTML tags are ignored, so if
+    # you don't want them to turn up, they should be stripped from the string
+    # before passing it to the excerpt function.
+    #
+    # +params+ is a hash where the following keys can be set:
+    #
+    # +length+:: The maximum number of characters this excerpt can contain,
+    #            including the omission. Defaults to 25.
+    #
+    # +omission+:: The string to append to the excerpt when the excerpt is
+    #              shorter than the original string. Defaults to '...' (but in
+    #              HTML, you may want to use something more fancy, like
+    #              '…').
+    def excerptize(string, params={})
+      # Initialize params
+      params[:length]   ||= 25
+      params[:omission] ||= '...'
+
+      # Get excerpt
+      length = params[:length] - params[:omission].length
+      length = 0 if length < 0
+      (string.length > params[:length] ? string[0...length] + params[:omission] : string)
+    end
+
+    # Strips all HTML tags out of the given string.
+    def strip_html(string)
+      # FIXME will need something more sophisticated than this, because it sucks
+      string.gsub(/<[^>]*(>+|\s*\z)/m, '').strip
+    end
+
+  end
+
+end

data/lib/nanoc2/helpers/xml_sitemap.rb

@@ -0,0 +1,63 @@
+module Nanoc2::Helpers
+
+  # Nanoc2::Helpers::XMLSitemap contains functionality for building XML
+  # sitemaps that will be crawled by search engines. See the Sitemaps protocol
+  # web site, http://www.sitemaps.org, for details.
+  #
+  # To activate this helper, +include+ it, like this:
+  #
+  #   include Nanoc2::Helpers::XMLSitemap
+  module XMLSitemap
+
+    # Returns the XML sitemap as a string.
+    #
+    # The following attributes can optionally be set on pages to change the
+    # behaviour of the sitemap:
+    #
+    # * 'changefreq', containing the estimated change frequency as defined by
+    #   the Sitemaps protocol.
+    #
+    # * 'priority', containing the page's priority, ranging from 0.0 to 1.0,
+    #   as defined by the Sitemaps protocol.
+    #
+    # The sitemap will also include dates on which the pages were updated.
+    # These are generated automatically; the way this happens depends on the
+    # used data source (the filesystem data source checks the file mtimes, for
+    # instance).
+    #
+    # The sitemap page will need to have the following attributes:
+    #
+    # * 'base_url', containing the URL to the site, without trailing slash.
+    #   For example, if the site is at "http://example.com/", the base_url
+    #   would be "http://example.com". It is probably a good idea to define
+    #   this in the page defaults, i.e. the 'meta.yaml' file (at least if the
+    #   filesystem data source is being used, which is probably the case).
+    def xml_sitemap
+      require 'builder'
+
+      # Create builder
+      buffer = ''
+      xml = Builder::XmlMarkup.new(:target => buffer, :indent => 2)
+
+      # Build sitemap
+      xml.instruct!
+      xml.urlset(:xmlns => 'http://www.google.com/schemas/sitemap/0.84') do
+        # Add page
+        @pages.reject { |p| p.is_hidden || p.skip_output }.each do |page|
+          xml.url do
+            loc = (@site.config[:base_url] || @page.base_url) + page.path
+            xml.loc         loc
+            xml.lastmod     page.mtime.to_iso8601_date unless page.mtime.nil?
+            xml.changefreq  page.changefreq unless page.changefreq.nil?
+            xml.priority    page.priority unless page.priority.nil?
+          end
+        end
+      end
+
+      # Return sitemap
+      buffer
+    end
+
+  end
+
+end