# module CGI::HtmlExtension

Mixin module providing HTML generation methods.

For example,

    cgi.a("http://www.example.com") { "Example" }
      # => "<A HREF=\"http://www.example.com\">Example</A>"

Modules Html3, Html4, etc., contain more basic HTML-generation methods (`#title`, `#h1`, etc.).

See class `CGI` for a detailed example.

### Public Instance Methods

a(href = "") { || ... } click to toggle source

Generate an Anchor element as a string.

`href` can either be a string, giving the URL for the HREF attribute, or it can be a hash of the element's attributes.

The body of the element is the string returned by the no-argument block passed in.

    a("http://www.example.com") { "Example" }
      # => "<A HREF=\"http://www.example.com\">Example</A>"

    a("HREF" => "http://www.example.com", "TARGET" => "_top") { "Example" }
      # => "<A HREF=\"http://www.example.com\" TARGET=\"_top\">Example</A>"

Calls superclass method

    # File lib/cgi/html.rb, line 97
    def a(href = "") # :yield:
      attributes = if href.kind_of?(String)
                     { "HREF" => href }
                   else
                     href
                   end
      super(attributes)
    end

base(href = "") { || ... } click to toggle source

Generate a Document Base `URI` element as a `String`.

`href` can either by a string, giving the base URL for the HREF attribute, or it can be a has of the element's attributes.

The passed-in no-argument block is ignored.

    base("http://www.example.com/cgi")
      # => "<BASE HREF=\"http://www.example.com/cgi\">"

Calls superclass method

    # File lib/cgi/html.rb, line 115
    def base(href = "") # :yield:
      attributes = if href.kind_of?(String)
                     { "HREF" => href }
                   else
                     href
                   end
      super(attributes)
    end

blockquote(cite = {}) { || ... } click to toggle source

Generate a BlockQuote element as a string.

`cite` can either be a string, give the `URI` for the source of the quoted text, or a hash, giving all attributes of the element, or it can be omitted, in which case the element has no attributes.

The body is provided by the passed-in no-argument block

    blockquote("http://www.example.com/quotes/foo.html") { "Foo!" }
      #=> "<BLOCKQUOTE CITE=\"http://www.example.com/quotes/foo.html\">Foo!</BLOCKQUOTE>

Calls superclass method

    # File lib/cgi/html.rb, line 134
    def blockquote(cite = {})  # :yield:
      attributes = if cite.kind_of?(String)
                     { "CITE" => cite }
                   else
                     cite
                   end
      super(attributes)
    end

caption(align = {}) { || ... } click to toggle source

Generate a Table Caption element as a string.

`align` can be a string, giving the alignment of the caption (one of top, bottom, left, or right). It can be a hash of all the attributes of the element. Or it can be omitted.

The body of the element is provided by the passed-in no-argument block.

    caption("left") { "Capital Cities" }
      # => <CAPTION ALIGN=\"left\">Capital Cities</CAPTION>

Calls superclass method

    # File lib/cgi/html.rb, line 154
    def caption(align = {}) # :yield:
      attributes = if align.kind_of?(String)
                     { "ALIGN" => align }
                   else
                     align
                   end
      super(attributes)
    end

checkbox(name = "", value = nil, checked = nil) click to toggle source

Generate a Checkbox Input element as a string.

The attributes of the element can be specified as three arguments, `name`, `value`, and `checked`. `checked` is a boolean value; if true, the CHECKED attribute will be included in the element.

Alternatively, the attributes can be specified as a hash.

    checkbox("name")
      # = checkbox("NAME" => "name")

    checkbox("name", "value")
      # = checkbox("NAME" => "name", "VALUE" => "value")

    checkbox("name", "value", true)
      # = checkbox("NAME" => "name", "VALUE" => "value", "CHECKED" => true)

    # File lib/cgi/html.rb, line 180
    def checkbox(name = "", value = nil, checked = nil)
      attributes = if name.kind_of?(String)
                     { "TYPE" => "checkbox", "NAME" => name,
                       "VALUE" => value, "CHECKED" => checked }
                   else
                     name["TYPE"] = "checkbox"
                     name
                   end
      input(attributes)
    end

