Module: Nanoc3::Helpers::LinkTo

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

Overview

Contains functions for linking to items and item representations.

Instance Method Summary collapse

Methods included from HTMLEscape

#html_escape

Methods included from Capturing

#capture, #content_for

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

  • text (String) —

    The visible link text

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

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

  • attributes (Hash) (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
60
61
62
63
64
 
# File 'lib/nanoc3/helpers/link_to.rb', line 48

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

#link_to_unless_current(text, target, attributes = {}) ⇒ String

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:

  • text (String) —

    The visible link text

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

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

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

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

Returns:



90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/nanoc3/helpers/link_to.rb', line 90

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

#relative_path_to(target) ⇒ String

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

Raises:

  • (RuntimeError) 


116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
 
# File 'lib/nanoc3/helpers/link_to.rb', line 116

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