| core_html

# Class: Bs_FormFieldSelect Source Location: /core/html/form/Bs_FormFieldSelect.class.php
### Class Overview
    Bs_Object
       |
       --Bs_FormElement
          |
          --Bs_FormField
             |
             --Bs_FormFieldSelect
SELECT Form Field Class #### Author(s): andrej arn <at blueshoes dot org> #### Version: 4.3.$Revision: 1.6 $ $Date: 2003/10/29 17:48:39 $ #### Copyright: blueshoes.org | ### Variables $flipFlopObjName $flipFlopSettings $multiple $optionsEval $optionsHard $optionsType $size $useFlipFlop | ### Methods Bs_FormFieldSelect getField getOptionStringForValue inputManipulate inputValidate validateMaxLength validateMinLength _prepareOptions
### Child classes: Bs_FormFieldSelectImage IMAGE SELECT Form Field Class Bs_DaFormFieldComboBox DomApi ComboBox Form Field Class Bs_DaFormFieldListBox DomApi ListBox Form Field Class Bs_FormFieldChVisa CH Visa Select Form Field Class Bs_FormFieldCountryList Country List Select Form Field Class | ### Inherited Variables #### Class: Bs_FormField Bs_FormField::$additionalCheck Bs_FormField::$additionalTags Bs_FormField::$advancedStyles Bs_FormField::$bsDataInfo Bs_FormField::$bsDataManipulation Bs_FormField::$bsDataManipVar Bs_FormField::$bsDataType Bs_FormField::$case Bs_FormField::$codePostLoad Bs_FormField::$codePostManipulate Bs_FormField::$codePostReceive Bs_FormField::$dbAttributes Bs_FormField::$dbAutoIncrement Bs_FormField::$dbDataType Bs_FormField::$dbFieldName Bs_FormField::$dbForeignKey Bs_FormField::$dbIndexFulltext Bs_FormField::$dbKey Bs_FormField::$dbNotNull Bs_FormField::$dbPrimaryKey Bs_FormField::$dbUnique Bs_FormField::$defaultErrorMessage Bs_FormField::$direction Bs_FormField::$editability Bs_FormField::$enforce Bs_FormField::$equalTo Bs_FormField::$errorMessage Bs_FormField::$errorType Bs_FormField::$events Bs_FormField::$explodeEval Bs_FormField::$fieldType Bs_FormField::$isUsed Bs_FormField::$level Bs_FormField::$maxLength Bs_FormField::$minLength Bs_FormField::$must Bs_FormField::$mustBeUnique Bs_FormField::$mustContain Bs_FormField::$mustEndWith Bs_FormField::$mustIf Bs_FormField::$mustOneOf Bs_FormField::$mustOneOfIf Bs_FormField::$mustStartWith Bs_FormField::$notContain Bs_FormField::$notEndWith Bs_FormField::$notEqualTo Bs_FormField::$notStartWith Bs_FormField::$onEnter Bs_FormField::$onlyIf Bs_FormField::$onlyOneOf Bs_FormField::$onlyOneOfIf Bs_FormField::$regularExpression Bs_FormField::$remove Bs_FormField::$removeI Bs_FormField::$replace Bs_FormField::$replaceI Bs_FormField::$saveToDb Bs_FormField::$styles Bs_FormField::$trim Bs_FormField::$valueDefault Bs_FormField::$valueDefaultType Bs_FormField::$valueDisplay Bs_FormField::$valueInternal Bs_FormField::$valueReceived Bs_FormField::$_Bs_String Bs_FormField::$_explodeArray Bs_FormField::$_must #### Class: Bs_FormElement Bs_FormElement::$accessRights Bs_FormElement::$caption Bs_FormElement::$container Bs_FormElement::$elementLayout Bs_FormElement::$elementStringFormat Bs_FormElement::$elementType Bs_FormElement::$FormID Bs_FormElement::$hideCaption Bs_FormElement::$name Bs_FormElement::$orderId Bs_FormElement::$persister Bs_FormElement::$persisterID Bs_FormElement::$persisterVarSettings Bs_FormElement::$visibility Bs_FormElement::$_form | ### Inherited Methods #### Class: Bs_FormField Bs_FormField::Bs_FormField() Constructor. Bs_FormField::addEnforceCheckbox() add enforce checkbox if needed. Bs_FormField::applyOnEnterBehavior() merges the onEnter javascript call into the events array if needed. Bs_FormField::getAdvancedStyle() returns the advanced style for the given key. Bs_FormField::getAdvancedStyleHelper() returns the advanced style for the field itself or the caption, taking the current mode into account. Bs_FormField::getCaption() Return the caption string (for the current language). Bs_FormField::getCaptionForFormOutput() returns the caption string to use in the form output. so expect html here and not plaintext. Bs_FormField::getDbDataType() returns the db datatype to use for this field. Bs_FormField::getDbFieldName() returns the db field name you should use for this field. Bs_FormField::getElement() Return some html code to display all the exploded fields on a website in a form. Bs_FormField::getError() returns the error message for the current field, or an empty string if no error. Bs_FormField::getErrorMessage() returns a textual error message for the given error type. Bs_FormField::getField() overwrite this method in your subclass. Bs_FormField::getFieldAsHidden() Return some html code to send to the client. same as getField() but returns the field like a hidden field, no matter what field type it is. Bs_FormField::getHelp() returns the help text Bs_FormField::getLabel() Return the label tag (for the current language). Bs_FormField::getOnEnterBehavior() tells how this form field should behave when the user hits enter. Bs_FormField::getOnEnterCode() returns some javascript code (the call) to behave the way the coder wants. Bs_FormField::getValue() returns the value. Bs_FormField::hasJavascript() tells whether the client browser has javascript support or not. Bs_FormField::inputManipulate() manipulate the user inputs according to the object vars. Bs_FormField::inputValidate() validate the user inputs according to the object vars. Bs_FormField::isExplodable() tells if this is an explodable field. Bs_FormField::isFilledIn() tells if the user filled in this field *somehow*. does not tell if the input was ok/accepted. Bs_FormField::isMust() tells if the field has to be filled in according to the current settings. Bs_FormField::postManipulateTrigger() gets called after the user input has been set to the form fields, and the needed automatic manipulations have been done. Bs_FormField::postReceiveTrigger() gets called right after the user input has been set to the form fields. Bs_FormField::setExplode() explode this field into multiple ones? Bs_FormField::shouldPersist() tells if the received value should be persisted (used) this time. Bs_FormField::unpersistTrigger() gets executed automatically in some circumstances: by the ObjPersister. read there for more info. Bs_FormField::validateAdditionalCheck() additionalCheck Bs_FormField::validateDataType() bsDataType/bsDataInfo Bs_FormField::validateEqualTo() equalTo Bs_FormField::validateMaxLength() checks the maxLength case. Bs_FormField::validateMinLength() checks the minLength case. Bs_FormField::validateMust() must Bs_FormField::validateMustBeUnique() checks the mustBeUnique case. the check is made non-case-sensitive. Bs_FormField::validateMustContain() mustContain Bs_FormField::validateMustEndWith() mustEndWith Bs_FormField::validateMustStartWith() mustStartWith Bs_FormField::validateNotContain() notContain Bs_FormField::validateNotEndWith() notEndWith Bs_FormField::validateNotEqualTo() notEqualTo Bs_FormField::validateNotStartWith() notStartWith Bs_FormField::validateOnlyIf() onlyIf Bs_FormField::validateOnlyOneOf() onlyOneOf Bs_FormField::validateRegularExpression() regularExpression #### Class: Bs_FormElement Bs_FormElement::Bs_FormElement() Constructor. Bs_FormElement::getCaption() Return the caption string (for the current language). Bs_FormElement::getCaptionForFormOutput() returns the caption. here in Bs_FormElement it's the same getCaption() but in Bs_FormField which overwrites these methods it makes a difference. Bs_FormElement::getElement() Return some html code to display the element on a website in a form. Bs_FormElement::getElementLayout() returns the layout string for this element. Bs_FormElement::getLanguageDependentValue() returns the value of a [language dependant] [object] var for the current or given language. Bs_FormElement::getLevel() returns the level this element belongs to. Bs_FormElement::getVisibility() returns how this field/element should be visible and editable to the user. Bs_FormElement::hasFormObject() tells if we have a reference to a form object where we can grab some information. Bs_FormElement::setFormObject() set a reference to a form object. #### Class: Bs_Object Bs_Object::Bs_Object() Bs_Object::getErrors() Basic error handling: Get *all* errors as string array from the global Bs_Error-error stack. Bs_Object::getLastError() Basic error handling: Get last error string from the global Bs_Error-error stack. Bs_Object::getLastErrors() Basic error handling: Get last errors string array from the global Bs_Error-error stack sinc last call of getLastErrors(). Bs_Object::persist() Persists this object by serializing it and saving it to a file with unique name. Bs_Object::setError() Basic error handling: Push an error string on the global Bs_Error-error stack. Bs_Object::toHtml() Dumps the content of this object to a string using PHP's var_dump(). Bs_Object::toString() Dumps the content of this object to a string using PHP's var_dump(). Bs_Object::unpersist() Fetches an object that was persisted with persist()
### Class Details [line 61] SELECT Form Field Class
     example tag:

     what's special about this tag?
       alot is different to a text field for example.
       - value     => the real value can be different from the visible value.
       - value     => multiple values can be selected.
       - size      => how large the select field should be displayed. needs to be >1 for multiple.
       - multiple  => if more then one value can be selected. size needs to be set and >1.
       - events    => does not support the usual 14 events, only 'onBlur', 'onFocus' and 'onChange'
                      (2001/05/01)
       - all the following object vars are of no use and thus ignored (mainly because the user
         cannot change the values at all, he can only select them):
          - bsDataType         - mustContain
          - bsDataInfo         - notContain
          - minLength          - mustBeUnique
          - [maxLength]        - regularExpression
          - mustStartWith      - trim
          - notStartWith       - remove
          - mustEndWith        - replace
          - notEndWith         - case
       - options
         the options that are selectable for the user.
       - valueDefault
         the following data structores are allowed:
           array('1'=>'one', '2'=>'two', '3'=>'three');
           array('en'=>array('1'=>'one','2'=>'two','3'=>'three'), 'de'=>array('1'=>'eins','2'=>'zwei','3'=>'drei'), 'fr'=>array('1'=>'un','2'=>'deux','3'=>'trois'));
         while these are not:
           'one';
           array('one', 'two', 'three');
           array('en'=>'one', 'de'=>'eins', 'fr'=>'un');
           array('en'=>array('one','two','three'), 'de'=>array('eins','zwei','drei'), 'fr'=>array('un','deux','trois'));
         because it would not be possible to know the difference sometimes.
         this means: even if you have only one default value, it must be an array. and you always
         need key=>val, even if the key and the value is the same.
