# Module: YARD::Server::DocServerHelper

Included in:
  Commands::DisplayObjectCommand, Commands::SearchCommand

Defined in:
  lib/yard/server/doc_server_helper.rb

## Overview

A module that is mixed into Templates::Template in order to customize certain template methods.

Since:

- 0.6.0

## Instance Method Summary collapse

- #abs_url(*path_components) ⇒ String

  The absolute path from any mounted base URI.

- #base_path(path) ⇒ String

  The base URI for a library with an extra `path` prefix.

- #mtime(file) ⇒ String

  A timestamp for a given file.

- #mtime_url(file) ⇒ String

  A URL for a file with a timestamp.

- #router ⇒ Router

  Convenience method for accessing the router.

- #url_for(obj, anchor = nil, relative = false) ⇒ String

  Modifies Templates::Helpers::HtmlHelper#url_for to return a URL instead of a disk location.

- #url_for_file(filename, anchor = nil) ⇒ String

  Modifies Templates::Helpers::HtmlHelper#url_for_file to return a URL instead of a disk location.

- #url_for_frameset ⇒ String

  Returns the frames URL for the page.

- #url_for_index ⇒ String

  Returns the URL for the alphabetic index page.

- #url_for_list(type) ⇒ String

  Modifies Templates::Helpers::HtmlHelper#url_for_list to return a URL based on the list prefix instead of a HTML filename.

- #url_for_main ⇒ String

  Returns the main URL, first checking a readme and then linking to the index.

## Instance Method Details

### #abs_url(*path_components) ⇒ `String`

Returns the absolute path from any mounted base URI.

Parameters:

- path_components (`Array<String>`) —

  components of a URL

Returns:

- (`String`) —

  the absolute path from any mounted base URI.

Since:

- 0.6.0

    61
    62
    63

    # File 'lib/yard/server/doc_server_helper.rb', line 61

    def abs_url(*path_components)
      File.join(router.request.script_name, *path_components)
    end

### #base_path(path) ⇒ `String`

Returns the base URI for a library with an extra `path` prefix.

#### Examples:

#####

The base path for a library ‘foo’

    base_path('docs') # => 'docs/foo'

Parameters:

- path (`String`) —

  the path prefix for a base path URI

Returns:

- (`String`) —

  the base URI for a library with an extra `path` prefix

Since:

- 0.6.0

    69
    70
    71
    72

    # File 'lib/yard/server/doc_server_helper.rb', line 69

    def base_path(path)
      libname = router.request.version_supplied ? @library.to_s : @library.name
      path + (@single_library ? '' : "/#{libname}")
    end

### #mtime(file) ⇒ `String`

Returns a timestamp for a given file.

Returns:

- (`String`) —

  a timestamp for a given file

Since:

- 0.6.0

    78
    79
    80
    81

    # File 'lib/yard/server/doc_server_helper.rb', line 78

    def mtime(file)
      file = YARD::Server::Commands::StaticFileHelpers.find_file(@adapter, file)
      file ? File.mtime(file).to_i : nil
    end

### #mtime_url(file) ⇒ `String`

Returns a URL for a file with a timestamp.

Returns:

- (`String`) —

  a URL for a file with a timestamp

Since:

- 0.6.0

    84
    85
    86
    87
    88

    # File 'lib/yard/server/doc_server_helper.rb', line 84

    def mtime_url(file)
      url = url_for(file)
      time = mtime(file)
      url + (time ? "?#{time}" : "")
    end

### #router ⇒ `Router`

Returns convenience method for accessing the router.

Returns:

- (`Router`) —

  convenience method for accessing the router

Since:

- 0.6.0

    75

    # File 'lib/yard/server/doc_server_helper.rb', line 75

    def router; @adapter.router end

### #url_for(obj, anchor = nil, relative = false) ⇒ `String`

Modifies Templates::Helpers::HtmlHelper#url_for to return a URL instead of a disk location.

Parameters:

- obj (`String`, `CodeObjects::Base`) —

  the object (or object path) to link to

- anchor (`String`) (defaults to: `nil`) —

  the anchor to link to

- relative (`Boolean`) (defaults to: `false`) —

  use a relative or absolute link

Returns:

- (`String`) —

  the URL location of the object

Since:

- 0.6.0

    11
    12
    13
    14
    15
    16
    17
    18

    # File 'lib/yard/server/doc_server_helper.rb', line 11

    def url_for(obj, anchor = nil, relative = false) # rubocop:disable Lint/UnusedMethodArgument
      return '' if obj.nil?
      return url_for_index if obj == '_index.html'
      return abs_url(base_path(router.static_prefix), obj) if String === obj
      url = super(obj, anchor, false)
      return unless url
      abs_url(base_path(router.docs_prefix), url)
    end

### #url_for_file(filename, anchor = nil) ⇒ `String`

Modifies Templates::Helpers::HtmlHelper#url_for_file to return a URL instead of a disk location.

Parameters:

- filename (`String`, `CodeObjects::ExtraFileObject`) —

  the filename to link to

- anchor (`String`) (defaults to: `nil`) —

  optional anchor

Returns:

- (`String`) —

  the URL pointing to the file

Since:

- 0.6.0

    24
    25
    26
    27
    28
    29
    30
    31

    # File 'lib/yard/server/doc_server_helper.rb', line 24

    def url_for_file(filename, anchor = nil)
      if filename.is_a?(CodeObjects::ExtraFileObject)
        filename = filename.filename
      end
      fname = filename.sub(%r{^#{@library.source_path.to_s}/}, '')
      fname += "##{anchor}" if anchor && !anchor.empty?
      abs_url(base_path(router.docs_prefix), 'file', fname)
    end

### #url_for_frameset ⇒ `String`

Returns the frames URL for the page

Returns:

- (`String`) —

  the URL pointing to the frames page

Since:

- 0.6.0

    43
    44
    45

    # File 'lib/yard/server/doc_server_helper.rb', line 43

    def url_for_frameset
      options.file ? url_for_file(options.file) : url_for(object)
    end

### #url_for_index ⇒ `String`

Returns the URL for the alphabetic index page

Returns:

- (`String`) —

  the URL pointing to the first main page the user should see.

Since:

- 0.6.0

    55
    56
    57

    # File 'lib/yard/server/doc_server_helper.rb', line 55

    def url_for_index
      abs_url(base_path(router.docs_prefix), 'index')
    end

### #url_for_list(type) ⇒ `String`

Modifies Templates::Helpers::HtmlHelper#url_for_list to return a URL based on the list prefix instead of a HTML filename.

Parameters:

- type (`String`, `Symbol`) —

  the list type to generate a URL for

Returns:

- (`String`) —

  the URL pointing to the list

Since:

- 0.6.0

    37
    38
    39

    # File 'lib/yard/server/doc_server_helper.rb', line 37

    def url_for_list(type)
      abs_url(base_path(router.list_prefix), type.to_s)
    end

### #url_for_main ⇒ `String`

Returns the main URL, first checking a readme and then linking to the index

Returns:

- (`String`) —

  the URL pointing to the first main page the user should see.

Since:

- 0.6.0

    49
    50
    51

    # File 'lib/yard/server/doc_server_helper.rb', line 49

    def url_for_main
      options.readme ? url_for_file(options.readme) : url_for_index
    end