checkbox_group(name = "", *values) click to toggle source

Generate a sequence of checkbox elements, as a `String`.

The checkboxes will all have the same `name` attribute. Each checkbox is followed by a label. There will be one checkbox for each value. Each value can be specified as a `String`, which will be used both as the value of the VALUE attribute and as the label for that checkbox. A single-element array has the same effect.

Each value can also be specified as a three-element array. The first element is the VALUE attribute; the second is the label; and the third is a boolean specifying whether this checkbox is CHECKED.

Each value can also be specified as a two-element array, by omitting either the value element (defaults to the same as the label), or the boolean checked element (defaults to false).

    checkbox_group("name", "foo", "bar", "baz")
      # <INPUT TYPE="checkbox" NAME="name" VALUE="foo">foo
      # <INPUT TYPE="checkbox" NAME="name" VALUE="bar">bar
      # <INPUT TYPE="checkbox" NAME="name" VALUE="baz">baz

    checkbox_group("name", ["foo"], ["bar", true], "baz")
      # <INPUT TYPE="checkbox" NAME="name" VALUE="foo">foo
      # <INPUT TYPE="checkbox" CHECKED NAME="name" VALUE="bar">bar
      # <INPUT TYPE="checkbox" NAME="name" VALUE="baz">baz

    checkbox_group("name", ["1", "Foo"], ["2", "Bar", true], "Baz")
      # <INPUT TYPE="checkbox" NAME="name" VALUE="1">Foo
      # <INPUT TYPE="checkbox" CHECKED NAME="name" VALUE="2">Bar
      # <INPUT TYPE="checkbox" NAME="name" VALUE="Baz">Baz

    checkbox_group("NAME" => "name",
                     "VALUES" => ["foo", "bar", "baz"])

    checkbox_group("NAME" => "name",
                     "VALUES" => [["foo"], ["bar", true], "baz"])

    checkbox_group("NAME" => "name",
                     "VALUES" => [["1", "Foo"], ["2", "Bar", true], "Baz"])

    # File lib/cgi/html.rb, line 234
    def checkbox_group(name = "", *values)
      if name.kind_of?(Hash)
        values = name["VALUES"]
        name = name["NAME"]
      end
      values.collect{|value|
        if value.kind_of?(String)
          checkbox(name, value) + value
        else
          if value[-1] == true || value[-1] == false
            checkbox(name, value[0],  value[-1]) +
            value[-2]
          else
            checkbox(name, value[0]) +
            value[-1]
          end
        end
      }.join
    end

file_field(name = "", size = 20, maxlength = nil) click to toggle source

Generate an `File` Upload Input element as a string.

The attributes of the element can be specified as three arguments, `name`, `size`, and `maxlength`. `maxlength` is the maximum length of the file's name, not of the file's contents.

Alternatively, the attributes can be specified as a hash.

See `multipart_form()` for forms that include file uploads.

    file_field("name")
      # <INPUT TYPE="file" NAME="name" SIZE="20">

    file_field("name", 40)
      # <INPUT TYPE="file" NAME="name" SIZE="40">

    file_field("name", 40, 100)
      # <INPUT TYPE="file" NAME="name" SIZE="40" MAXLENGTH="100">

    file_field("NAME" => "name", "SIZE" => 40)
      # <INPUT TYPE="file" NAME="name" SIZE="40">

    # File lib/cgi/html.rb, line 276
    def file_field(name = "", size = 20, maxlength = nil)
      attributes = if name.kind_of?(String)
                     { "TYPE" => "file", "NAME" => name,
                       "SIZE" => size.to_s }
                   else
                     name["TYPE"] = "file"
                     name
                   end
      attributes["MAXLENGTH"] = maxlength.to_s if maxlength
      input(attributes)
    end

form(method = "post", action = script_name, enctype = "application/x-www-form-urlencoded") { || ... } click to toggle source

Generate a Form element as a string.

