Module: Nanoc::Helpers::LinkTo

Includes:
HTMLEscape
Included in:
Filters::RelativizePaths
Defined in:
lib/nanoc/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, Nanoc::Item, Nanoc::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:



46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
# File 'lib/nanoc/helpers/link_to.rb', line 46

def link_to(text, target, attributes = {})
  # Find path
  if target.is_a?(String)
    path = target
  else
    path = target.path
    raise "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.reduce('') do |memo, (key, value)|
    memo + key.to_s + '="' + h(value) + '" '
  end

  # Create link
  "<a #{attributes}href=\"#{h path}\">#{text}</a>"
end

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, Nanoc::Item, Nanoc::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:



88
89
90
91
92
93
94
95
96
97
98
# File 'lib/nanoc/helpers/link_to.rb', line 88

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



114
115
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
148
149
150
151
152
153
154
# File 'lib/nanoc/helpers/link_to.rb', line 114

def relative_path_to(target)
  require 'pathname'

  # Find path
  if target.is_a?(String)
    path = target
  else
    path = target.path
    if path.nil?
      raise "Cannot get the relative path to #{target.inspect} because this target is not outputted (its routing rule returns nil)"
    end
  end

  # Handle Windows network (UNC) paths
  if path.start_with?('//') || path.start_with?('\\\\')
    return path
  end

  # Get source and destination paths
  dst_path   = Pathname.new(path)
  if @item_rep.path.nil?
    raise "Cannot get the relative path to #{path} because the current item representation, #{@item_rep.inspect}, is not outputted (its routing rule returns nil)"
  end
  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