Module: Erector::HTML

Included in:
Widget
Defined in:
lib/erector/html.rb

Defined Under Namespace

Modules: ClassMethods

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.included(base) ⇒ Object 



60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/erector/html.rb', line 60

def self.included(base)
  base.extend ClassMethods

  base.full_tags.each do |tag_name|
    base.def_full_tag_method(tag_name)
  end

  base.empty_tags.each do |tag_name|
    base.def_empty_tag_method(tag_name)
  end
end

Instance Method Details

#character(code_point_or_name) ⇒ Object

Return a character given its unicode code point or unicode name.



178
179
180
181
182
183
184
185
186
187
188
189
190
191
 
# File 'lib/erector/html.rb', line 178

def character(code_point_or_name)
  if code_point_or_name.is_a?(Symbol)
    require "erector/unicode"
    found = Erector::CHARACTERS[code_point_or_name]
    if found.nil?
      raise "Unrecognized character #{code_point_or_name}"
    end
    raw("&#x#{sprintf '%x', found};")
  elsif code_point_or_name.is_a?(Integer)
    raw("&#x#{sprintf '%x', code_point_or_name};")
  else
    raise "Unrecognized argument to character: #{code_point_or_name}"
  end
end

#close_tag(tag_name) ⇒ Object

Emits a close tag, consisting of ‘<’, ‘/’, tag name, and ‘>’



132
133
134
135
136
137
138
 
# File 'lib/erector/html.rb', line 132

def close_tag(tag_name)
  output.undent
  output << raw("</#{tag_name}>")
  if newliney?(tag_name)
    output.newline
  end
end

#comment(text = '') ⇒ Object

Emits an HTML comment (&lt;!– … –&gt;) surrounding text and/or the output of block. see www.w3.org/TR/html4/intro/sgmltut.html#h-3.2.4

If text is an Internet Explorer conditional comment condition such as “[if IE]”, the output includes the opening condition and closing “[endif]”. See www.quirksmode.org/css/condcom.html

Since “Authors should avoid putting two or more adjacent hyphens inside comments,” we emit a warning if you do that.



207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
 
# File 'lib/erector/html.rb', line 207

def comment(text = '')
  puts "Warning: Authors should avoid putting two or more adjacent hyphens inside comments." if text =~ /--/

  conditional = text =~ /\[if .*\]/

  rawtext "<!--"
  rawtext text
  rawtext ">" if conditional

  if block_given?
    rawtext "\n"
    yield
    rawtext "\n"
  end

  rawtext "<![endif]" if conditional
  rawtext "-->\n"
end

#element(*args, &block) ⇒ Object

Internal method used to emit an HTML/XML element, including an open tag, attributes (optional, via the default hash), contents (also optional), and close tag.

Using the arcane powers of Ruby, there are magic methods that call element for all the standard HTML tags, like a, body, p, and so forth. Look at the source of #full_tags for the full list. Unfortunately, this big mojo confuses rdoc, so we can’t see each method in this rdoc page, but trust us, they’re there.

When calling one of these magic methods, put attributes in the default hash. If there is a string parameter, then it is used as the contents. If there is a block, then it is executed (yielded), and the string parameter is ignored. The block will usually be in the scope of the child widget, which means it has access to all the methods of Widget, which will eventually end up appending text to the output string. See how elegant it is? Not confusing at all if you don’t think about it.



90
91
92
 
# File 'lib/erector/html.rb', line 90

def element(*args, &block)
  __element__(false, *args, &block)
end

#element!(*args, &block) ⇒ Object

Like element, but string parameters are not escaped.



95
96
97
 
# File 'lib/erector/html.rb', line 95

def element!(*args, &block)
  __element__(true, *args, &block)
end

#empty_element(*args, &block) ⇒ Object

Internal method used to emit a self-closing HTML/XML element, including a tag name and optional attributes (passed in via the default hash).

Using the arcane powers of Ruby, there are magic methods that call empty_element for all the standard HTML tags, like img, br, and so forth. Look at the source of #empty_tags for the full list. Unfortunately, this big mojo confuses rdoc, so we can’t see each method in this rdoc page, but trust us, they’re there.



108
109
110
 
