Module: Helper::Helper

Includes:
Linker
Defined in:
lib/helper/helper.rb

Overview

The Helper-methods in this module are globally used one and should not depend on the template you are using. You will find many html-helpers around here, that are inspired by rails.

Constant Summary

Constants included from Linker

Linker::DOCUMENTATION, Linker::EXTERNAL, Linker::FILE, Linker::HASH, Linker::MAIL

Markdown collapse

Instance Method Summary collapse

Methods included from Linker

#link_to, #path_to, #relative_link, #replace_links

Instance Method Details

#attributize(hash) ⇒ String

Takes a hash as input and returns a string, which can be included in a html tag.

Examples:

attributize :style => 'border: none;', :class => 'foo' #=> 'style="border: none;" class="foo"'

Parameters:

  • hash (Hash)

Returns:



224
225
226
 
# File 'lib/helper/helper.rb', line 224

def attributize(hash)
  hash.map{|k,v| "#{k}=\"#{v}\""}.join ' '
end

#code(source, opts = {}) ⇒ String

Removes intendation from the sources and generates a code-tag with all the required classes to make the javascript-syntax-highlighter work.

Examples:

code "  function() {}"
#=> <code class="brush:js first-line:1">function(){}</code>
code "  function() {}", :firstline => 15
#=> <code class="brush:js first-line:15">function(){}</code>

Parameters:

  • source (String)
  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • :firstline (Numeric) — default: 1 —

    The line-numeration will start with that number

  • :class (String) — default: "block" —

    A optional css-class which can be added

Returns:

  • (String) —

    the html-code-element

See Also:



110
111
112
113
114
115
116
117
118
119
120
121
122
123
 
# File 'lib/helper/helper.rb', line 110

def code(source, opts = {})

  # defaults
  opts[:firstline] ||=  1
  opts[:class]     ||= "block"
      
  # find minimal intendation
  intendation = source.lines.map {|line| line.match(/(^\s+)/) && line.match(/(^\s+)/).captures.first.size || 0 }.min
  
  # @todo there has to be a better way for that      
  tag :code, h(source.lines.map { 
    |line| line[intendation .. line.size] 
  }.join("")), :class => "#{opts[:class]} brush:js first-line:#{opts[:firstline]}" 
end

#h(to_escape) ⇒ String

Escapes any html-elements in the given string

Parameters:

Returns:

  • (String) —

    the escaped string



129
130
131
 
# File 'lib/helper/helper.rb', line 129

def h(to_escape)
  CGI.escapeHTML(to_escape)
end

#render_tokens(opts = {}) ⇒ Object