`method` should be either “get” or “post”, and defaults to the latter. `action` defaults to the current `CGI` script name. `enctype` defaults to “application/x-www-form-urlencoded”.

Alternatively, the attributes can be specified as a hash.

See also `multipart_form()` for forms that include file uploads.

    form{ "string" }
      # <FORM METHOD="post" ENCTYPE="application/x-www-form-urlencoded">string</FORM>

    form("get") { "string" }
      # <FORM METHOD="get" ENCTYPE="application/x-www-form-urlencoded">string</FORM>

    form("get", "url") { "string" }
      # <FORM METHOD="get" ACTION="url" ENCTYPE="application/x-www-form-urlencoded">string</FORM>

    form("METHOD" => "post", "ENCTYPE" => "enctype") { "string" }
      # <FORM METHOD="post" ENCTYPE="enctype">string</FORM>

Calls superclass method

    # File lib/cgi/html.rb, line 310
    def form(method = "post", action = script_name, enctype = "application/x-www-form-urlencoded")
      attributes = if method.kind_of?(String)
                     { "METHOD" => method, "ACTION" => action,
                       "ENCTYPE" => enctype }
                   else
                     unless method.has_key?("METHOD")
                       method["METHOD"] = "post"
                     end
                     unless method.has_key?("ENCTYPE")
                       method["ENCTYPE"] = enctype
                     end
                     method
                   end
      if block_given?
        body = yield
      else
        body = ""
      end
      if @output_hidden
        body << @output_hidden.collect{|k,v|
          "<INPUT TYPE=\"HIDDEN\" NAME=\"#{k}\" VALUE=\"#{v}\">"
        }.join
      end
      super(attributes){body}
    end

hidden(name = "", value = nil) click to toggle source

Generate a Hidden Input element as a string.

The attributes of the element can be specified as two arguments, `name` and `value`.

Alternatively, the attributes can be specified as a hash.

    hidden("name")
      # <INPUT TYPE="hidden" NAME="name">

    hidden("name", "value")
      # <INPUT TYPE="hidden" NAME="name" VALUE="value">

    hidden("NAME" => "name", "VALUE" => "reset", "ID" => "foo")
      # <INPUT TYPE="hidden" NAME="name" VALUE="value" ID="foo">

    # File lib/cgi/html.rb, line 351
    def hidden(name = "", value = nil)
      attributes = if name.kind_of?(String)
                     { "TYPE" => "hidden", "NAME" => name, "VALUE" => value }
                   else
                     name["TYPE"] = "hidden"
                     name
                   end
      input(attributes)
    end

html(attributes = {}) { || ... } click to toggle source

Generate a top-level HTML element as a string.

The attributes of the element are specified as a hash. The pseudo-attribute “PRETTY” can be used to specify that the generated HTML string should be indented. “PRETTY” can also be specified as a string as the sole argument to this method. The pseudo-attribute “DOCTYPE”, if given, is used as the leading DOCTYPE SGML tag; it should include the entire text of this tag, including angle brackets.

The body of the html element is supplied as a block.

    html{ "string" }
      # <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"><HTML>string</HTML>

    html("LANG" => "ja") { "string" }
      # <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"><HTML LANG="ja">string</HTML>

    html("DOCTYPE" => false) { "string" }
      # <HTML>string</HTML>

    html("DOCTYPE" => '<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">') { "string" }
      # <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"><HTML>string</HTML>

    html("PRETTY" => "  ") { "<BODY></BODY>" }
      # <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
      # <HTML>
      #   <BODY>
      #   </BODY>
      # </HTML>

    html("PRETTY" => "\t") { "<BODY></BODY>" }
      # <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
      # <HTML>
      #         <BODY>
      #         </BODY>
      # </HTML>

    html("PRETTY") { "<BODY></BODY>" }
      # = html("PRETTY" => "  ") { "<BODY></BODY>" }

    html(if $VERBOSE then "PRETTY" end) { "HTML string" }

