HTML::Menu::Select - Create HTML for select menus to simplify your templates.

- NAME
- SYNOPSIS
- DESCRIPTION
- INSTALLATION
- METHODS

- `menu()`
- `options()`
- `popup_menu()`

- HTML escaping
- CGI.pm COMPATABILITY
- SUPPORT / BUGS
- SEE ALSO
- AUTHOR
- CREDITS
- COPYRIGHT AND LICENSE

# NAME

HTML::Menu::Select - Create HTML for select menus to simplify your templates.

# SYNOPSIS

      use HTML::Menu::Select qw( menu options );

      my $html = menu(
        name   => 'myMenu',
        values => [ 'yes', 'no' ],
      );

      $tmpl->param( select_menu => $html );

# DESCRIPTION

This modules creates HTML for form `select` items.

Traditionally, if you wanted to dynamically generate a list of options in a `select` menu, you would either have to use CGI's HTML generation routines, or use a complicated template such as this:

      <select name="day">
      <TMPL_LOOP day>
              <option value="<TMPL_VAR value>" <TMPL_VAR selected>>
                <TMPL_VAR label>
              </option>
            </TMPL_LOOP>
      </select>

This module allows you to quickly prototype a page, allowing the CGI to completely generate the HTML, while allowing you at a later stage to easily change how much HTML it generates.

# INSTALLATION

To install this module, run the following commands:

      perl Makefile.PL
      make
      make test
      make install

Alternatively, to install with Module::Build, you can use the following commands:

      perl Build.PL
      ./Build
      ./Build test
      ./Build install

# METHODS

## `menu()`

Use `menu()` to generate the entire HTML for a select menu.

This allows you to have a very simple template tag, such as:

      <TMPL_VAR select_menu>

`menu()` accepts the following parameters:

name
  This is used in the `select` tag's `name=""` attribute.

  The name value will be run through escapeHTML(), see HTML escaping.

values
  This is an array-ref of values used for each of the `option` tags.

  The values will be run through escapeHTML, see HTML escaping.

default
  This selects which (if any) `option` tag should have a `selected="selected"` attribute.

labels
  This is a hash-ref of values to provide different values for the user-visible label of each `option` tag. Each key should match a value provided by the `values` parameter.

  If this parameter is not provided, or for any `value` which doesn't have a matching key here, the user-visible label will be the `option`'s `value`.

        print menu(
          values => [1, 2],
          labels => {
            1 => 'one'},
            2 => 'two'},
          },
        );

        # will output

        <select name="">
        <option name="1">one</option>
        <option name="2">two</option>
        </select>

  The labels will be run through escapeHTML, see HTML escaping.

attributes
  This is a hash-ref of values to provide extra HTML attributes for the `option` tags. Like the `labels` parameter, the keys should match a value provided by the c<values> parameter.

  Each value of this hash-ref should be a hash-ref representing the name and value of a HTML attribute.

        print menu(
          values     => ['one', 'two'],
          attributes => {
            one => {onSubmit => 'do(this);'},
            two => {style => 'color: #000;'},
          },
        );

        # will output

        <select name="">
        <option onSubmit="do(this);" name="one">one</option>
        <option style="color: #000;" name="two">two</option>
        </select>

  All attribute values (but not the attribute name) will be run through escapeHTML, see HTML escaping.

value
  An alias for `value`.

defaults
  An alias for `default`.

All parameters are optional, though it doesn't make much sense to not provide anything for `values`.

Any unrecognised parameters will be used to provide extra HTML attributes for the `select` tag. For example:

      print menu(
        id       => 'myID',
        values   => ['one'],
        onChange => 'do(this);',
      );

      # will output

      <select name="" id="myID" onChange="do(this);">
      <option name="one">one</option>
      </select>

All attribute values (but not the attribute name) will be run through escapeHTML, see HTML escaping.

## `options()`

Use `options()` to generate the HTML for only the `option` tags, allowing you to keep the outer `select` tag in the template, so that, for example, a designer can easily make changes to the CSS or JavaScript handlers.

You would have something like the following in your template:

      <select name="day">
        <TMPL_VAR menu_options>
      </select>

`options()` accepts the same parameters as menu(), but the `name` parameter is ignored.

## `popup_menu()`

`popup_menu()` is an alias for menu() for those familiar with CGI.

# HTML escaping

If any of the following modules are already loaded into memory, their own escapeHTML (or equivalent) method will be used

CGI
CGI::Simple
HTML::Entities
Apache::Util

Otherwise the following characters will be escaped

      & < > "

# CGI.pm COMPATABILITY

Arguments may be passed as a hash-reference, rather than a hash.
  This allows compile time checking, rather than runtime.

        popup_menu( name => $name );

        # OR
        popup_menu( {name => $name} );

Arguments to the menu(), options() and popup_menu() functions are similar to CGI.pm's, excepting the following differences.

Named arguments should not have a leading dash

        popup_menu( name => $name );

        # NOT
        # popup_menu( -name => $name );

Positional arguments are not supported

        popup_menu( name => $name, labels => \@labels );

        # NOT
        # popup_menu( $name, \@labels );

Attribute names not lowercased
  An argument to CGI.pm's popup_menu such as `-onChange =` 'check()'> will output the HTML `onchange="check()"`.

  This module will retain the case, outputting `onChange="check()"`.

The `optgroup` function is not yet supported

# SUPPORT / BUGS

Please log bugs, feature requests and patch submissions at http://sourceforge.net/projects/html-menu.

Support mailing list: html-menu-users@lists.sourceforge.net

# SEE ALSO

HTML::Menu::DateTime, HTML::Template, Template, Template::Magic, DateTime::Locale.

# AUTHOR

Carl Franks <cpan@fireartist.com>

# CREDITS

      Ron Savage

# COPYRIGHT AND LICENSE

Copyright 2005, Carl Franks. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Licenses are in the files ``Artistic'' and ``Copying'' in this distribution.