Module: Nanoc::Helpers::LinkTo

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

  • (String)

    The link text



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

def link_to(text, target, attributes = {})
  # Find path
  path =
    case target
    when String
      target
    when Nanoc::ItemWithRepsView, Nanoc::ItemWithoutRepsView, Nanoc::ItemRepView
      raise "Cannot create a link to #{target.inspect} because this target is not outputted (its routing rule returns nil)" if target.path.nil?
      target.path
    else
      raise ArgumentError, "Cannot link to #{target.inspect} (expected a string or an item, not a #{target.class.name})"
    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">This Item</span>'

Parameters:

  • text (String)

    The visible link text

  • target (String, Nanoc::Int::Item, Nanoc::Int::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:

  • (String)

    The link text



90
91
92
93
94
95
96
97
98
99
100
# File 'lib/nanoc/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\">#{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:

  • target (String, Nanoc::Int::Item, Nanoc::Int::ItemRep)

    The path/URL, item or item representation to which the relative path should be generated

Returns:

  • (String)

    The relative path to the target



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
155
156
157
# File 'lib/nanoc/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
    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?('//', '\\\\')
    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).
  relative_path =
    if src_path.to_s[-1, 1] != '/'
      dst_path.relative_path_from(src_path.dirname).to_s
    else
      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