nanoc-toolbox 0.0.2 → 0.0.3

data/.gitignore

@@ -7,3 +7,4 @@ pkg/*
 .yardoc
 rdoc
 coverage
+doc

data/CHANGELOG.md

@@ -2,11 +2,20 @@
 
 ## developement
 
+## Release 0.0.3
+
+* NEW: 		Gravatar Helper
+* CHANGED:	Better Yardoc documentation
+* NEW:		RSpec tests
+* NEW:		HTML Tag Helper
+* NEW:		HtlmTidy Filter
+
+## Release 0.0.2
+
 * NEW:      README, LICENSE and CHANGELOG files
 * FIXED:    Correct the gemspec hompage, and removed rubyforge reference
 * CHANGED:  Cleanup on the navigation helper
 * NEW:      Add Yardoc
-* NEW:      RSPEC Test framework
 
 ## Release 0.0.1
 

data/Gemfile.lock

@@ -1,17 +1,28 @@
 PATH
   remote: .
   specs:
-    nanoc-toolbox (0.0.1)
+    nanoc-toolbox (0.0.3)
       nanoc (>= 3.1.6)
+      nokogiri (>= 1.4.4)
 
 GEM
   remote: http://rubygems.org/
   specs:
     cri (1.0.1)
+    diff-lcs (1.1.2)
     nanoc (3.1.6)
       nanoc3 (>= 3.1.6)
     nanoc3 (3.1.6)
       cri (>= 1.0.0)
+    nokogiri (1.4.4)
+    rspec (2.4.0)
+      rspec-core (~> 2.4.0)
+      rspec-expectations (~> 2.4.0)
+      rspec-mocks (~> 2.4.0)
+    rspec-core (2.4.0)
+    rspec-expectations (2.4.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.4.0)
 
 PLATFORMS
   ruby
@@ -20,3 +31,5 @@ DEPENDENCIES
   bundler (>= 1.0.0)
   nanoc (>= 3.1.6)
   nanoc-toolbox!
+  nokogiri (>= 1.4.4)
+  rspec (>= 1.0.0)

data/README.md

@@ -1,19 +1,23 @@
 # nanoc-toolbox
 
+!!! THIS LIBRARY IS STILL UNDER DEVELOPMENT !!!
+
 ## Presentation
 
-The nanoc-toolbox is a collection of filters and helpers for the static site generator tool nanoc
+The nanoc-toolbox is a collection of filters and helpers for the static site generator tool nanoc.
 
 ## Features
 
 * Navigation Helper
+* Gravatar Helper
+* HtmlTag Helper
 
 ## Requirements
 
 * nanoc3
+* Nokogiri
 
-
-## Instalation
+## Installation
 
 To use the nanoc-toolbox, you have to start by installing the gem.
 
@@ -34,6 +38,7 @@ The following example shows a sample helpers_.rb file in the lib directory
 
     # Custom Helpers
     include Nanoc::Toolbox::Helpers::Navigation
+    include Nanoc::Toolbox::Helpers::Gravatar
 
 ## Acknowledgments
 

data/lib/nanoc/toolbox/filters/html_tidy.rb

@@ -0,0 +1,21 @@
+module Nanoc::Toolbox::Filters
+  # NANOC Filter for html output tidy
+  #
+  # @author Anouar ADLANI <anouar@adlani.com>
+  class HtmlTidy < Nanoc3::Filter
+    
+    identifier :html_tidy
+    
+    # Tidy the HTML output
+    # Runs the content through Nokogiry document parser, and request the html output, 
+    # which is tidied by default.
+    #
+    # @param [String] content The content to filter
+    # @param [String] params This method takes no options.
+    # @return [String] The filtered content
+    def run(content, params = {})
+      require 'nokogiri'
+      Nokogiri::HTML::Document.parse(content).to_html
+    end
+  end
+end

data/lib/nanoc/toolbox/filters.rb

@@ -0,0 +1,6 @@
+require 'nanoc/toolbox/filters/html_tidy'
+
+# This module will regroup all the filters for nanoc
+module Nanoc::Toolbox::Filters
+
+end

data/lib/nanoc/toolbox/helpers/gravatar.rb

@@ -0,0 +1,143 @@
+require 'nanoc/toolbox/helpers/html_tag'
+
+module Nanoc::Toolbox::Helpers
+
+  # NANOC Helper for the Gravatar avatars
+  #
+  # This module contains functions for generating URL or IMG tags to
+  # display the Gravatar linked to an address email, or the default gravatar
+  #
+  # @see http://en.gravatar.com/
+  #
+  # @author Anouar ADLANI <anouar@adlani.com>
+  module Gravatar    
+    include Nanoc::Toolbox::Helpers::HtmlTag
+
+    # Gravatar avatar image base URL
+    URL = { :http   => "http://gravatar.com/avatar/",
+            :https  => "https://secure.gratatar.com/avatar/" }
+
+    # Collection of allowed ratings
+    RATING = %w{g pg r x}
+
+    # Default Icon sets
+    ICONS = %w{none identicon monsterid wavatar 404}
+
+    # Size range available
+    SIZE = 1..512
+
+    # Available options that could be configure
+    HELPER_OPTION = [:ext, :secure]
+    GRAVATAR_OPTIONS = [:default_icon, :size, :rating]
+    AVAILABLE_OPTIONS = HELPER_OPTION + GRAVATAR_OPTIONS
+
+    # Default values set to the options
+    DEFAULT_VALUES = { :size => nil, :rating => nil, :ext => false, :secure => false }
+
+    # Generate the image tag to the gravatar of the supplied email
+    #
+    # @example
+    #   gravatar_image('anouar@adlani.com', :size => "100")
+    #   #=> <img src="http://gravatar.com/avatar/4d076af1db60b16e1ce080505baf821c?size=100" />
+    #
+    # @param  [String]  email - the email address of the gravatar account
+    # @param  options (see #build_options_parameters)
+    # @option options (see #build_options_parameters)
+    def gravatar_image(email, options={})
+      image_url = gravatar_url(email, options)
+      options.delete_if {|key, value| GRAVATAR_OPTIONS.include?(key) }
+      tag('img', options.merge(:src => image_url))
+    end
+
+
+    # Generate image URL
+    #
+    # @example
+    #   gravatar_url('anouar@adlani.com', :size => "512", :ext => true)
+    #   #=> "http://gravatar.com/avatar/4d076af1db60b16e1ce080505baf821c.jpg?size=512"
+    #
+    # @param  email   (see #gravatar_image)
+    # @param  options (see #build_options_parameters)
+    # @option options (see #build_options_parameters)
+    def gravatar_url(email, options={})
+      # Prepare the email
+      email = clean_email(email)
+
+      # Prepare the options
+      options = DEFAULT_VALUES.merge(options)
+      options = clean_options(options)
+
+      # Retreive the URL depending on the protocole and build it
+      protocole = options[:secure] ? :https : :http
+      host = URL[protocole]
+
+      # generate the image name and append a the extension if requested
+      file = hash_email(email)
+      file += '.jpg' if options[:ext]
+
+      # Build the query string
+      parameters = build_options_parameters(options)
+
+      "#{host}#{file}#{parameters}"
+    end
+
+    protected
+      # Filters, Validates and build the options parameters for the URL.
+      # It simply consists in returning the URL query string based on the options passed
+      # after validating the availability the correctness of the option
+      #
+      # @example
+      #   {:size => 225, :rating => 'g', :ext => false, :secure => false}
+      #   #=> "?size=225&rating=g"
+      #
+      # @param [Hash] options the options to pass to the gravatar URL
+      # @option options [String] default_icon
+      # @option options [String] size (nil) Size of the image, between 1 to 512
+      # @option options [String] rating (nil) The rating allowed, a value in g, pg, r or x
+      # @option options [Boolean] ext (false) Use or not a file extension
+      # @option options [Boolean] secure (false) Use or not https
+      def build_options_parameters(options={})
+        # Remove unecessary options
+        options.delete_if {|key, value| !GRAVATAR_OPTIONS.include?(key) }
+
+        # Return now if the options hash is empty after cleanup
+        return '' if options.empty?
+
+        # Build the parameters string
+        '?' + options.sort.map { |e|  e = e.join('=') if e.size == 2}.join('&')
+      end
+
+    private
+      # Generate email address hash
+      def hash_email(email)
+        require 'digest/md5'
+        Digest::MD5.hexdigest(email)
+      end
+
+      # @example
+      #   {:size => 225, :rating => 'g', :ext => false, :secure => false}
+      #   #=> "?size=225&rating=g"
+      def clean_options(options={})
+        # remove unsupported options
+        options.delete_if {|key, value| !AVAILABLE_OPTIONS.include?(key) }
+
+        # remove empty options
+        options.delete_if {|key, value| value.nil? || value.to_s.strip == '' }
+
+        # remove options with unsupported values
+        options.delete(:default_icon) unless ICONS.include?(options[:default_icon])
+        options.delete(:rating) unless RATING.include?(options[:rating])
+        options.delete(:size) unless SIZE.include?(options[:size].to_i)
+
+        # cleanned up options
+        options
+      end
+
+      # Clean up and validates email
+      def clean_email(email='')
+        raise ArgumentError.new('Invalid email') if email.empty? || email.index('@').nil? || email.index('@') == 0 || email.count('@') > 1 || email.size <= 6
+        email.strip
+      end
+
+  end
+end

data/lib/nanoc/toolbox/helpers/html_tag.rb

@@ -0,0 +1,47 @@
+module Nanoc::Toolbox::Helpers
+
+  # NANOC Helper for HTML Tags
+  #
+  # This module contains functions for generating simple tags with attribute
+  #
+  # @author Anouar ADLANI <anouar@adlani.com>
+  module HtmlTag
+    # Simple tag
+    #
+    # @example
+    #   tag("br")
+    #    # => <br />
+    #
+    #   tag("hr", class => "thin", true)
+    #    # => <br class="thin">
+    #
+    #   tag("input", :type => 'text')
+    #    # => <input type="text" />
+    #
+    def tag(name, options={}, open=false)
+      "<#{name}#{tag_options(options) if options}#{open ? ">" : " />"}"
+    end
+
+    # Content tag
+    #
+    # @example
+    #   content_tag(:p, "Hello world!")
+    #    # => <p>Hello world!</p>
+    #   content_tag(:div, content_tag(:p, "Hello world!"), :class => "strong")
+    #    # => <div class="strong"><p>Hello world!</p></div>
+    def content_tag(name, content, options={})
+      "<#{name}#{tag_options(options) if options}>#{content}</#{name}>"
+    end
+    
+    protected
+      def tag_options(options)
+        unless options.empty?
+          attributes = []
+          options.each do |key, value|
+            attributes << %(#{key}="#{value}")
+          end
+          ' ' + attributes.join(' ')
+        end
+      end
+  end
+end

data/lib/nanoc/toolbox/helpers/navigation.rb

@@ -1,101 +1,102 @@
-module Nanoc::Toolbox::Helpers
+require 'nanoc/toolbox/helpers/html_tag'
 
+module Nanoc::Toolbox::Helpers  
   # NANOC Helper for the Navigation related stuff.
+  #
   # This module contains functions for generating navigation menus for your
   # pages, like navigation menu, breadcrumbs or a table of content for a given Item
   #
   # @author Anouar ADLANI <anouar@adlani.com>
   module Navigation
+    include Nanoc3::Helpers::LinkTo
+    include Nanoc::Toolbox::Helpers::HtmlTag
 
-    # Generate a navigation menu for a given item. 
-    # The menu will be generated form the identifier of the desired root element. 
-    # The root itself will not be rendered. It generate the menu by parsing all 
+    # Generate a navigation menu for a given item.
+    # The menu will be generated form the identifier of the desired root element.
+    # The root itself will not be rendered. It generate the menu by parsing all
     # the descendent of the passed item.
-    # 
+    #
     # @param  [String]  identifier - the identifier string of the root element
-    # @param  [Hash]    params - The Optional parameters
-    # @option params [Interger] :depth (3) maximum depth of the rendered menu
-    # @option params [String] :collection_tag ('ol') collection englobing tag name
-    # @option params [String] :item_tag ('li') item englobing tag name
-    # 
+    # @param  [Hash]    options - The Optional parameters
+    # @option options [Interger] :depth (3) maximum depth of the rendered menu
+    # @option options [String] :collection_tag ('ol') collection englobing tag name
+    # @option options [String] :item_tag ('li') item englobing tag name
+    #
     # @return [String] The output ready to be displayed by the caller
-    def navigation_for(identifier, params={})
-      # Parse params or set to default values
-      params[:depth]            ||= 3
-      params[:collection_tag]   ||= 'ol'
-      params[:item_tag]         ||= 'li'
-    
-      # Decrease the depth level
-      params[:depth] -= 1
-    
+    def navigation_for(identifier, options={})
+      # Parse options or set to default values
+      options[:depth]            ||= 3
+      options[:collection_tag]   ||= 'ol'
+      options[:item_tag]         ||= 'li'
+
       # Get root item for which we need to draw the navigation
       root = @items.find { |i| i.identifier == identifier }
-    
+
       # Do not render if there is no child
       return nil unless root.children
-    
+
       # Find all sections, and render them
       sections = find_item_tree(root)
-      render_menu(sections, params)
+      render_menu(sections, options)
     end
-  
-  
+
+
     # Generate a Table of Content for a given item. The toc will be generated
     # form the item content. The parsing is done with Nokogiri through XPath.
-    # 
+    #
     # @param  [String]  item_rep - the representation of desired item
-    # @param  [Hash]    params - The Optional parameters
-    # @option params [Interger] :depth (3) maximum depth of the rendered menu
-    # @option params [String] :collection_tag ('ol') collection englobing tag name
-    # @option params [String] :item_tag ('li') item englobing tag name
-    # 
+    # @param  [Hash]    options - The Optional parameters
+    # @option options [Interger] :depth (3) maximum depth of the rendered menu
+    # @option options [String] :collection_tag ('ol') collection englobing tag name
+    # @option options [String] :item_tag ('li') item englobing tag name
+    #
     # @return [String] The output ready to be displayed by the caller
     #
     # @see http://nokogiri.org/
-    def toc_for(item_rep, params={})
+    def toc_for(item_rep, options={})
       require 'nokogiri'
-      
-      # Parse params or set to default values
-      params[:depth]            ||= 3
-      params[:collection_tag]   ||= 'ol'
-      params[:item_tag]         ||= 'li'
-      params[:path]             ||= 'div[@class="section"]'
-      
+
+      # Parse options or set to default values
+      options[:depth]            ||= 3
+      options[:collection_tag]   ||= 'ol'
+      options[:item_tag]         ||= 'li'
+      options[:path]             ||= 'div[@class="section"]'
+
       # Retreive the parsed content and init nokogiri
       compiled_content = item_rep.instance_eval { @content[:pre] }
       doc = Nokogiri::HTML(compiled_content)
       doc_root = doc.xpath('/html/body').first
-      
+
       # Find all sections, and render them
-      sections = find_toc_sections(doc_root, "#{params[:path]}", 2)
-      render_menu(sections, params)
+      sections = find_toc_sections(doc_root, options[:path])
+      render_menu(sections, options)
     end
-  
-  
-    # Generate a Breadcrumb for a given item. The breadcrumbs, is starting with 
-    # the root item and ending with the item itself. 
+
+
+    # Generate a Breadcrumb for a given item. The breadcrumbs, is starting with
+    # the root item and ending with the item itself.
     #
     # Requires the Helper: Nanoc3::Helpers::Breadcrumbs
-    # 
+    #
     # @param  [String]  identifier - the identifier string of element
-    # @param  [Hash]    params - The Optional parameters
-    # @option params [String] :collection_tag ('ol') collection englobing tag name
-    # @option params [String] :item_tag ('li') item englobing tag name
-    # 
+    # @param  [Hash]    options - The Optional parameters
+    # @option options [String] :collection_tag ('ol') collection englobing tag name
+    # @option options [String] :item_tag ('li') item englobing tag name
+    #
     # @return [String] The output ready to be displayed by the caller
     #
     # @see Nanoc3::Helpers::Breadcrumbs#breadcrumbs_for_identifier
-    def breadcrumb_for(identifier, params={})
-    
-      # Parse params or set to default values
-      params[:collection_tag]   ||= 'ul'
-      params[:item_tag]         ||= 'li'
-    
+    def breadcrumb_for(identifier, options={})
+
+      # Parse options or set to default values
+      options[:collection_tag]   ||= 'ul'
+      options[:item_tag]         ||= 'li'
+
       # Retreive the breadcrumbs trail and format them
       sections = find_breadcrumbs_trail(identifier)
-      render_menu(sections, params)
+      render_menu(sections, options)
     end
-  
+
     # Render a Hash to a HTML List by default
     #
     # Hash structure should be construct like this:
@@ -120,86 +121,81 @@ module Nanoc::Toolbox::Helpers
     #   </ul>
     #
     # @param  [Array]  items - The array of links that need to be rendered
-    # @param  [Hash]    params - The Optional parameters
-    # @option params [String] :collection_tag ('ol') collection englobing tag name
-    # @option params [String] :item_tag ('li') item englobing tag name
-    # 
+    # @param  [Hash]    options - The Optional parameters
+    # @option options [String] :collection_tag ('ol') collection englobing tag name
+    # @option options [String] :item_tag ('li') item englobing tag name
+    #
     # @return [String] The output ready to be displayed by the caller
-    def render_menu(items, params={})
+    def render_menu(items, options={})
+
+      # Parse options or set to default values
+      options[:depth]            ||= 3
+      options[:collection_tag]   ||= 'ol'
+      options[:item_tag]         ||= 'li'
 
-      # Parse params or set to default values
-      params[:depth]            ||= 3
-      params[:collection_tag]   ||= 'ol'
-      params[:item_tag]         ||= 'li'
-    
       # Decrease the depth level
-      params[:depth] -= 1
-    
+      options[:depth] -= 1
+
       rendered_menu = items.map do |item|
-        
+
         # Render only if there is depth left
-        if params[:depth].to_i  >= 0 && item[:subsections]
-          output = render_menu(item[:subsections], params) 
-          params[:depth] += 1 # Increase the depth level after the call of navigation_for
+        if options[:depth].to_i  > 0 && item[:subsections]
+          output = render_menu(item[:subsections], options)
+          options[:depth] += 1 # Increase the depth level after the call of navigation_for
         end
         output ||= ""
-        content_tag(params[:item_tag], link_to(item[:title], item[:link]) + output)
-        
+        content_tag(options[:item_tag], link_to(item[:title], item[:link]) + output)
+
       end.join()
-      
-      content_tag(params[:collection_tag], rendered_menu)
+
+      content_tag(options[:collection_tag], rendered_menu) unless rendered_menu.empty?
     end
-  
+
     private
 
-      # Really basic Helper Method that wrap a content within an HTML Tag
-      def content_tag(name, content="", &block)
-        "<#{name}>#{content}</#{name}>"
-      end
-    
-      # Recursive method that extract from an XPath pattern the document structure 
-      # and return the "permalinks" to each sections in an Array of Hash that 
-      # could be used by the rendering method. The structure is deducted by the 
+      # Recursive method that extract from an XPath pattern the document structure
+      # and return the "permalinks" to each sections in an Array of Hash that
+      # could be used by the rendering method. The structure is deducted by the
       # H1-6 header within the html element defined by the XPATH
       def find_toc_sections(section, section_xpath, title_level=1)
         return {} unless section.xpath(section_xpath)
-      
-        # For each section found call the find_toc_sections on it with an 
+
+        # For each section found call the find_toc_sections on it with an
         # increased header level (ex: h1 => h2) and then generate the hash res
         sections = section.xpath(section_xpath).map do |subsection|
           header = subsection.xpath("h#{title_level}").first
           sub_id = subsection['id']
           sub_title = header.inner_html if header
           subsections = {}
-          
-          
+
+
           if subsection.xpath("#{section_xpath}") && title_level <= 6
             subsections = find_toc_sections(subsection, "#{section_xpath}", title_level+1)
           end
           { :title => sub_title, :link => '#' + sub_id, :subsections =>  subsections }
         end
       end
-    
-      # Recursive method that extract from an XPath pattern the document structure 
-      # and return the "permalinks" in a Array of Hash that could be used by the 
+
+      # Recursive method that extract from an XPath pattern the document structure
+      # and return the "permalinks" in a Array of Hash that could be used by the
       # rendering method
       def find_item_tree(root)
         return nil unless root.children
-      
+
         # For each child call the find_item_tree on it and then generate the hash
         sections = root.children.map do |child|
-          subsections = find_item_tree(child) 
+          subsections = find_item_tree(child)
 
-          { :title        => (child[:title] || child.identifier), 
+          { :title        => (child[:title] || child.identifier),
             :link         => relative_path_to(child),
             :subsections  => subsections }
         end
       end
-      
-      
-      def find_breadcrumbs_trail(root)      
+
+
+      def find_breadcrumbs_trail(root)
         sections = breadcrumbs_for_identifier(root).map do |child|
-          { :title        => (child[:title] || child.identifier), 
+          { :title        => (child[:title] || child.identifier),
             :link         => relative_path_to(child),
             :subsections  => nil }
         end