no dependencies here. #### Tags:
copyright: | blueshoes.org
pattern: | singleton: (pseudostatic)
access: | public
version: | 4.3.$Revision: 1.6 $ $Date: 2003/10/29 17:48:39 $
author: | andrej arn <at blueshoes dot org>
[ Top ] ### Class Variables #### $flipFlopObjName = [line 193] the name of the flipflop instance. if not specified then something will be made up. #### Tags:
since: | bs4.5
see: | vars $useFlipFlop, Bs_FormFieldSelect::$flipFlopSettings
access: | public
Type: | string
[ Top ] #### $flipFlopSettings = [line 184] for detals see the javascript class: Bs_FlipFlop.class.js
     hash with the following keys:
       fieldAvailableCssClass
       fieldSelectedCssClass
       textAvailable
       textAvailableCssClass
       textSelected
       textSelectedCssClass
       showCaptionLine
       captionLineClass
       moveOnDblClick
       moveOnClick
       maxSelectedNumber
       maxSelectedWarning

       buttonSelectAll and buttonDeselectAll:
         can be set to false, which means they won't be used.
         not more customization for these yet.
#### Tags:
since: | bs4.5
see: | vars $useFlipFlop, Bs_FormFieldSelect::$flipFlopObjName
access: | public
Type: | array
[ Top ] #### $multiple = [line 83] if the user is able to select multiple values, not just one. $size needs to be >1 then. if not set it's FALSE. you can make this field use the js flipflop component. see $useFlipFlop. #### Tags:
see: | var $useFlipFlop
access: | public
Type: | bool
[ Top ] #### $optionsEval = [line 143] php code to be evaluated. has to return an array (hash or vector) that will be used for the option tags of this select field. the code is executed in $this->_prepareOptions() so it's in the scope of a method of this object. this means you can use vars from here etc. language dependant. ya know what i mean. #### Tags:
see: | Bs_FormFieldSelect::_prepareOptions(), var $optionsType, var $optionsHard, var $_options
access: | public
Type: | mixed
[ Top ] #### $optionsHard = [line 129] the options that are selectable for the user.
         the following data structures are allowed:
           array('1'=>'one', '2'=>'two', '4'=>'four');
           array('en'=>array('1'=>'one','2'=>'two','3'=>'three'), 'de'=>array('1'=>'eins','2'=>'zwei','3'=>'drei'), 'fr'=>array('1'=>'un','2'=>'deux','3'=>'trois'));
         while these are not:
           'one';
           array('one', 'two', 'three');
           array('en'=>'one', 'de'=>'eins', 'fr'=>'un');
           array('en'=>array('one','two','three'), 'de'=>array('eins','zwei','drei'), 'fr'=>array('un','deux','trois'));
         because it would not be possible to know the difference sometimes.
         this means: even if you have only one default value, it must be an array.
