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

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.

item or item representation that should be linked to

rel, title, …) that will be added to the link.

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:

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

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

Creates a HTML link using linkto, 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</em>to apply here as well.

item or item representation that should be linked to

rel, title, …) that will be added to the link.

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:

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

- (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.

item or item representation to which the relative path should be generated

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