FAQ
HTML_QuickForm_advmultiselect FAQ
- What does it cost ?
- Do you offer support ?
- I found a bug, what shall i do ?
- What is HTML_QuickForm ?
- What is PEAR ?
- May i use HTML_QuickForm_advmultiselect if my browser is no javascript compliant or if javascript is disabled ?
- How to validate a HTML_QuickForm_advmultiselect element ?
- How to optimize javascript code usage on html generated page ?
- My Quickform advmultiselect element is not displayed on my browser window.
- My live counter is not updated with a single select list, when I click on checkboxes ?
- The selected list has one blank entry that you can move to available list
General questions
- What does it cost ?
-
You can download and use it for free. But don't delete the copyright notice. You can read terms of the license.
- Do you offer support ?
-
YES if there is no answer in this Guide and if you are ready to share some informations such as : your configuration (platform Win *nix mac, PHP version, PEAR packages installed) and perharps your script.
- I found a bug, what shall i do ?
-
You can report it with the bug tracker at PEAR.
- What is HTML_QuickForm ?
-
HTML_QuickForm is a PEAR package that provides methods for creating, validating and processing HTML forms.
The purpose of Keith Edmunds tutorial is to give the new users of QuickForm an overview of its features and usage patterns. It describes a small subset of available functionality.
Don't forget to read also the PEAR Manual, HTML_QuickForm related part.
- What is PEAR ?
-
PEAR (an acronym for PHP Extension and Application Repository) is a framework and distribution system for reusable PHP components.
Don't forget to read also the PEAR Manual and PEAR FAQ.
How to
- May i use HTML_QuickForm_advmultiselect if my browser is no javascript compliant or if javascript is disabled ?
-
The dual multi-select won't work, but you can display a single multi select box witch checkboxes. To do so, you have to remove {unselected} placeholder in the advmultiselect template element.
- How to validate a HTML_QuickForm_advmultiselect element ?
-
You must use the HTML_QuickForm addGroupRule() method rather than HTML_QuickForm addRule() method.
- How to optimize javascript code usage on html generated page ?
-
Following answers can be applied only for HTML_QuickForm_advmultiselect version 1.3.0 or better.
Use only once reference of javascript source code. If you have more than one advmultiselect element on your html page, then keep only one call and remove others.
<script type="text/javascript">
<?php
echo $ams1->getElementJs(); // keep one
//echo $ams2->getElementJs(); // remove others
?>
</script>Better solution is to use link to external resource and then reduce amount of javascript source code embedded. Add line of code below between <head> tags of your generated page.
<script type="text/javascript" src="qfamsHandler.js"></script>
Fix path to javascript resource if necessary.
qfamsHandler.jsfile can be found in PEAR/data/HTML_QuickForm_advmultiselect directory.At least remove
{javascript}placeholder if you use default template. You have to set this new one$deftpl, with code something like :<?php
require_once 'HTML/QuickForm.php';
require_once 'HTML/QuickForm/advmultiselect.php';
$form = new HTML_QuickForm('ams130');
// ....
$ams =& $form->addElement('advmultiselect', 'cars', null, $car_array);
$deftpl = '
<table{class}>
<!-- BEGIN label_2 --><tr><th>{label_2}</th><!-- END label_2 -->
<!-- BEGIN label_3 --><th> </th><th>{label_3}</th></tr><!-- END label_3 -->
<tr>
<td valign="top">{unselected}</td>
<td align="center">{add}{remove}</td>
<td valign="top">{selected}</td>
</tr>
</table>
';
$ams->setElementTemplate($deftpl);
//...
?>
Troubleshooting guide
- My Quickform advmultiselect element is not displayed on my browser window.
-
You should have forgotten to add package ressource itself. This operation is mandatory for all external Quickform elements and not necessary for internal elements such as "radio", "checkbox", "text", "button" ...
<?php
require_once 'HTML/QuickForm.php';
require_once 'HTML/QuickForm/advmultiselect.php'; // <-- DO NOT forget it
?>
- My live counter is not updated with a single select list, when I click on checkboxes ?
-
With HTML_QuickForm_advmultiselect version 1.3.0 or better you need to add a chunk of javascript code to initialize onclick event handler of each checkboxes.
<script type="text/javascript" src="qfamsHandler.js"></script> <script type="text/javascript"> window.qfamsName = new Array(); window.qfamsName[0] = 'cars'; window.qfamsName[1] = 'fruit'; window.addEventListener('load', qfamsInit, false); </script>window.qfamsNameis an array what identify each advmultiselect element used on your html page.
- The selected list has one blank entry that you can move to available list
-
This problem comes when you set the selected list (see HTML_QuickForm::setDefaults method) with a wrong data array.
Remember that the available list contains all datas (selected and unselected values). This list is an associative array of "key-code" => "display-value". While selected list is only an array of "key-code".
Suppose we have to retrieve information from a database (with PEAR::DB), and have a simple table for holding user info. This SQL statement creates a table usable under the default database scheme using MySQL:
CREATE TABLE user ( userid VARCHAR(5) NOT NULL, gid INT NOT NULL, affect INT NOT NULL, lastname VARCHAR(50)NOT NULL, firstname VARCHAR(50) NOT NULL, PRIMARY KEY (userid) );
with values :
INSERT INTO user VALUES ('MJ001', 1, 0, 'Martin', 'Jansen'); INSERT INTO user VALUES ('BG001', 1, 1, 'Greg', 'Beaver'); INSERT INTO user VALUES ('CD001', 1, 0, 'Daniel', 'Convissor'); INSERT INTO user VALUES ('LL001', 2, 1, 'Laurent', 'Laville');Column gid identify a user group, while userid identify a single and unique user.
We will initialize AVAILABLE list (on left side if default template) by a db query something like that:
<?php
$queryAll = 'SELECT userid, CONCAT(lastname, " ", firstname) AS useridentity '
. 'FROM user WHERE gid = 1';
?>and get this array:
Array ( [MJ001] => Jansen Martin [BG001] => Beaver Greg [CD001] => Convissor Daniel )We will initialize SELECTED list (on right side if default template) by a db query something like that:
<?php
// Once you have a valid DataBase object named $db ...
$querySel = 'SELECT userid FROM user WHERE gid = 1 AND affect = 1';
$affected_user =& $db->getCol($querySel);
?>and get this array:
Array ( [0] => BG001 )Remember that only a key-code array is necessary, other data will make blank line into select box.
Remains stuff is basic, create the QFAMS element, and load options (available and selected) with the
load()method.<?php
require_once 'HTML/QuickForm.php';
require_once 'HTML/QuickForm/advmultiselect.php';
$form = new HTML_QuickForm('amsDB');
// Once you have a valid QuickForm advmultiselect object named $ams in a QuickForm named $form ...
$ams =& $form->addElement('advmultiselect', 'user',
array('Users:', 'Available', 'Affected'), // labels
null, // datas: "key-code" => "display-value"
array('style' => 'width:200px;') // custom layout
);
$ams->load($db, $queryAll, 'useridentity', 'userid', $affected_user);
// ...
?>You may use the
load()method to set options from :<?php
// ...
// 1. a php array
$all_user = array('MJ001' => 'Martin Jansen',
'BG001' => 'Greg Beaver',
'CD001' => 'Daniel Convissor'
);
$affected_user = array('BG001');
$ams->load($all_user, $affected_user);
// queries to get data
$queryAll = 'SELECT userid, CONCAT(lastname, " ", firstname) AS useridentity '
. 'FROM user WHERE gid = 1';
$querySel = 'SELECT userid FROM user WHERE gid = 1 AND affect = 1';
$affected_user =& $db->getCol($querySel);
// 2. a db result
$all_user =& $db->query($queryAll);
$ams->load($all_user, 'useridentity', 'userid', $affected_user);
// 3. a db query
$ams->load($db, $queryAll, 'useridentity', 'userid', $affected_user);
// ...
?>This example is available in bundle (see examples/qfams_basic_2.php)