WARNING: you always need key=>val, even if the key and the value is the same. you can use Bs_Array->copyValuesToKeys() to work around this. #### Tags:
see: | Bs_FormFieldSelect::_prepareOptions(), var $optionsType, var $optionsEval, var $_options
access: | public
Type: | array
[ Top ] #### $optionsType = [line 96] how to fill in the option tags for this select field. one of 'eval' or 'hard'. if not set, the one var that is used is used :) if both are used (speaking of $optionsHard and $optionsEval) then $optionsHard is the default. #### Tags:
see: | Bs_FormFieldSelect::_prepareOptions(), var $optionsHard, var $optionsEval, var $_options
access: | public
Type: | string
[ Top ] #### $size = [line 71] how large the select field should be displayed. needs to be >1 for multiple. if not set it won't be written to the client, which equals to a value of '1'. #### Tags:
access: | public
Type: | int
[ Top ] #### $useFlipFlop = FALSE [line 154] for detals see the javascript class: Bs_FlipFlop.class.js #### Tags:
since: | bs4.5
see: | vars $flipFlopSettings, Bs_FormFieldSelect::$flipFlopObjName
access: | public
Type: | bool
[ Top ] ### Class Methods ### constructor Bs_FormFieldSelect [line 199]
`Bs_FormFieldSelect Bs_FormFieldSelect( )`
Constructor. [ Top ] ### method getField [line 222]
`string &getField( [bool $addEnforceCheckbox = TRUE])`
Returns some html code to display the field on a website in a form. overwrites parent method. #### Tags:
return: | some html code
see: | $this->getFieldAsHidden(), $this->addEnforceCheckbox()
access: | public
Overridden in child classes as: Bs_FormFieldSelectImage::getField() Returns some html code to display the field on a website in a form. Bs_DaFormFieldComboBox::getField() Return some html code to display the field on a website in a form. Bs_DaFormFieldListBox::getField() Return some html code to display the field on a website in a form. Overrides Bs_FormField::getField() (overwrite this method in your subclass.) #### Parameters:
bool | $addEnforceCheckbox | default is TRUE. adds the enforce checkbox automatically, if needed. see (parent::)addEnforceCheckbox().
[ Top ] ### method getOptionStringForValue [line 400]
`string getOptionStringForValue( mixed $value, [string $lang = null])`
returns the displayed value for an internal value. example: you have <option value="ca">Canada</option> getOptionStringForValue('ca') returns 'Canada'. BIG NOTE: this method is (and should be) identical in Bs_FormFieldRadio and Bs_FormFieldSelect. #### Tags:
access: | public
#### Parameters:
mixed | $value | (string or so)
string | $lang | (...)
[ Top ] ### method inputManipulate [line 448]
`void inputManipulate( )`
overwrite parent method cause we don't want to manipulate anything here. #### Tags:
todo: | use $paramValue, see Bs_FormField->inputManipulate()
access: | public
Overrides Bs_FormField::inputManipulate() (manipulate the user inputs according to the object vars.) [ Top ] ### method inputValidate [line 471]
`mixed inputValidate( [mixed $paramValue = NULL])`
validate the user inputs according to the object vars. overwrites parent method. read manual there. additional information: the order for data validation is: (-- means check omitted here)
       1) must         5) --mustStartWith     9) --mustContain    13) --mustBeUnique
       2a) onlyOneOf   6) --notStartWith     10) --notContain     14) --regularExpression
       2b) onlyIf
       3) minLength    7) --mustEndWith      11) --equalTo
       4) maxLength    8) --notEndWith       12) --notEqualTo
