Buttons
Introduction
There is two categories of button: sort and swap.
The swap buttons are included since origin, while the sort buttons were included in the 0.5.0 version.
With swap buttons, you will do your selection easily. Select item(s) (one or more), from unselected or selected list, then clic on the add or remove button to move your selection from one list to the other.
You can also double-clic on one item to move it, immediately, to the other list without to clic on the add or remove button.
Since version 1.1.0 you have ability to select or unselect all items in one stroke. You may also toggle a previous selection. This new feature is available through buttons all, none and toggle.
Since version 1.2.0 toggle selection feature is available for both single and dual multi-select boxes.
with one multi-select list, buttons available are only: all, none and toggle.
with two multi-select list, buttons available are only: add, remove, moveup, movedown, all, none and toggle.
Since version 1.5.0, you may add to buttons list : movetop and movebottom.
A full example is given in appendices. See the advanced selection
With sort buttons, you have ability to reorder your selection easily. Select one item then clic on the up or down button to move it to the top or the bottom of your selection.
Order is keep in the $_POST super global array, when the form is submit; Even if you've activated the auto-arrange feature (see
$sortparameter of the HTML_QuickForm_advmultiselect class constructor )
Appearance
There is two kinds of button: text and image. These are the standard html buttons we can find in a form. Default appearance is text but you can also easily use image layout. Here is how to do :
<?php
$ams->setButtonAttributes('add', array('type' => 'image', 'src' => '/img/add.png'));
$ams->setButtonAttributes('remove', array('type' => 'image', 'src' => '/img/remove.png'));
?>
Of course, all images are supported: PNG, GIF ...
If the image file does not exist, you will get the internal text value as output without nothing else.
Remember that defaults are: "
>>" for add button, and "<<" for remove button.
Attributes
In version 0.4.0, there were only the basic add and remove buttons. In version 0.5.0, two new buttons were added: moveup and movedown. In version 1.1.0, three new buttons were added: all, none, and toggle. In version 1.5.0, two new buttons were added: movetop and movebottom.
Any other button identifier than add, remove, all, none, toggle, moveup, movedown, movetop, movebottom will throws a PEAR_Error.
Only five attributes may be set, with these four button identifiers; they are:
-
name -
The form input button name. Default are: 'add', or 'remove', or 'all, or 'none', or 'toggle', or 'up', or 'down', or 'top', or 'bottom'.
Default values of the name attribute are not equivalent to button identifiers.
-
value -
The form input button text. Default are : ' >> ', or ' << ', or ' Select All ', or ' Select None ', or ' Toggle Selection ', or ' Up ', or ' Down ', or ' Top ', or ' Bottom '.
-
type -
The form input button kind. Default is 'button' (Can be either 'button' or 'image').
-
class -
A CSS class identifier in one of your stylesheets.
-
src -
URL of the image file used.