Calls superclass method

    # File lib/cgi/html.rb, line 403
    def html(attributes = {}) # :yield:
      if nil == attributes
        attributes = {}
      elsif "PRETTY" == attributes
        attributes = { "PRETTY" => true }
      end
      pretty = attributes.delete("PRETTY")
      pretty = "  " if true == pretty
      buf = "".dup

      if attributes.has_key?("DOCTYPE")
        if attributes["DOCTYPE"]
          buf << attributes.delete("DOCTYPE")
        else
          attributes.delete("DOCTYPE")
        end
      else
        buf << doctype
      end

      buf << super(attributes)

      if pretty
        CGI.pretty(buf, pretty)
      else
        buf
      end

    end

image_button(src = "", name = nil, alt = nil) click to toggle source

Generate an Image Button Input element as a string.

`src` is the URL of the image to use for the button. `name` is the input name. `alt` is the alternative text for the image.

Alternatively, the attributes can be specified as a hash.

    image_button("url")
      # <INPUT TYPE="image" SRC="url">

    image_button("url", "name", "string")
      # <INPUT TYPE="image" SRC="url" NAME="name" ALT="string">

    image_button("SRC" => "url", "ALT" => "string")
      # <INPUT TYPE="image" SRC="url" ALT="string">

    # File lib/cgi/html.rb, line 448
    def image_button(src = "", name = nil, alt = nil)
      attributes = if src.kind_of?(String)
                     { "TYPE" => "image", "SRC" => src, "NAME" => name,
                       "ALT" => alt }
                   else
                     src["TYPE"] = "image"
                     src["SRC"] ||= ""
                     src
                   end
      input(attributes)
    end

img(src = "", alt = "", width = nil, height = nil) click to toggle source

Generate an Image element as a string.

`src` is the URL of the image. `alt` is the alternative text for the image. `width` is the width of the image, and `height` is its height.

Alternatively, the attributes can be specified as a hash.

    img("src", "alt", 100, 50)
      # <IMG SRC="src" ALT="alt" WIDTH="100" HEIGHT="50">

    img("SRC" => "src", "ALT" => "alt", "WIDTH" => 100, "HEIGHT" => 50)
      # <IMG SRC="src" ALT="alt" WIDTH="100" HEIGHT="50">

Calls superclass method

    # File lib/cgi/html.rb, line 474
    def img(src = "", alt = "", width = nil, height = nil)
      attributes = if src.kind_of?(String)
                     { "SRC" => src, "ALT" => alt }
                   else
                     src
                   end
      attributes["WIDTH"] = width.to_s if width
      attributes["HEIGHT"] = height.to_s if height
      super(attributes)
    end

multipart_form(action = nil, enctype = "multipart/form-data") { || ... } click to toggle source

Generate a Form element with multipart encoding as a `String`.

Multipart encoding is used for forms that include file uploads.

`action` is the action to perform. `enctype` is the encoding type, which defaults to “multipart/form-data”.

Alternatively, the attributes can be specified as a hash.

    multipart_form{ "string" }
      # <FORM METHOD="post" ENCTYPE="multipart/form-data">string</FORM>

    multipart_form("url") { "string" }
      # <FORM METHOD="post" ACTION="url" ENCTYPE="multipart/form-data">string</FORM>

    # File lib/cgi/html.rb, line 500
    def multipart_form(action = nil, enctype = "multipart/form-data")
      attributes = if action == nil
                     { "METHOD" => "post", "ENCTYPE" => enctype }
                   elsif action.kind_of?(String)
                     { "METHOD" => "post", "ACTION" => action,
                       "ENCTYPE" => enctype }
                   else
                     unless action.has_key?("METHOD")
                       action["METHOD"] = "post"
                     end
                     unless action.has_key?("ENCTYPE")
                       action["ENCTYPE"] = enctype
                     end
                     action
                   end
      if block_given?
        form(attributes){ yield }
      else
        form(attributes)
      end
    end

password_field(name = "", value = nil, size = 40, maxlength = nil) click to toggle source

Generate a Password Input element as a string.

`name` is the name of the input field. `value` is its default value. `size` is the size of the input field display. `maxlength` is the maximum length of the inputted password.