To visually group the tokens you can specify an area. All tokens for one area (‘:sidebar` in this example) will be collected and can be rendered in the view-templates with the render_tokens helper-method. 

render_tokens :of => @code_object, :in => :sidebar

While registering a new token you can use any symbol for ‘area`. But your tokens may not appear in the rendered html-documentation, unless you explicitly call `render_tokens` for each area.

The default-templates make use of the following areas:

  • :notification

  • :body

  • :sidebar

  • :footnote

If you don’t want your token to be rendered at all, you can use ‘:none` as value for `area`.

register :your_token, :area => :none

Examples:

render tokens of notification-area

render_tokens :of => code_object, :in => :notification

exclude ‘@deprecated`-Tokens from output

render_tokens :of => code_object, :in => :body, :without => [:deprecated]

use special default-template

render_tokens :of => code_object, :in => :sidebar, :template => 'sidebar'

Parameters:

  • opts (Hash) (defaults to: {})

Options Hash (opts):

  • :of (CodeObject::Base) —

    The object, which contains the tokens, to be rendered

  • :area (Symbol) —

    The area to filter the tokens for

  • :without (Array<Symbol>, nil) —

    Tokennames to be excluded from the output

  • :template (Symbol, String, nil) —

    If you wan’t to overwrite the default template you can use this option. (Note: templates, specified at token-registration have higher precedence, than this option)



190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
 
# File 'lib/helper/helper.rb', line 190

def render_tokens(opts = {})

  code_object = opts[:of] or raise Exception.new("Parameter :of (CodeObject) required")
  area        = opts[:in] or raise Exception.new("Parameter :in (Area) required")
  exclude     = opts[:without] || []

  rendered = ""

  tokens = code_object.tokens.reject {|token, v| exclude.include? token }

  token_groups = tokens.values.each do |tokens|        
       
    # tokens is an array of Token::Token
    if not tokens.empty? and tokens.first.area == area
    
      template = tokens.first.template.to_s
      
      # overwriting default template with specified option[:template] if existant
      template = opts[:template].to_s if opts[:template] and template == 'default'
    
      rendered += render :partial => "tokens/#{template}", :locals => { :tokens => tokens }
    end
  end            
  
  rendered
end

#script(*args) ⇒ String

TODO:

because those js-files are all relative links, they could be joined together and packed afterwards

Creates a javascript-tag for each input string to import the script. The resource will be linked relativly.

Examples:

script 'foo', 'bar'
#=> <script href='../js/foo.js'/>
#=> <script href='../js/bar.js'/>

Parameters:

  • basename (String) —

    of the javascript-file (without extension)

Returns:

  • (String) —

    html-element to include the javascript-file



85
86
87
88
89
 
# File 'lib/helper/helper.rb', line 85

def script(*args)
  args.map do |path|
    tag :script, "", :src => to_relative('js/'+path+'.js')
  end.join ''
end

#style(*args) ⇒ String

Creates a css-link tag for each input string. The resource will be linked relativly.

Examples:

style 'foo', 'bar'
#=> <link rel='stylesheet' href='../css/foo.css'/>
#=> <link rel='stylesheet' href='../css/bar.css'/>

Parameters:

  • basename (String) —

    of the css-file (without extension)

Returns:

  • (String) —

    html-element to include the css-file



66
67
68
69
70
 
# File 'lib/helper/helper.rb', line 66

def style(*args)
  args.map do |path|
    tag :link, "", :rel => 'stylesheet', :href => to_relative('css/'+path+'.css')
  end.join ''
end

#tag(tagname, content = "", attrs = {}) ⇒ String

TODO:

FIXME - not working with block, yet… Rails incorporates a ‘capture` method, which captures the ERB-output of a block maybe we can use something like that `with_output_buffer` http://apidock.com/rails/ActionView/Helpers/CaptureHelper/with_output_buffer

Creates a HTML-Tag and adds the attributes, specified with ‘attrs`

Examples:

tag :a, 'Hello', :href => 'http://foobar.com', :class => 'red_one'
#=> <a href="http://foobar.com" class="red_one">Hello</a>

Parameters:

  • tagname (Symbol, String)
  • content (String) (defaults to: "")
  • attrs (Hash<Symbol, String>) (defaults to: {})

Returns:

See Also:



40
41
42
43
44
45
46
47
48
49
50
 
# File 'lib/helper/helper.rb', line 40

def tag(tagname, content = "", attrs = {})
   
  # Not working with blocks!
  if block_given?
    _erbout << "<#{tagname.to_s} #{attributize(content)}>"        
    content = yield
    _erbout << "</#{tagname.to_s}>"
  else
    "<#{tagname.to_s} #{attributize(attrs)}>#{content}</#{tagname.to_s}>"        
  end     
end

#to_html(markdown_text, *markdown_opts) ⇒ String

Converts input text to html using RDiscount. Afterwards all contained links are resolved and replaced.

More information about the markdown_opts can be found at the RDiscount-rdoc-page.

Parameters:

  • markdown_text (String) —

    plain text with markdown-markup

  • markdown_opts (Symbol, nil)

Returns:



239
240
241
 
# File 'lib/helper/helper.rb', line 239

def to_html(markdown_text, *markdown_opts)
  replace_links RDiscount.new(markdown_text, *markdown_opts).to_html
end

#to_relative(path) ⇒ String

Takes an absolute path and converts it to a relative one, comparing it to the **current output path**.

Parameters:

Returns:



138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
 
# File 'lib/helper/helper.rb', line 138

def to_relative(path)

  path = Pathname.new(path)
  base = Pathname.new(@current_path)
  
  # for example /home/jsdoc/css/style.css
  # current: /home/jsdoc/output/Foo/Bar.html
  if not path.absolute?
    # resolve to Configs.output
    path = Pathname.new(Configs.output) + path
  end     
  
  Logger.debug "Relative path '#{path}' from '#{base}'"
  path.relative_path_from(base).to_s
end

#toc(markdown_text) ⇒ String

Can be used to generate a table of contents out of a markdown-text. The generated toc contains links to the document-headlines. To make this links actually work you need to process the document with the :generate_toc flag, too.

Examples:

<%= toc(my_text) %>
...
<%= to_html my_text, :generate_toc %>

Parameters:

Returns:

  • (String) —

    html table of contents



255
256
257
 
# File 'lib/helper/helper.rb', line 255

def toc(markdown_text)
  RDiscount.new(markdown_text, :generate_toc).toc_content
end

#truncate(string, length = 150) ⇒ Object

Shortens the given string to the specified length and adds ‘…’



53
54
55
 
# File 'lib/helper/helper.rb', line 53

def truncate(string, length = 150)
  string.length <= length ? string : string[0..length] + " &hellip;"
end