Module: Nanoc3::Helpers::LinkTo

Includes:
HTMLEscape
Included in:
Nanoc3::Filters::RelativizePaths
Defined in:
lib/nanoc3/helpers/link_to.rb

Overview

Contains functions for linking to items and item representations.

Instance Method Summary

Methods included from HTMLEscape

#html_escape

Instance Method Details

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 Nanoc3::Helpers::HTMLEscape#html_escape.

Examples:

Linking to a path

link_to('Blog', '/blog/')
# => '<a href="/blog/">Blog</a>'

Linking to an item

about = @items.find { |i| i.identifier == '/about/' }
link_to('About Me', about)
# => '<a href="/about.html">About Me</a>'

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>'

Linking with custom attributes

link_to('Blog', '/blog/', :title => 'My super cool blog')
# => '<a title="My super cool blog" href="/blog/">Blog</a>'

Parameters:

  • (String) text —

    The visible link text

  • (String, Nanoc3::Item, Nanoc3::ItemRep) target —

    The path/URL, item or item representation that should be linked to

  • (Hash) attributes (defaults to: {}) —

    A hash containing HTML attributes (e.g. rel, title, …) that will be added to the link.

Returns:



48
49
50
51
52
53
54
55
56
57
58
59
 
# File 'lib/nanoc3/helpers/link_to.rb', line 48

def link_to(text, target, attributes={})
  # Find path
  path = target.is_a?(String) ? target : target.path

  # 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

- (String) link_to_unless_current(text, target, attributes = {})

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.

Examples:

Linking to a different page

link_to_unless_current('Blog', '/blog/')
# => '<a href="/blog/">Blog</a>'

Linking to the same page

link_to_unless_current('This Item', @item)
# => '<span class="active" title="You\'re here.">This Item</span>'

Parameters:

  • (String) text —

    The visible link text

  • (String, Nanoc3::Item, Nanoc3::ItemRep) target —

    The path/URL, item or item representation that should be linked to

  • (Hash) attributes (defaults to: {}) —

    A hash containing HTML attributes (e.g. rel, title, …) that will be added to the link.

Returns:



85
86
87
88
89
90
91
92
93
94
95
 
# File 'lib/nanoc3/helpers/link_to.rb', line 85

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

- (String) relative_path_to(target)

Returns the relative path from the current item to the given path or item representation. The returned path will not be HTML-escaped.

Examples:

# if the current item's path is /foo/bar/
relative_path_to('/foo/qux/')
# => '../qux/'

Parameters:

Returns:

  • (String) —

    The relative path to the target



111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
 
# File 'lib/nanoc3/helpers/link_to.rb', line 111

def relative_path_to(target)
  require 'pathname'

  # Find path
  path = target.is_a?(String) ? target : target.path

  # Get source and destination paths
  dst_path   = Pathname.new(path)
  src_path   = Pathname.new(@item_rep.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