# File 'lib/erector/html.rb', line 108

def empty_element(*args, &block)
  __empty_element__(*args, &block)
end

#h(content) ⇒ Object

Returns an HTML-escaped version of its parameter. Leaves the output string untouched. This method is idempotent: h(h(text)) will not double-escape text. This means that it is safe to do something like text(h(“2<4”)) – it will produce “2&lt;4”, not “2&amp;lt;4”.



116
117
118
119
120
121
122
 
# File 'lib/erector/html.rb', line 116

def h(content)
  if content.respond_to?(:html_safe?) && content.html_safe?
    content
  else
    raw(CGI.escapeHTML(content.to_s))
  end
end

#instruct(attributes = {:version => "1.0", :encoding => "UTF-8"}) ⇒ Object

Emits an XML instruction, which looks like this: <?xml version="1.0" encoding="UTF-8"?>



194
195
196
 
# File 'lib/erector/html.rb', line 194

def instruct(attributes={:version => "1.0", :encoding => "UTF-8"})
  output << raw("<?xml#{format_sorted(sort_for_xml_declaration(attributes))}?>")
end

#javascript(value = nil, attributes = {}) ⇒ Object

Emits a javascript block inside a script tag, wrapped in CDATA doohickeys like all the cool JS kids do.



228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
 
# File 'lib/erector/html.rb', line 228

def javascript(value = nil, attributes = {})
  if value.is_a?(Hash)
    attributes = value
    value      = nil
  elsif block_given? && value
    raise ArgumentError, "You can't pass both a block and a value to javascript -- please choose one."
  end

  script(attributes.merge(:type => "text/javascript")) do
    # Shouldn't this be a "cdata" HtmlPart?
    # (maybe, but the syntax is specific to javascript; it isn't
    # really a generic XML CDATA section.  Specifically,
    # ]]> within value is not treated as ending the
    # CDATA section by Firefox2 when parsing text/html,
    # although I guess we could refuse to generate ]]>
    # there, for the benefit of XML/XHTML parsers).
    output << raw("\n// <![CDATA[\n")
    if block_given?
      yield
    else
      output << raw(value)
    end
    output << raw("\n// ]]>")
    output.append_newline # this forces a newline even if we're not in pretty mode
  end

  output << raw("\n")
end

#nbsp(value = " ") ⇒ Object

Returns a copy of value with spaces replaced by non-breaking space characters. With no arguments, return a single non-breaking space. The output uses the escaping format ‘&#160;’ since that works in both HTML and XML (as opposed to ‘&nbsp;’ which only works in HTML).



173
174
175
 
# File 'lib/erector/html.rb', line 173

def nbsp(value = " ")
  raw(h(value).gsub(/ /,'&#160;'))
end

#open_tag(tag_name, attributes = {}) ⇒ Object

Emits an open tag, comprising ‘<’, tag name, optional attributes, and ‘>’



125
126
127
128
129
 
# File 'lib/erector/html.rb', line 125

def open_tag(tag_name, attributes={})
  output.newline if newliney?(tag_name) && !output.at_line_start?
  output << raw("<#{tag_name}#{format_attributes(attributes)}>")
  output.indent
end

#raw(value) ⇒ Object

Returns text which will not be HTML-escaped.



141
142
143
 
# File 'lib/erector/html.rb', line 141

def raw(value)
  RawString.new(value.to_s)
end

#text(value) ⇒ Object

Emits text. If a string is passed in, it will be HTML-escaped. If the result of calling methods such as raw is passed in, the HTML will not be HTML-escaped again. If another kind of object is passed in, the result of calling its to_s method will be treated as a string would be.

You shouldn’t pass a widget in to this method, as that will cause performance problems (as well as being semantically goofy). Use the #widget method instead.



153
154
155
156
157
158
159
160
 
# File 'lib/erector/html.rb', line 153

def text(value)
  if value.is_a? Widget
    widget value
  else
    output << h(value)
  end
  nil
end

#text!(value) ⇒ Object Also known as: rawtext

Emits text which will not be HTML-escaped. Same effect as text(raw(s))



163
164
165
 
# File 'lib/erector/html.rb', line 163

def text!(value)
  text raw(value)
end