CREATING A GROUP OF RELATED CHECKBOXES 

   print $query->checkbox_group(-name=>'group_name',
				-values=>['eenie','meenie','minie','moe'],
				-default=>['eenie','moe'],
				-linebreak=>'true',
				-labels=>\%labels);


   print $query->checkbox_group('group_name',
				['eenie','meenie','minie','moe'],
				['eenie','moe'],'true',\%labels);


   HTML3-COMPATIBLE BROWSERS ONLY:


   print $query->checkbox_group(-name=>'group_name',
				-values=>['eenie','meenie','minie','moe'],
				-rows=2,-columns=>2);

checkbox_group creates a list of checkboxes that are related by the same name.

Parameters:
  • The first and second arguments are the checkbox name and values, respectively (-name and -values). As in the popup menu, the second argument should be an array reference. These values are used for the user-readable labels printed next to the checkboxes as well as for the values passed to your script in the query string.

  • The optional third argument (-default) can be either a reference to a list containing the values to be checked by default, or can be a single value to checked. If this argument is missing or undefined, then nothing is selected when the list first appears.

  • The optional fourth argument (-linebreak) can be set to true to place line breaks between the checkboxes so that they appear as a vertical list. Otherwise, they will be strung together on a horizontal line.

  • The optional fifth argument is a pointer to an associative array relating the checkbox values to the user-visible labels that will will be printed next to them (-labels). If not provided, the values will be used as the default.

  • HTML3-compatible browsers (such as Netscape) can take advantage of the optional parameters -rows, and -columns. These parameters cause checkbox_group to return an HTML3 compatible table containing the checkbox group formatted with the specified number of rows and columns. You can provide just the -columns parameter if you wish; checkbox_group will calculate the correct number of rows for you.

    To include row and column headings in the returned table, you can use the -rowheader and -colheader parameters. Both of these accept a pointer to an array of headings to use. The headings are just decorative. They don't reorganize the interpretation of the checkboxes -- they're still a single named unit.

    • When the form is processed, all checked boxes will be returned as a list under the parameter name 'group_name'. The values of the ``on'' checkboxes can be retrieved with: 

          @turned_on = $query->param('group_name');

    The value returned by checkbox_group is actually an array of button elements. You can capture them and use them within tables, lists, or in other creative ways: 

        @h = $query->checkbox_group(-name=>'group_name',-values=>\@values);
    &use_in_creative_way(@h);

    JAVASCRIPTING: checkbox_group recognizes the -onClick parameter. This specifies a JavaScript code fragment or function call to be executed every time the user clicks on any of the buttons in the group. You can retrieve the identity of the particular button clicked on using the ``this'' variable.