Chapter 2. FAQ - Frequently Asked Questions

2.1. General questions

2.1.1. What does it cost ?
2.1.2. Do you offer support ?
2.1.3. I found a bug, what shall i do ?
2.1.4. What is HTML_QuickForm ?
2.1.5. What is PEAR ?

2.2. How to

2.2.1. May i use HTML_QuickForm_advmultiselect if my browser is no javascript compliant or if javascript is disabled ?
2.2.2. How to validate a HTML_QuickForm_advmultiselect element ?
2.2.3. How to optimize javascript code usage on html generated page ?

2.3. Troubleshooting guide

2.3.1. My Quickform advmultiselect element is not displayed on my browser window.
2.3.2. My live counter is not updated with a single select list, when I click on checkboxes ?
2.3.3. The selected list has one blank entry that you can move to available list

2.1. General questions

2.1.1. What does it cost ?
2.1.2. Do you offer support ?
2.1.3. I found a bug, what shall i do ?
2.1.4. What is HTML_QuickForm ?
2.1.5. What is PEAR ?

2.1.1.

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

2.1.2.

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.

2.1.3.

I found a bug, what shall i do ?

You can report it with the bug tracker at PEAR.

2.1.4.

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.

2.1.5.

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.

2.2. How to

2.2.1. May i use HTML_QuickForm_advmultiselect if my browser is no javascript compliant or if javascript is disabled ?
2.2.2. How to validate a HTML_QuickForm_advmultiselect element ?
2.2.3. How to optimize javascript code usage on html generated page ?

2.2.1.

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.

2.2.2.

How to validate a HTML_QuickForm_advmultiselect element ?

You must use the HTML_QuickForm addGroupRule() method rather than HTML_QuickForm addRule() method. See Template usage example.

2.2.3.

How to optimize javascript code usage on html generated page ?

	Caution
	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>

	Note
	Fix path to javascript resource if necessary. `qfamsHandler.js` file 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}>
<tr><th>{label_2}</th>
<th> </th><th>{label_3}</th></tr>
<tr>
<td valign="top">{unselected}</td>
<td align="center">{add}{remove}</td>
<td valign="top">{selected}</td>
</tr>
</table>
';
$ams->setElementTemplate($deftpl);
//...
?>

2.3. Troubleshooting guide

2.3.1. My Quickform advmultiselect element is not displayed on my browser window.
2.3.2. My live counter is not updated with a single select list, when I click on checkboxes ?
2.3.3. The selected list has one blank entry that you can move to available list

2.3.1.

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
?>

2.3.2.

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.qfamsName is an array what identify each advmultiselect element used on your html page.

2.3.3.

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
)

	Caution
	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 QF/select element 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);
// ...
?>

Tip

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);
// ...
?>

	Note
	This example is available in bundle (see examples/qfams_basic_2.php)

Prev	Up	Next
Why use HTML_QuickForm_advmultiselect ?	Home	Chapter 3. What's New ?

HTML_QuickForm_advmultiselect : The Definitive Guide