Alternatively, attributes can be specified as a hash.

    password_field("name")
      # <INPUT TYPE="password" NAME="name" SIZE="40">

    password_field("name", "value")
      # <INPUT TYPE="password" NAME="name" VALUE="value" SIZE="40">

    password_field("password", "value", 80, 200)
      # <INPUT TYPE="password" NAME="name" VALUE="value" SIZE="80" MAXLENGTH="200">

    password_field("NAME" => "name", "VALUE" => "value")
      # <INPUT TYPE="password" NAME="name" VALUE="value">

    # File lib/cgi/html.rb, line 542
    def password_field(name = "", value = nil, size = 40, maxlength = nil)
      attributes = if name.kind_of?(String)
                     { "TYPE" => "password", "NAME" => name,
                       "VALUE" => value, "SIZE" => size.to_s }
                   else
                     name["TYPE"] = "password"
                     name
                   end
      attributes["MAXLENGTH"] = maxlength.to_s if maxlength
      input(attributes)
    end

radio_button(name = "", value = nil, checked = nil) click to toggle source

Generates a radio-button Input element.

`name` is the name of the input field. `value` is the value of the field if checked. `checked` specifies whether the field starts off checked.

Alternatively, the attributes can be specified as a hash.

    radio_button("name", "value")
      # <INPUT TYPE="radio" NAME="name" VALUE="value">

    radio_button("name", "value", true)
      # <INPUT TYPE="radio" NAME="name" VALUE="value" CHECKED>

    radio_button("NAME" => "name", "VALUE" => "value", "ID" => "foo")
      # <INPUT TYPE="radio" NAME="name" VALUE="value" ID="foo">

    # File lib/cgi/html.rb, line 646
    def radio_button(name = "", value = nil, checked = nil)
      attributes = if name.kind_of?(String)
                     { "TYPE" => "radio", "NAME" => name,
                       "VALUE" => value, "CHECKED" => checked }
                   else
                     name["TYPE"] = "radio"
                     name
                   end
      input(attributes)
    end

radio_group(name = "", *values) click to toggle source

Generate a sequence of radio button Input elements, as a `String`.

This works the same as `checkbox_group()`. However, it is not valid to have more than one radiobutton in a group checked.

    radio_group("name", "foo", "bar", "baz")
      # <INPUT TYPE="radio" NAME="name" VALUE="foo">foo
      # <INPUT TYPE="radio" NAME="name" VALUE="bar">bar
      # <INPUT TYPE="radio" NAME="name" VALUE="baz">baz

    radio_group("name", ["foo"], ["bar", true], "baz")
      # <INPUT TYPE="radio" NAME="name" VALUE="foo">foo
      # <INPUT TYPE="radio" CHECKED NAME="name" VALUE="bar">bar
      # <INPUT TYPE="radio" NAME="name" VALUE="baz">baz

    radio_group("name", ["1", "Foo"], ["2", "Bar", true], "Baz")
      # <INPUT TYPE="radio" NAME="name" VALUE="1">Foo
      # <INPUT TYPE="radio" CHECKED NAME="name" VALUE="2">Bar
      # <INPUT TYPE="radio" NAME="name" VALUE="Baz">Baz

    radio_group("NAME" => "name",
                  "VALUES" => ["foo", "bar", "baz"])

    radio_group("NAME" => "name",
                  "VALUES" => [["foo"], ["bar", true], "baz"])

    radio_group("NAME" => "name",
                  "VALUES" => [["1", "Foo"], ["2", "Bar", true], "Baz"])

    # File lib/cgi/html.rb, line 685
    def radio_group(name = "", *values)
      if name.kind_of?(Hash)
        values = name["VALUES"]
        name = name["NAME"]
      end
      values.collect{|value|
        if value.kind_of?(String)
          radio_button(name, value) + value
        else
          if value[-1] == true || value[-1] == false
            radio_button(name, value[0],  value[-1]) +
            value[-2]
          else
            radio_button(name, value[0]) +
            value[-1]
          end
        end
      }.join
    end

reset(value = nil, name = nil) click to toggle source

