SelectLayers(3pm)

💖 SelectLayers — the HTML::Widgets::SelectLayers page, but make it cute

okay so. SelectLayers(3pm) is a page from the User Contributed Perl Documentation section, and bestie, it is giving 2006 in the best way. Let's get into it. 🦋

---

✨ NAME ✨

HTML::Widgets::SelectLayers — a Perl extension for selectable HTML layers. (yes. layers. like tabs but spookier. we love her. 💅)

---

🌸 SYNOPSIS 🌸

look, the vibes are impeccable, just copy the ritual exactly:

  use HTML::Widgets::SelectLayers;

  use Tie::IxHash;
  tie my %options, 'Tie::IxHash',
    'value'  => 'Select One',
    'value2' => 'Select Two',
  ;

  $widget = new HTML::Widgets::SelectLayers(
    'options'       => \%options,
    'form_name'     => 'dummy',
    'form_action'   => 'process.cgi',

    #new code auto-detects form types (radio not yet supported)
    #'form_elements' => [ qw( textfield1 textfield2 checkbox1 radio1 select1 ) ],
    'form_elements' => [ qw( textfield1 textfield2 checkbox1 radio1 select1 ) ],

    #deprecated style still works for now
    #'form_text'     => [ qw( textfield1 textfield2 ) ],
    #'form_checkbox' => [ qw( checkbox1 ) ],
    #'form_radio'    => [ qw( radio1 ) ],
    #'form_select'   => [ qw( select1 ) ],

    'layer_callback' => sub {
      my $layer = shift;
      my $html = qq!<INPUT TYPE="hidden" NAME="layer" VALUE="$layer">!;
      $html .= $other_stuff;
      $html;
    },
  );

  print '<FORM NAME=dummy STYLE="margin-top: 0; margin-bottom: 0">'.
        '<INPUT TYPE="text" NAME="textfield1">'.
        '<INPUT TYPE="text" NAME="textfield2">'.
        '<INPUT TYPE="checkbox" NAME="checkbox1" VALUE="Y">'.
        $widget->html;

note the lil comments in there, they're literally doing lore drops: form_elements auto-detects form types (radio not yet supported btw 💀) and the form_text / form_checkbox / form_radio / form_select style is deprecated but still works for now. okayyy.

---

💜 DESCRIPTION 💜

so this module builds an HTML widget that has multiple layers, and only one layer is visible at any given time, and the one in charge of swapping them is a <SELECT> box. iconic honestly. there's a live example at http://www.420.am/selectlayers/ if you wanna vibe-check it.

the HTML this module generates uses JavaScript, but it nevertheless attempts to be as cross-browser as possible 🫶. the 0.05 release drops Navigator 4 compatibility, and it's been tested under Mozilla Firefox 1.0.6, MSIE 6.0, Konqueror 3.3.2, and Opera 8.0.2. and a 2006 note for the historians among us: still working under newer browsers such as IE7, Firefox 2.0, etc. no cap.

---

🎀 FORMS 🎀

okay so here's the drama. the author's understanding is that forms cannot span <DIV>s elements. so the generated HTML puts a </FORM> tag before the layers, and then generates <FORM> and </FORM> tags for each layer 🌈.

to facilitate <SUBMIT> buttons living inside the layers, you can pass a form name and element names, and the relevant values get copied to the layer's form. see the form_ options down below 👇

---

👑 METHODS 👑

new KEY, VALUE, KEY, VALUE...

options come in as name/value pairs, like a little group chat of settings:

• options — hash reference of layers and labels for the <SELECT>. peep Tie::IxHash if you wanna control the ordering. in HTML it becomes: <OPTION VALUE="$layer">$label</OPTION>
• layer_callback — subroutine reference to create each layer. the layer name is passed as an option in @_.
• selected_layer — (optional) the initially selected layer.
• form_name — (optional) form name to copy values from. if it's not supplied, no values will be copied. periodt.
• form_action — form action.
• form_elements — (optional) array reference of form fields to copy from the form_name form. field type is autodetected; right now text, hidden, checkbox, and select fields are supported. radio fields are not yet supported, sorry babes 😭
• form_text — (optional) array reference of text (or hidden) form fields to copy from the form_name form.
• form_checkbox — (optional) array reference of checkbox form fields to copy from the form_name form.
• form_radio — (optional) array reference of radio form fields to copy from the form_name form.
• form_select — (optional) array reference of select form fields to copy from the form_name form.
• fixup_callback — (optional) subroutine reference, returns supplimentary JavaScript for the function described above under FORMS.
• size — (optional) size of the <SELECT>, default 1.
• unique_key — (optional) prepended to all JavaScript function/variable/object names to avoid namespace collisions. main character energy for your namespace 🧚
• html_beween — (optional) HTML between the <SELECT> and the layers. (yes it's spelled html_beween. it's canon. we respect it. 🙈)
• under_position — (optional) specifies the positioning of any HTML appearing after the widget.
  • static — the default. positions subsequent HTML underneath the current layer (or immediately under the select box if no layer has yet been selected), reflowing when layers are changed.
  • absolute — calculates the size of the largest layer and keeps the subsequent HTML in a single position underneath it. note that absolute works by positioning subsequent HTML in a <DIV>, so you should probably close it yourself with a </DIV> before your </HTML> end tag. absolute is a bit experimental and might have some quirks with truncating the end of the page under IE; you might have better results by just making all your layers the exact same size at the moment. 💀

lowkey a warning: that absolute mode is experimental and IE might truncate the end of your page. you've been told, bestie.

html

returns HTML for the widget. that's it, that's the whole job ✨

---

🫶 AUTHOR 🫶

Ivan Kohler <ivan-selectlayers@420.am> — the icon, the legend.

---

💖 COPYRIGHT 💖

Copyright (c) 2002-2005 Ivan Kohler All rights reserved. this program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

💀 BUGS 💀

• JavaScript
• all the different form_* options are unnecessary, could use .type to auto-sense
• could give you a function or something for copying variables out of the layered forms

ngl, that's a very chill bug list. the author is basically like "yeah I know. anyway." 😌

---

🌈 SEE ALSO 🌈

perl. Tie::IxHash, http://www.xs4all.nl/~ppk/js/dom.html, http://javascript.about.com/library/scripts/blsafeonload.htm

---

and that's the whole page, bestie 💅 this one's perl v5.36.0, dated 2022-10-15, and it's the SelectLayers(3pm) page from the User Contributed Perl Documentation. mwah. 🎀✨