Module: DHTML::Document

Included in:
DHTML
Defined in:
lib/dhtml/document.rb

Overview

Provides methods for generating HTML.

Since:

  • 0.1.0

Constant Summary collapse

ESCAPE_HTML =

Most commonly used HTML escape sequences.

Since:

  • 0.1.0

{
  "'" => ''',
  '"' => '"',
  '&' => '&',
  '/' => '/',
  '<' => '&lt;',
  '>' => '&gt;',
}
ESCAPE_HTML_PATTERN =

Regular expression that matches the most common characters that need to be escaped in HTML strings.

Since:

  • 0.1.0

Regexp.union(*ESCAPE_HTML.keys)

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#tag ⇒ void (readonly)

This method returns an undefined value.

Writes the opening element for the given HTML tag to the document.

Since:

  • 0.1.0



135
136
137
138
139
140
141
142
 
# File 'lib/dhtml/document.rb', line 135

def write_html_element(tag, attributes = {})
  document << '<'
  document << tag
  document << " #{html_attributes(attributes)}" unless attributes.empty?
  document << '>'

  nil
end

Instance Method Details

#attributes=(value) ⇒ void

This method returns an undefined value.

Writes the opening element for the given HTML tag to the document.

Since:

  • 0.1.0



135
136
137
138
139
140
141
142
 
# File 'lib/dhtml/document.rb', line 135

def write_html_element(tag, attributes = {})
  document << '<'
  document << tag
  document << " #{html_attributes(attributes)}" unless attributes.empty?
  document << '>'

  nil
end

#doctype(type) ⇒ Integer

Writes the HTML doctype.

Parameters:

  • type (Symbol) —

    of document

Returns:

  • (Integer) —

    number of bytes written to the document.

Since:

  • 0.1.0



34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
 
# File 'lib/dhtml/document.rb', line 34

def doctype(type)
  tag = case type
  when :html3
    %|<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">|
  when :html4
    %|<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">|
  when :html4_framesets, :html4_fr
    %|<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN" "http://www.w3.org/TR/html4/frameset.dtd">|
  when :html4_transitional, :html4_tr
    %|<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">|
  when :html5, :html
    %|<!doctype html>|
  else
    fail ArgumentError, "unsupported doctype: #{type.inspect}"
  end

  document.write(tag)
end

#document ⇒ StringIO

The document is written to this buffer.

Returns:

  • (StringIO)

Since:

  • 0.1.0



57
58
59
 
# File 'lib/dhtml/document.rb', line 57

def document
  @document ||= StringIO.new
end

#finish ⇒ StringIO

Rewinds the document so it can be read.

Returns:

  • (StringIO)

Since:

  • 0.1.0



65
66
67
 
# File 'lib/dhtml/document.rb', line 65

def finish
  document.tap(&:rewind)
end

#html_attribute(name, value) ⇒ String

Generates an HTML attribute (e.g. class=“form”).

Parameters:

  • name (Symbol, String)
  • value (Symbol, String)

Returns:

  • (String)

Since:

  • 0.1.0



75
76
77
 
# File 'lib/dhtml/document.rb', line 75

def html_attribute(name, value)
  [h(name.to_s), h(value.to_s).inspect].join('=')
end

#html_attributes(attributes) ⇒ String

Generates a string of HTML attributes from a Hash.

Parameters:

  • attributes (Hash)

Returns:

  • (String)

Since:

  • 0.1.0



84
85
86
87
 
# File 'lib/dhtml/document.rb', line 84

def html_attributes(attributes)
  # noinspection RubyYardParamTypeMatch
  attributes.inject([]) { _1 << html_attribute(_2[0], _2[1]) }.join(' ')
end

#html_escape(string) ⇒ String Also known as: h

Escape ampersands, brackets and quotes for HTML.

Parameters:

  • string (String) —

    to escape.

Returns:

  • (String) —

    HTML escaped string.

Since:

  • 0.1.0



94
95
96
 
# File 'lib/dhtml/document.rb', line 94

def html_escape(string)
  string.to_s.gsub(ESCAPE_HTML_PATTERN) { ESCAPE_HTML[_1] }
end

#pretty_html(indent: ' ' * 2) ⇒ String

Note:

Not available to Opal.

Reads and formats the document in a way presentable to a human.

Parameters:

  • indent (String) (defaults to: ' ' * 2) —

    string.

Returns:

  • (String)

Since:

  • 0.1.4



106
107
108
109
110
 
# File 'lib/dhtml/document.rb', line 106

def pretty_html(indent: ' ' * 2)
  require 'cgi' unless defined?(CGI)

  CGI.pretty(read_html, indent)
end

#read_html ⇒ String

Reads the entire HTML document.

Returns:

  • (String)

Since:

  • 0.1.0



116
117
118
 
# File 'lib/dhtml/document.rb', line 116

def read_html
  document.tap(&:rewind).read
end

#reset ⇒ StringIO

Clears all content from the document.

Returns:

  • (StringIO)

Since:

  • 0.1.1



124
125
126
127
 
# File 'lib/dhtml/document.rb', line 124

def reset
  document.close
  document.reopen
end

#write_html_element(tag, attributes = {}) ⇒ void

This method returns an undefined value.

Writes the opening element for the given HTML tag to the document.

Since:

  • 0.1.0



135
136
137
138
139
140
141
142
 
# File 'lib/dhtml/document.rb', line 135

def write_html_element(tag, attributes = {})
  document << '<'
  document << tag
  document << " #{html_attributes(attributes)}" unless attributes.empty?
  document << '>'

  nil
end

#write_html_tag(tag: __callee__, **attributes, &inner_html) ⇒ void

This method returns an undefined value.

Write a tag to the HTML document.

Parameters:

  • tag (Symbol) (defaults to: __callee__) —

    name.

  • attributes (Hash) —

    for the tag.

  • inner_html (Proc) —

    to include in the tag.

Since:

  • 0.1.0



151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
 
# File 'lib/dhtml/document.rb', line 151

def write_html_tag(tag: __callee__, **attributes, &inner_html)
  # Ensure the method isn't being called directly.
  fail ArgumentError, 'invalid tag' if tag == :write_html_tag

  # Remove the underscore prefix added to prevent conflicts with internal Ruby methods.
  tag = tag.to_s
  tag = tag[1..-1] if tag[0] == '_'

  # Opening tag with its HTML attributes - e.g. <div id="main">
  write_html_element(tag, attributes)

  # Capture the inner HTML.
  content = inner_html&.call(document)

  # Write the inner HTML to the document when present.
  document.write(content) if content.is_a?(String)

  # Close the tag when necessary.
  document.write("</#{tag}>") if content.is_a?(String) || block_given? || !void?(tag.to_sym)

  nil
end