Generate a reset button Input element, as a `String`.

This resets the values on a form to their initial values. `value` is the text displayed on the button. `name` is the name of this button.

Alternatively, the attributes can be specified as a hash.

    reset
      # <INPUT TYPE="reset">

    reset("reset")
      # <INPUT TYPE="reset" VALUE="reset">

    reset("VALUE" => "reset", "ID" => "foo")
      # <INPUT TYPE="reset" VALUE="reset" ID="foo">

    # File lib/cgi/html.rb, line 720
    def reset(value = nil, name = nil)
      attributes = if (not value) or value.kind_of?(String)
                     { "TYPE" => "reset", "VALUE" => value, "NAME" => name }
                   else
                     value["TYPE"] = "reset"
                     value
                   end
      input(attributes)
    end

scrolling_list(name = "", *values)
Alias for: popup_menu
submit(value = nil, name = nil) click to toggle source

Generate a submit button Input element, as a `String`.

`value` is the text to display on the button. `name` is the name of the input.

Alternatively, the attributes can be specified as a hash.

    submit
      # <INPUT TYPE="submit">

    submit("ok")
      # <INPUT TYPE="submit" VALUE="ok">

    submit("ok", "button1")
      # <INPUT TYPE="submit" VALUE="ok" NAME="button1">

    submit("VALUE" => "ok", "NAME" => "button1", "ID" => "foo")
      # <INPUT TYPE="submit" VALUE="ok" NAME="button1" ID="foo">

    # File lib/cgi/html.rb, line 750
    def submit(value = nil, name = nil)
      attributes = if (not value) or value.kind_of?(String)
                     { "TYPE" => "submit", "VALUE" => value, "NAME" => name }
                   else
                     value["TYPE"] = "submit"
                     value
                   end
      input(attributes)
    end

text_field(name = "", value = nil, size = 40, maxlength = nil) click to toggle source

Generate a text field Input element, as a `String`.

`name` is the name of the input field. `value` is its initial value. `size` is the size of the input area. `maxlength` is the maximum length of input accepted.

Alternatively, the attributes can be specified as a hash.

    text_field("name")
      # <INPUT TYPE="text" NAME="name" SIZE="40">

    text_field("name", "value")
      # <INPUT TYPE="text" NAME="name" VALUE="value" SIZE="40">

    text_field("name", "value", 80)
      # <INPUT TYPE="text" NAME="name" VALUE="value" SIZE="80">

    text_field("name", "value", 80, 200)
      # <INPUT TYPE="text" NAME="name" VALUE="value" SIZE="80" MAXLENGTH="200">

    text_field("NAME" => "name", "VALUE" => "value")
      # <INPUT TYPE="text" NAME="name" VALUE="value">

    # File lib/cgi/html.rb, line 782
    def text_field(name = "", value = nil, size = 40, maxlength = nil)
      attributes = if name.kind_of?(String)
                     { "TYPE" => "text", "NAME" => name, "VALUE" => value,
                       "SIZE" => size.to_s }
                   else
                     name["TYPE"] = "text"
                     name
                   end
      attributes["MAXLENGTH"] = maxlength.to_s if maxlength
      input(attributes)
    end

textarea(name = "", cols = 70, rows = 10) { || ... } click to toggle source

Generate a TextArea element, as a `String`.

`name` is the name of the textarea. `cols` is the number of columns and `rows` is the number of rows in the display.

Alternatively, the attributes can be specified as a hash.

The body is provided by the passed-in no-argument block

    textarea("name")
       # = textarea("NAME" => "name", "COLS" => 70, "ROWS" => 10)

    textarea("name", 40, 5)
       # = textarea("NAME" => "name", "COLS" => 40, "ROWS" => 5)

Calls superclass method

    # File lib/cgi/html.rb, line 808
    def textarea(name = "", cols = 70, rows = 10)  # :yield:
      attributes = if name.kind_of?(String)
                     { "NAME" => name, "COLS" => cols.to_s,
                       "ROWS" => rows.to_s }
                   else
                     name
                   end
      super(attributes)
    end