File: array2combo.userguide.txt

ARRAY2COMBO USER GUIDE

Last modified: 24/02/2003
PHP class, creates HTML comboboxes from monodimensional arrays
Copyright (C) 2003 Gerosa Stefano (gerry_at_gerry_dot_it)

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details.

GNU home page: http://www.gnu.org
To contact author, please use this form:
http://www.gerry.it/serve/mail/

GENERAL DESCRIPTION

The aim of this class is to easily create a combobox/listbox taking data from a monodimensional array.
Values will be automatically escaped to match html specifications, according to php internal functions htmlentities and htmlspecialchars

USAGE

CREATING CLASS

$classref = new array2combo($name,$data,$size,$type,$sel,$attr)

Data can be setted during class creation or later using function set_data, with the same params as class constructor. However Select name is required during class creation.
It can be changed later, if needed, with set_data() method. 
Data is always required when calling set_data().

Parameters meanings:

- $name (required)
SELECT object name: <select name="$name">

- $data ($required)
Array with the data to show

- $size
Size of SELECT, in HTML is usually used to determine if browser should show a listbox ($size=1) or a combobox ($size > 1). If size is > 1 combobox will show $size elements, providing scrollbars if there are more.
Defalut value is 1, so a listbox is showed if no value is provided.
Please note that this param is converted to an unsigned int before usage, so other values will be converted.

- $type
combo can be created in 3 different ways, according to this setting.
If it equals to 0, only values of array are considered, they are assigned both to value and label of OPTION tag.
<OPTION value="arrvalue">arrvalue</OPTION>
If it's more than 0,  keys are assigned to OPTION value and corresponding values are assigned to OPTION label
<OPTION value="arrkey">arrvalue</OPTION>
If it's less than zero, key and values are swapped.
<OPTION value="arrvalue">arrkey</OPTION>
Default is 0

- $sel 
If it's not false (according to PHP concept of 'false'), a simple comparison is performed on every item to determine if item should be 'selected'.
Item is 'selected' if $sel matches (==) item value, intending the one which is placed in value attribute of OPTION. This means it changes according to $type assignation.
However this method provide a very poor comparison. It has been created to be overridden by user, who can create a more appropriate method to match his needings. (See OVERRIDE check_selected($value,$label) METHOD to a more complex explanation)
Defalut is false

- $attr
A string included into SELECT element, in order to provide customizations such as assigning CSS class or id, events handling with javascript and other such things.
Be aware that this string is not escaped in any way.
Default is empty string

OUTPUTTING RESULT

Class returs the compiled combo as a string, when calling the output() method.
Be aware that combo is not recalculated every time you call output(), instead is cached the first time you call it and then cache is returned if needed. However cache is cleared every time you call set_data() method.
So changing data values directly into the object may not change the final output if it has been calculated earlier.

OVERRIDING check_selected($value,$label) METHOD

check_selected($value,$label) method returns a string which is directly placed into OPTION tag.
Thus it can decide if an option should be 'selected' or not.
It can (and should) be overridden, if a custom selection is needed.
Method accepts (and so overriden method must do) two arguments, $value and $label. $value is the value which will be placed in OPTION tag (value="") while $label is the one which will be inserted into OPTION label, <OPTION>label</OPTION>.
They will correspond to data array, according to $type setting of object.
Method should return a string which is directly placed into OPTION tag, thus is also possible to use this method to provide other features such as custom style for any option.
Be aware that this method is only called when the $sel param is true, so remember to do this if you want to enable your method


##################################################

CLASS ARRAY2COMBO_PREDEF

This class in an array2combo extension, provides some predefinited data structure that can be generally useful such as date structures.
It must be inizialized the same way as array2combo, except $data, $type and $sel which are setted internally.
Instead of calling the output() method you can call those methods:

- predef_mon_day($sel=0,$limit=31)
Returns a combo with the days from 01 to 31, it's also possible to limit days using $limit param.
if $sel is true tries to select current day

- predef_mon_num($sel=0)
Returns a combo with a numerical representation of months, from 01 to 12.
Months are in numerical flavour, both in OPTION value and label
If sel is true it will select current month

- predef_mon_ita($sel=0)
- predef_mon_en($sel=0)
Indentical to predef_mon_num($sel=0) except that OPTION labels are setted to textual representation of months, in italian language (predef_mon_ita) or english language (predef_mon_en).
OPTION values are always numeric.

- predef_year($from,$to,$sel=0)
A combo representing a range of years from $from to $to. If $to is less than $from empty string is returned.
if $sel is true tries to select current year