module DHTML::Document

Provides methods for generating HTML.

@since 0.1.0

Constants

ESCAPE_HTML

Most commonly used HTML escape sequences.

@type [Hash<String => String>] @since 0.1.0

ESCAPE_HTML_PATTERN

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

@type [Regexp] @since 0.1.0

Public Instance Methods

doctype(type) click to toggle source

Writes the HTML doctype.

@param [Symbol] type of document @return [Integer] number of bytes written to the document. @since 0.1.0

# 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() click to toggle source

The document is written to this buffer.

@return [StringIO] @since 0.1.0

# File lib/dhtml/document.rb, line 57
def document
  @document ||= StringIO.new
end
finish() click to toggle source

Rewinds the document so it can be read.

@return [StringIO] @since 0.1.0

# File lib/dhtml/document.rb, line 65
def finish
  document.tap(&:rewind)
end
h(string)
Alias for: html_escape
html_attribute(name, value) click to toggle source

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

@param [Symbol, String] name @param [Symbol, String] value @return [String] @since 0.1.0

# 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) click to toggle source

Generates a string of HTML attributes from a Hash.

@param [Hash] attributes @return [String] @since 0.1.0

# 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) click to toggle source

Escape ampersands, brackets and quotes for HTML.

@param [String] string to escape. @return [String] HTML escaped string. @since 0.1.0

# File lib/dhtml/document.rb, line 94
def html_escape(string)
  string.to_s.gsub(ESCAPE_HTML_PATTERN) { ESCAPE_HTML[_1] }
end
Also aliased as: h
pretty_html(indent: ' ' * 2) click to toggle source

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

@note Not available to Opal. @param [String] indent string. @return [String] @since 0.1.4

# 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() click to toggle source

Reads the entire HTML document.

@return [String] @since 0.1.0

# File lib/dhtml/document.rb, line 116
def read_html
  document.tap(&:rewind).read
end
reset() click to toggle source

Clears all content from the document.

@return [StringIO] @since 0.1.1

# File lib/dhtml/document.rb, line 124
def reset
  document.close
  document.reopen
end
write_html_element(tag, attributes = {}) click to toggle source

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

@!attribute [String] tag @!attribute [Hash] attributes @return [void] @since 0.1.0

# 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) click to toggle source

Write a tag to the HTML document.

@param [Symbol] tag name. @param [Hash] attributes for the tag. @param [Proc] inner_html to include in the tag. @return [void] @since 0.1.0

# 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