#### Tags:
access: | public
Overrides Bs_FormField::inputValidate() (validate the user inputs according to the object vars.) #### Parameters:
mixed | $paramValue | (only used internally!!!)
[ Top ] ### method validateMaxLength [line 537]
`mixed validateMaxLength( mixed &$v, int &$vLength)`
checks the maxLength case. overwrites parent method. for a select field the maxLength has another meaning. it's the number of max. selectable elements. if it doesn't have the 'multiple' property the setting is ignored. #### Tags:
return: | (bool)TRUE if ok, (string)error message if not.
see: | var $maxLength
access: | public
Overrides Bs_FormField::validateMaxLength() (checks the maxLength case.) #### Parameters:
mixed | &$v | (the value the user submitted, should be a string here)
int | &$vLength | the length of $v. this way we don't have to do strlen() again.
[ Top ] ### method validateMinLength [line 515]
`mixed validateMinLength( mixed &$v, int &$vLength)`
checks the minLength case. overwrites parent method. for a select field the minLength has another meaning. it's the number of min. selectable elements. if it doesn't have the 'multiple' property the setting is ignored. #### Tags:
return: | (bool)TRUE if ok, (string)error message if not.
see: | var $minLength
access: | public
Overrides Bs_FormField::validateMinLength() (checks the minLength case.) #### Parameters:
mixed | &$v | (the value the user submitted, should be a string here)
int | &$vLength | the length of $v. this way we don't have to do strlen() again.
[ Top ] ### method _prepareOptions [line 553]
`void _prepareOptions( [bool $suppressErrors = FALSE])`
sets $this->_options based on the vars $optionsHard and $optionsEval. #### Tags:
see: | var $optionsType, var $optionsHard, var $optionsEval, var $_options
todo: | security hole here. we should use the concept of evalWrap(). i want to have it executed here and not there so we're in this object's scope.
#### Parameters:
bool | $suppressErrors | (default is FALSE. it's really hard to debug something with this set to true. you won't see anything.)
[ Top ] Documentation generated on Mon, 29 Dec 2003 21:10:09 +0100 by phpDocumentor 1.2.3