view release on metacpan or  search on metacpan

lib/HTML/Menu/Select.pm  view on Meta::CPAN

package HTML::Menu::Select;
use 5.004;
use strict;
use Carp 'carp';

our $VERSION = '1.01';

require Exporter;
our @ISA = qw( Exporter );

our @EXPORT_OK = qw(
 options menu popup_menu
 );

our %EXPORT_TAGS = ( all => \@EXPORT_OK );

our @KNOWN_KEYS = qw( 
  name value values default defaults labels attributes size multiple override );


sub popup_menu { &menu };

sub menu {
  my %arg  = (ref $_[0]) ? %{$_[0]} : @_;
  my $html = '';
  
  $arg{name} = '' if not exists $arg{name};
  
  $html = sprintf '<select name="%s"', _escapeHTML( $arg{name} );
  
  for my $key (keys %arg) {
    if (! grep {$key eq $_} @KNOWN_KEYS) {
      $html .= sprintf ' %s="%s"', $key, _escapeHTML( $arg{$key} );
    }
  }
  
  $html .= ">\n";
  $html .= options(%arg);
  $html .= "</select>\n";
  
  return $html;
}


sub options {
  my %arg  = (ref $_[0]) ? %{$_[0]} : @_;
  my $html  = '';
  
  # aliases
  for (qw/ value default /) {
    $arg{$_} = $arg{"${_}s"} 
      if exists $arg{"${_}s"};
    
    $arg{$_} = [$arg{$_}]
      if exists $arg{$_} && ! ref $arg{$_};
  }
  
  # don't support CGI.pm's 'override' argument
  if (exists $arg{override}) {
    carp "CGI.pm's 'override' argument is not supported by HTML::Menu::Select";
  }
  
  for my $option (@{ $arg{value} }) {
    $html .= '<option ';
    
    for my $default (@{ $arg{default} }) {
      if ($option eq $default) {
        $html .= 'selected="selected" ';
      }
    }
    
    for my $att (keys %{ $arg{attributes} }) {
      if ($att eq $option) {
        for (keys %{ $arg{attributes}{$att} }) {
          $html .= sprintf '%s="%s" ', 
                           $_, 
                           _escapeHTML( $arg{attributes}{$att}{$_} );
        }
      }
    }
    

lib/HTML/Menu/Select.pm  view on Meta::CPAN

    },
  );
  
  # 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 L<"HTML escaping">.

=item value

An alias for C<value>.

=item defaults

An alias for C<default>.

=back

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

Any unrecognised parameters will be used to provide extra HTML 
attributes for the C<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 L<"HTML escaping">.

=head2 options()

Use C<options()> to generate the HTML for only the C<option> tags, 
allowing you to keep the outer C<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>

C<options()> accepts the same parameters as L<"menu()">, but the C<name> 
parameter is ignored.

=head2 popup_menu()

C<popup_menu()> is an alias for L<"menu()"> for those familiar with 
CGI.

=head1 HTML escaping

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

=over

=item CGI

=item CGI::Simple

=item HTML::Entities

=item Apache::Util

=back

Otherwise the following characters will be escaped

  & < > "

=head1 CGI.pm COMPATABILITY

=over

=item 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} );

=back

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

=over

=item Named arguments should not have a leading dash

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

=item Positional arguments are not supported

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

=item Attribute names not lowercased

An argument to CGI.pm's popup_menu such as C<-onChange => 'check()'> will 
output the HTML C<onchange="check()">.

This module will retain the case, outputting C<onChange="check()">.

=item The C<optgroup> function is not yet supported

=back

=head1 SUPPORT / BUGS

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

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

=head1 SEE ALSO

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

=head1 AUTHOR

Carl Franks <cpan@fireartist.com>

=head1 CREDITS

  Ron Savage

=head1 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.

=cut