blueshoes php application framework and cms            core_html
[ class tree: core_html ] [ index: core_html ] [ all elements ]

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):

Version:

  • 4.3.$Revision: 1.6 $ $Date: 2003/10/29 17:48:39 $

Copyright:

  • blueshoes.org

Variables

Methods


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

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