Module: Nanoc::Toolbox::Helpers::TaggingExtra

Includes:
Helpers::Blogging
Defined in:
lib/nanoc/toolbox/helpers/tagging_extra.rb

Overview

NANOC Helper for added tagging functions

This module contains functions for …

Instance Method Summary collapse

Instance Method Details

#count_tags(items = nil) ⇒ Hash

Count the tags in a given collection of items. By default, the method counts tags in all the site items. The result is an hash such as: { tag => count }.

Parameters:

  • items (Array<Nanoc::Item>) (defaults to: nil)

Returns:

  • (Hash)

    Hash indexed by tag name with the occurences as value


50
51
52
53
54
# File 'lib/nanoc/toolbox/helpers/tagging_extra.rb', line 50

def count_tags(items=nil)
  items ||= @items
  tags = items.map { |i| i[:tags] }.flatten.delete_if{|t| t.nil?}
  tags.inject(Hash.new(0)) {|h,i| h[i] += 1; h }
end

#create_tag_pages(items = nil, options = {}) ⇒ Object

Creates in-memory tag pages from tags of the passed items or form all items

Parameters:

  • item (Array<Item>)

    the item from which to extract tags

  • options (Item) (defaults to: {})

    the options for the item to be created

Options Hash (options):

  • :tag_pattern (String) — default: "%%tag%%"

    The pattern to be replace by the tag name

  • :title (String) — default: "options[:tag_pattern]"

    The text that will be in the link

  • :identifier (String) — default: "/tags/option[:tag_pattern]"

    The item identifer

  • :template (String) — default: "tag"

    The template/layout to use to render the tag


120
121
122
123
124
125
126
127
128
129
130
131
132
133
# File 'lib/nanoc/toolbox/helpers/tagging_extra.rb', line 120

def create_tag_pages(items=nil, options={})
  options[:tag_pattern]     ||= "%%tag%%"
  options[:title]           ||= options[:tag_pattern]
  options[:identifier]      ||= "/tags/#{options[:tag_pattern]}/"
  options[:template]        ||= "tag"

  tag_set(items).each do |tagname|
    raw_content = "<%= render('#{options[:template]}', :tag => '#{tagname}') %>"
    attributes  = { :title => options[:title].gsub(options[:tag_pattern], tagname) }
    identifier  = options[:identifier].gsub(options[:tag_pattern], tagname)

    @items << Nanoc::Item.new(raw_content, attributes, identifier, :binary => false)
  end
end

#has_tag?(item, tag) ⇒ Boolean

Return true if an item has a specified tag

Parameters:

  • item (Nanoc::Item)
  • tag (String)

Returns:

  • (Boolean)

    true if the item contains the specified tag


27
28
29
30
# File 'lib/nanoc/toolbox/helpers/tagging_extra.rb', line 27

def has_tag?(item, tag)
  return false if item[:tags].nil?
  item[:tags].include? tag
end

#items_with_tag(tag, items = nil) ⇒ Object

Finds all the items having a specified tag. By default the method search in all the site items. Alternatively, an item collection can be passed as second (optional) parameter, to restrict the search in the collection.

Parameters:

  • items (Array<Nanoc::Item>) (defaults to: nil)
  • tag (String)
  • item (Nanoc::Item)

39
40
41
42
# File 'lib/nanoc/toolbox/helpers/tagging_extra.rb', line 39

def items_with_tag(tag, items=nil)
  items = sorted_articles if items.nil?
  items.select { |item| has_tag?( item, tag ) }
end

#rank_tags(n, items = nil) ⇒ Object

Sort the tags of an item collection (defaults to all site items) in 'n' classes of rank. The rank 0 corresponds to the most frequent tags. The rank 'n-1' to the least frequents. The result is a hash such as: { tag => rank }

Parameters:

  • n (Integer)

    number of rank

  • items (Array<Nanoc::Item>) (defaults to: nil)

Raises:

  • (ArgumentError)

63
64
65
66
67
68
69
70
71
72
73
# File 'lib/nanoc/toolbox/helpers/tagging_extra.rb', line 63

def rank_tags(n, items=nil)
  raise ArgumentError, 'the number of ranks should be > 1' if n < 2

  items = @items if items.nil?
  count = count_tags( items )
  min, max = count.values.minmax

  ranker = lambda { |num| n - 1 - (num - min) / (max - min) }

  Hash[count.map {|tag,value| [tag, ranker.call(value) ] }]
end

Returns an Array of links to tags in the item, optionally omits the given tags from the selection

Examples:

omited = ['strange_tag']
options = { :tag_pattern => "%%TAGNAME%%",
            :title       => "articles tagged with %%TAGNAME%%",
            :url_format  => "/tags/tag_%%TAGNAME%%.html"}
tag_links_for(item, omited, options) # => ['<a href="/tags/tag_a.html">articles tagged with a</a>', '<a href="/tags/tag_b.html">articles tagged with b</a>']

Parameters:

  • item (Item)

    the item from which to extract tags

  • omit_tags (Array<String>) (defaults to: [])

    tags that should be excluded

  • options (Item) (defaults to: {})

    the options for the links to be created

Options Hash (options):

  • :tag_pattern (String) — default: "%%tag%%"

    The pattern to be replace by the tag name

  • :title (String) — default: "options[:tag_pattern]"

    The text that will be in the link

  • :file_extension (String) — default: ".html"

    The file extension

  • :url_format (String) — default: "/tags/:tag_pattern:file_extension"

    The path pattern

Returns:

  • (Array<String>)

    An array of html links


94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
# File 'lib/nanoc/toolbox/helpers/tagging_extra.rb', line 94

def tag_links_for(item, omit_tags=[], options={})
  tags = []
  return tags unless item[:tags]

  options[:tag_pattern]     ||= "%%tag%%"
  options[:title]           ||= options[:tag_pattern]
  options[:file_extension]  ||= ".html"
  options[:url_format]      ||= "/tags/#{options[:tag_pattern]}#{options[:file_extension]}"

  tags = item[:tags] - omit_tags

  tags.map! do |tag|
      title = options[:title].gsub(options[:tag_pattern], tag.downcase)
      url = options[:url_format].gsub(options[:tag_pattern], tag.downcase)
      ('a', title, {:href => url})
  end
end

#tag_set(items = nil) ⇒ Array<String>

Returns all the tags present in a collection of items. The tags are only present once in the returned value. When called whithout parameters, all the site items are considered.

Parameters:

  • items (Array<Nanoc::Item>) (defaults to: nil)

Returns:

  • (Array<String>)

    An array of tags


17
18
19
20
# File 'lib/nanoc/toolbox/helpers/tagging_extra.rb', line 17

def tag_set(items=nil)
  items ||= @items
  items.map { |i| i[:tags] }.flatten.uniq.delete_if{|t| t.nil?}
end