| core_html

# Class: Bs_FormField Source Location: /core/html/form/Bs_FormField.class.php
### Class Overview
    Bs_Object
       |
       --Bs_FormElement
          |
          --Bs_FormField
Abstract Form Field Class #### Author(s): andrej arn <at blueshoes dot org> #### Version: 4.3.$Revision: 1.7 $ $Date: 2003/12/27 16:05:37 $ #### Copyright: blueshoes.org | ### Variables $additionalCheck $additionalTags $advancedStyles $bsDataInfo $bsDataManipulation $bsDataManipVar $bsDataType $case $codePostLoad $codePostManipulate $codePostReceive $dbAttributes $dbAutoIncrement $dbDataType $dbFieldName $dbForeignKey $dbIndexFulltext $dbKey $dbNotNull $dbPrimaryKey $dbUnique $defaultErrorMessage $direction $editability $enforce $equalTo $errorMessage $errorType $events $explodeEval $fieldType $isUsed $level $maxLength $minLength $must $mustBeUnique $mustContain $mustEndWith $mustIf $mustOneOf $mustOneOfIf $mustStartWith $notContain $notEndWith $notEqualTo $notStartWith $onEnter $onlyIf $onlyOneOf $onlyOneOfIf $regularExpression $remove $removeI $replace $replaceI $saveToDb $styles $trim $valueDefault $valueDefaultType $valueDisplay $valueInternal $valueReceived $_Bs_String $_explodeArray $_must | ### Methods Bs_FormField addEnforceCheckbox applyOnEnterBehavior getAdvancedStyle getAdvancedStyleHelper getCaption getCaptionForFormOutput getDbDataType getDbFieldName getElement getError getErrorMessage getField getFieldAsHidden getHelp getLabel getOnEnterBehavior getOnEnterCode getValue hasJavascript inputManipulate inputValidate isExplodable isFilledIn isMust postManipulateTrigger postReceiveTrigger setExplode shouldPersist unpersistTrigger validateAdditionalCheck validateDataType validateEqualTo validateMaxLength validateMinLength validateMust validateMustBeUnique validateMustContain validateMustEndWith validateMustStartWith validateNotContain validateNotEndWith validateNotEqualTo validateNotStartWith validateOnlyIf validateOnlyOneOf validateRegularExpression
### Child classes: Bs_FormFieldBtn BTN Form Field Class. Bs_FormFieldCheckbox CHECKBOX Form Field Class Bs_FormFieldHidden HIDDEN Form Field Class. Bs_FormFieldImage IMAGE Form Field Class. Bs_FormFieldRadio RADIO Form Field Class Bs_FormFieldSelect SELECT Form Field Class Bs_FormFieldTextarea TEXTAREA Form Field Class. Bs_FormFieldTxt TXT Form Field Class Bs_FormFieldEditor [Wysiwyg] EDITOR Form Field Class. Bs_FormFieldSlider Slider Form Field Class. Bs_FormFieldSpreadsheet SPREADSHEET Form Field Class. Bs_FormFieldTree TREE Form Field Class Bs_FormFieldWysiwyg WYSIWYG Form Field Class. | ### Inherited Variables #### 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_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 63] Abstract Form Field Class basic implementation of an html form field. is never instanced alone, only extended by one of the classes in the directories: core/html/form/ core/html/form/specialfields core/html/form/domapi it has *lots* of properties. dependencies: Bs_FormElement, Bs_String, Bs_LanguageHandler, Bs_EmailValidator, Bs_Array, Bs_HtmlUtil, Bs_Date, #### Tags:
copyright: | blueshoes.org
pattern: | singleton: (pseudostatic)
access: | public
version: | 4.3.$Revision: 1.7 $ $Date: 2003/12/27 16:05:37 $
author: | andrej arn <at blueshoes dot org>
[ Top ] ### Class Variables #### $additionalCheck = NULL [line 1025] all the given validating rules may not be enough for you. you need something handmade. you can use this var for a peace of php code. it'll be evaluated. not language dependant, fork it in your code if needed. if there's an error in your code, it will be treated as "check was ok". your code should return bool(true), which means check succeeded. or a string or array to indicate that it failed, thus the input won't be accepted. your return value then is the error message that'll be shown to the user. it can be a string, or a hash if you want to offer it in different languages. key=language, value=message. '$v' and special case with explodable fields: to access the value in your code you could do it by using $this->valueInternal. but it could be an explodable field, which means valueInternal can be an array. if so, $this->validateAdditionalCheck() (which does the check) is called for each entry of the array. otherwise it is just called once. to have the right value (the one of the current array element) you always have 2 vars in your scope: $v (the value) and $vLength (the string length of $v). i don't mind if you access $this->valueInternal directly to do something with the whole array, but keep in mind that the method is called once for each element. hope you got that.
     example I:
     $additionalCheck = "
       if ($v != 'foobar') {
         return $this->errorMessage = array(
           'en' => 'Input must be foobar.',
           'de' => 'Eingabe muss foobar sein.'
         );
       } else {
         return TRUE;
       }
     ";

     example II:
     $additionalCheck = "
       if (($this->hasFormObject()) && (isSet($this->_form->language))) {
         $lang = $this->_form->language;
       } else {
         $lang = 'en'; //fallback
       }
       switch ($lang) {
         case 'de':
           if ($v != 'hallo welt') return $this->errorMessage = 'Irgend ein Fehler';
           break;
         default: //also case 'en'
           if ($v != 'hello world') return $this->errorMessage = 'Some Error';
       }
       return TRUE;
     ";

     NOTE: be sure to escape the $ vars when assigning code to a var, otherwise it will
           be evaluated right away.
#### Tags:
var: | some php code.
todo: | add security stuff because of the eval.
see: | $this->_evalWrap(), var $codePostLoad, $this->validateAdditionalCheck()
access: | public
Type: | string
[ Top ] #### $additionalTags = [line 502] maybe you'd like to add more properties to the html tags, some that are not supported by these classes. examples:
       $additionalTags = array("value='your value'", "checked");
       =>
       $additionalTags = "value='your value' checked";
       =>
CAUTION: you really can fuck up things here. be warned. these 2 example values are no good: value='tom's pizzaland' maxlength='15' value="my nickname is "tom" -> cool heh?" checked in the 1st example, the problem is the ' in the 2nd example, the problems are the " and the > you have to convert such characters first. please see/use Html/Bs_HtmlUtil.class.php->filterForHtml(). note I: it's *not* an associative array where you do key=value. note II: in the gui implementation, only the string version is supported (no vector). #### Tags:
var: | (vector holding strings or just a string)
see: | $this->_getTagStringAdditionalTags()
Type: | mixed
[ Top ] #### $advancedStyles = [line 439] it's the same as Bs_Form->advancedStyles but overwrites it for this field, if present. the value of this object is read first, and if it's not set, then the one of the bs_form is used if set. #### Tags:
see: | var Bs_Form->advancedStyles
Type: | mixed
[ Top ] #### $bsDataInfo = NULL [line 589] additional information to the $bsDataType. sometimes it's not enough to know what data type we have to deal with, it could help us to have additional information.
       number   => string: number range. eg '-5000|+9999' which means from -5000 to +9999. the + sign is voluntary.
       text     => int     until bs4.2: 1 = any characters, 2 = a-zA-Z0-9, 3 = a-zA-Z
                                        these are still supported but deprecated.
                           since bs4.3: new bitmask:
                             8 = BS_FORM_TEXT_AZLOWER    = a-z
                            16 = BS_FORM_TEXT_AZUPPER    = A-Z
                            32 = BS_FORM_TEXT_09         = 0-9
                            64 = BS_FORM_TEXT_UNDERSCORE = _
                           128 = BS_FORM_TEXT_DASH       = -
                           256 = BS_FORM_TEXT_ANYTHING   = any character
                           example: you want a-z, 0-9 and the underscore _ to be allowed. use:
                           $field->bsDataInfo = BS_FORM_TEXT_AZLOWER + BS_FORM_TEXT_AZUPPER + BS_FORM_TEXT_09 + BS_FORM_TEXT_UNDERSCORE;
       html     => bool:   validate the html code or not?
       email    => int:    1 = syntax validation, 2 = 1+ host validation, 3 = 1+2+ account validation
       url      => int:    1 = syntax validation, 2 = 1+ host validation, 3 = 1+2+ url validation
       username => int:    1 = anything, 2 = nothing like 'root', 'admin', 'user' etc
       password => int:    1 = anything, 2 = no forbidden password, 3 = 2 + no dictionary word,
                           4 = 2+3+ need alpha/num combination, 5 = 2+3+4+ special character
       zipcode  => int:    1 = anything,
                           10 = us syntax, 11 = us valid,
                           20 = ca syntax, 21 = ca valid,
                           30 = de syntax, 31 = de valid,
                           40 = ch syntax, 41 = ch valid,
       price    => int:    1 = anything, 2 = only a number (eg "1599.90"), 3 = can have characters a-zA-Z (eg "usd 1599.90")
       date     => int:    1 = anything, 2 = anything that evaluates to a date,
                           3 = us (eg '2001/12/31'), 4 = eu (eg '31.12.2001')
       month    => int:    1 = anything, 2 = anything that evaluates to a month,
                           3 = digit (eg '12'), 4 = string (eg 'december')
       year     => int:    1 = anything, 2 = 4 digits required, 3 = 2 digits accepted where <=30 = 2030, >=31 = 1931
       datetime => int:    1 = anything, 2 = anything that evaluates to a datetime,
                           3 = us (eg '2001/12/31 24:59:59'), 4 = eu (eg '31.12.2001 24:59:59')
       phone    => int     1 = anything
                           40 = ch any
                           41 = ch fixnet
                           42 = ch cell
the first option is always the default.
Type: | string
[ Top ] #### $bsDataManipulation = [line 625] some datatypes may be modified in some standard way. this depends on $bsDataType. the manipulations are not visible to the user, which means $valueInternal is changed while $valueDisplay is not.
       number   =>
       text     =>
       html     => idea: tagsToUpper/tagsToLower
       email    =>
       url      =>
       password =>
       price    => int:    1 = work around floating point
                           eg user submits "135.15", we do *100 = "13515". when displaying we do
                           / 100 so it is "135.15" again.

       date     => int:    1 = to us format (eg '2001/12/31'), 2 = to eu format (eg '31.12.2001')
       month    =>
       year     =>
       datetime => int:    1 = to us format (eg '2001/12/31 24:59:59'),
                           2 = to eu format (eg '31.12.2001 24:59:59'),
                           3 = to mysql format (eg '2001-12-31 24:59:59'),
                           4 = to mysql timestamp (eg '20011231245959'),
                           5 = to unix timestamp,
                           6 = to gmt
                           7 = 1 + 6
                           8 = 2 + 6
                           9 = 3 + 6
                          10 = 4 + 6
                          11 = 5 + 6
#### Tags:
todo: | make use of this or kick it out.
access: | public
Type: | mixed
[ Top ] #### $bsDataManipVar = [line 641] sometimes $bsDataManipulation needs additional information to know how to manipulate the data. that's what this var is for. example: we've got a datetime value, and we should convert it to gmt. but what's the difference between the value we've got and gmt? this var should tell... if used, $bsDataManipVar must be a vector with exactly 2 elements. element 0 tells the value type, element 1 is the (mixed) value. $bsDataManipVar[0] = ['hard'|'eval']; $bsDataManipVar[1] = 'something'; #### Tags:
todo: | make use of this or kick it out.
Type: | mixed
[ Top ] #### $bsDataType = NULL [line 543] the internal data type that we expect to receive. one of: number boolean text blob html email url username password zipcode price creditcard ip domain host date time month year datetime timestamp phone firstname lastname of course some combinations, like "textarea => username", make no sense.
Type: | string
[ Top ] #### $case = [line 1132] modify the case of the user input? one of: eg 'Hello World' => 'hello world' upper make a string all uppercase. eg 'Hello World' => 'HELLO WORLD' ucwords make the first character of words upper case (if it's a letter). eg 'hellO worlD' => 'HellO WorlD' ucwordsonly same as ucwords, but make everything else lowercase. eg 'hellO worlD' => 'Hello World' ucfirst make the first character of the string upper case (if it's a letter). eg 'hellO worlD' => 'HellO worlD' ucfirstonly same as ucfirst, but make everything else lowercase. eg 'hellO worlD' => 'Hello world' nospam1 change strings to ucfirst if they are all upper case. replace any number of ! and ? signs with just one. eg 'HELLO! CLICK HERE FOR SEX PICTURES!!!' => 'Hello! click here for sex pictures!!!' nospam2 nospam1 + replace any number of ! signs with just one dot '.'. eg 'HELLO! CLICK HERE FOR SEX PICTURES!!!' => 'Hello click here for sex pictures' </pre> note: setting is ignored for the types select, radio and checkbox. #### Tags:
var: | (not set = do nothing)
access: | public
Type: | string
[ Top ] #### $codePostLoad = [line 1147] this code is evaluated after the form and it's fields are unpersisted. the code is executed in a method of this class. (so you can use $this->stuff) #### Tags:
var: | some php code
todo: | add security stuff because of the eval.
see: | $this->evalWrap(), vars $codePostReceive and $codePostManipulate
access: | public
Type: | string
[ Top ] #### $codePostManipulate = [line 1179] this code is evaluated after the received value has been manipulated (case, replace, remove ...). the vars valueDisplay and valueInternal have been assigned. the validation things come later. the code is executed in $this->evalWrap() (so you can use $this-> stuff). #### Tags:
var: | some php code
since: | bs4.3
todo: | add security stuff because of the eval.
see: | $this->postManipulateTrigger(), $this->evalWrap(), vars $codePostLoad and $codePostReceive
access: | public
Type: | string
[ Top ] #### $codePostReceive = [line 1166] this code is evaluated right after the content has been received from the client. the vars valueDisplay and valueInternal have not been assigned yet. the manipulation and validation things come later. the code is executed in $this->evalWrap() (so you can use $this-> stuff). change: until bs4.2 this code has been executed AFTER the manipulations have been done. one could argue that it was correct, it was AFTER the data has been received, but it was even AFTER the manipulations. now there is the $codePostManipulate. note that this will only be done for the fields that were meant and used in this level. #### Tags:
var: | some php code
todo: | add security stuff because of the eval.
see: | $this->postReceiveTrigger(), $this->evalWrap(), vars $codePostLoad and $codePostManipulate
access: | public
Type: | string
[ Top ] #### $dbAttributes = [line 380] additional db attributes as the db told us. comma-separated or so, i think. dunno really.
Type: | ?
[ Top ] #### $dbAutoIncrement = [line 327] if the db field is or should be defined as auto increment field. #### Tags:
var: | (if not set then default is false.)
access: | public
Type: | bool
[ Top ] #### $dbDataType = NULL [line 292] the data type of the database field. if not specified, we have to make something up somehow, see getDbDataType(). something like 'varchar', 'int', ... #### Tags:
see: | $this->getDbDataType()
Type: | string
[ Top ] #### $dbFieldName = NULL [line 283] i suggest you don't set anything here. if you don't, the var $this->name will be used with a prefix (so we don't get in troubles because of reserved names). you may set something here, then exactly this name will be used instead. consider using the same value as for $this->name. #### Tags:
see: | $this->getDbFieldName()
Type: | string
[ Top ] #### $dbForeignKey = [line 373] if not set or not an array or empty then it's not a foreign key. the hash has the following keys:
       KEY       DATATYPE    COMMENTS
       multiple  bool        if it's a 1:x or n:x relation.
       dns       array       hash with the following keys (just as every dns hash):
                               'host'
                               'port'
                               'syntax'
                               'type'
                               'user'
                               'pass'
                             if anything is set here then a new db connection will be opened.
                             be aware of the fact that this data has to be stored along with the
                             form settings, and that isn't very secure. ...
       db        string      if not set then it's the same.
       table     string
       field     string      that should be the field 'ID' but can be different in some cases.
       showAs    string      if multiple is TRUE:  one of 'select' (default), 'radio',    'flipflop'.
                             if multiple is FALSE: one of 'select' (default), 'checkbox', 'flipflop'.
       caption   mixed       the field that should be used to display on the page (eg in the select field).
                             usually the field 'caption'.
                             this setting may be language dependant, thus it can be a string or a lang-hash.
       value     mixed       the field that should be used as key on the page (eg in the select field).
                             should be the field 'ID'.
                             this setting may be language dependant, thus it can be a string or a lang-hash.
rules: if this field ends with 'ID' (eg 'carID') then it's a x:1 relation. (x of this one have 1 car each) if this field ends with 'IDs' (eg 'carIDs') then it's a x:n relation. (x of this have n cars each) #### Tags:
var: | (hash, see above)
access: | public
Type: | array
[ Top ] #### $dbIndexFulltext = [line 320] if the db field is or should be defined as fulltext index. #### Tags:
var: | (if not set then default is false.)
access: | public
Type: | bool
[ Top ] #### $dbKey = FALSE [line 313] if the db field is or should be defined as key. #### Tags:
var: | (if not set then default is false.)
access: | public
Type: | bool
[ Top ] #### $dbNotNull = TRUE [line 299] if the db field is or should be defined NOT NULL. #### Tags:
var: | (if not set then default is TRUE!).
access: | public
Type: | bool
[ Top ] #### $dbPrimaryKey = TRUE [line 306] if the db field is or should be defined NOT NULL. #### Tags:
var: | (if not set then default is TRUE!)
access: | public
Type: | bool
[ Top ] #### $dbUnique = [line 334] if the db field is or should be defined UNIQUE. #### Tags:
var: | (if not set then default is false.)
access: | public
Type: | bool
[ Top ] #### $defaultErrorMessage = [line 113] specialized default error messages for that form field. example: $defaultErrorMessage['de']['must'] = 'your error message'; #### Tags:
see: | $this->getErrorMessage()
Type: | array
[ Top ] #### $direction = [line 406] the direction in which the text is written in that field, as in <input dir="ltr"> one of ltr (left to right) <= default rtl (right to left) ie5+ only. not set means ltr, which won't be written to the browser.
Type: | string
[ Top ] #### $editability = [line 156] is the field editable (now)? also depends on the state we're in. one of [never|once|always] never => never :) once => only in 'add' mode, not in 'edit', 'delete' and unknown mode. always => always :) (in 'add' AND 'edit' mode) if it's not set, it's treated as editable for this time. #### Tags:
see: | $this->getVisibility(), vars $visibility, Bs_FormElement::$accessRights
access: | public
Type: | string
[ Top ] #### $enforce = [line 672] enforce settings for validating rules. hash holding bool values. if a key/value pair is not set, it means FALSE. every validating class var can have an entry in this array. these are: must, mustIf, mustOneOf, mustOneOfIf, onlyOneOf, onlyIf, minLength, maxLength, mustStartWith notStartWith, mustEndWith, notEndWith, mustContain, notContain, equalTo notEqualTo, mustBeUnique, regularExpression, additionalCheck example code: $myField->enforce = array('must'=>TRUE, 'minLength'=>TRUE); example: the user is asked to type in an url. $bsDataType is 'url' and $bsDataInfo is '2'. now he types in his website, but unfortunately the host check fails because a) the server is currently down or b) the domain will be activated tomorrow or whatever. the user doesn't want to wait and come back when the problem is fixed, he wants to do it now, and you want to allow it. what you do is you set $enforce['bsDataInfo'] to true so when he submits, he'll get the form again with the error shown, but with a checkbox that says "enforce" to allow the user to ignore the error. take care: imagine an input field with minLength=10 and notStartWith='hello'. now if the user types in 'hello' and he's allowed to enforce the minLength check, this *may not* skip the notStartWith check! #### Tags:
todo: | enforce is the wrong name for this. change it to $overlook. update text. 2002/11/10 --andrej
Type: | array
[ Top ] #### $equalTo = [line 902] the field input has to be equal to the field(s) specified here. may be useful for 2 password fields, one to confirm. usually a string, may also be a vector array of strings.
     note  I:  we only compare the data, not the datatype. (== not ===)

     note II:  this could cause some headache. imagine that this field
               has to equal another value, but for some reason, the other
               field was not sent (not editable, not visible to this user, ...).
               now what? we are not able to compare... we're going with
               the following: accept the value, and log this case.
               it could be fixed when $visibility=omit would send the value
               in an encrypted way. see var $visibility. (seems to be on the todo --andrej)

     note III: setting is ignored for the types select, checkbox and radio. (seems to be on the todo --andrej)

     note IV:  if one of the fields is not a must field, then it is accepted that one field has an input
               and the other stays empty. so they are not equal, and still accpeted.
               may not be obvious, think about it.
#### Tags:
todo: | the gui only supports string, not vector.
Type: | mixed
[ Top ] #### $errorMessage = [line 121] is set with a textual error message if the validation of this field failed. (not set means no error, right? asking myself... --andrej) #### Tags:
see: | var $errorType
Type: | string
[ Top ] #### $errorType = [line 128] we might need to know which error occured. one of 'must', 'onlyOneOf' etc. #### Tags:
see: | var $errorMessage
Type: | string
[ Top ] #### $events = [line 465] (javascript) events like onClick, ... the currently (2001/04/27) available events are:
       - onFocus    - onClick       - onMouseOver   - onKeyDown
       - onBlur     - onDblClick    - onMouseMove   - onKeyUp
       - onSelect   - onMouseDown   - onMouseOut
       - onChange   - onMouseUp     - onKeyPress
     note: some field types do not support all events.
set the keys exactly like written above (case). otherwise we get in trouble when merging more events into one, and there may be bugs. example: $events['onClick'] = "javascript:someFunction();"; will look like: <input onClick="javascript:someFunction();"> that means: if you want the word "javascript:" included, *you* have to add it yourself. because it could also be vbscript or whatever. #### Tags:
var: | (an associative array)
see: | $this->_getTagStringEvents()
Type: | array
[ Top ] #### $explodeEval = [line 391] special case. the content of this string will be evaluated. #### Tags:
see: | Bs_FormField::setExplode(), Bs_FormField::isExplodable(), var $_explodeArray
Type: | string
[ Top ] #### $fieldType = NULL [line 104] the html field type as in <input type=$fieldType>. one of
       - text       - checkbox   - hidden   - reset      - wysiwyg
       - password   - image      - button   - select       (special case, not html, textarea
       - radio      - file       - submit   - textarea     is used if wysiwyg not supported.)
Type: | string
[ Top ] #### $isUsed = FALSE [line 168] tells if the field is used in the form. will be set to true if the field value will be used on the server side, means if Bs_FormElement->visibility evaluates to 'normal', 'read' or 'invisible'. not if it's 'readonly' cause the value won't be used, and not if it's 'omit' of course. default is FALSE. #### Tags:
see: | $this->_markAsUsed()
Type: | bool
[ Top ] #### $level = [line 139] this var is for internal use only in the formfield! the FormContainer uses a public one. fields have to inherit the information from their container. that's why this PRIVATE var is here. #### Tags:
var: | (1-x)
see: | FormContainer->level
Type: | int
[ Top ] #### $maxLength = NULL [line 830] the max length the field value can be. if the form tag supports it, it will be directly added like this: <input maxlength=$maxLength> it will be checked serverside anyway. someone could hack it. if not set, it'll be something that makes sense based on $bsDataType:
       number =>    20       username   => 20       domain   => 80       datetime => 19
       text   =>   255       password   => 20       host     => 80       timestamp => 8
       blob   => 65535       zipcode    => 10       date     => 10
       html   => 65535       price      => 20       time     =>  8
       email  =>    80       creditcard => 16       month    =>  2
       url    =>   200       ip         => 15       year     =>  4
there's room for more logic: if the value is made up based on $bsDataType (list above) and $dbDataType is set, the value should be no bigger than the db field types max length, eg char/varchar=255, int=11, blob=65535, ... note I: for the field types 'checkbox' and 'radio' this setting is ignored. because the user cannot do anything about it. it's up to the webmaster not to do shit. note II: for the field type 'select' it's the number of max. selectable elements. if it doesn't have the 'multiple' property the setting is ignored. #### Tags:
see: | $this->_getMaxLength()
Type: | int
[ Top ] #### $minLength = NULL [line 798] the min length the field value needs to be. if it's not a $must field, a value shorter than $minLength is not accepted while an empty value is. note I: for the field types 'checkbox' and 'radio' this setting is ignored. because the user cannot do anything about it. it's up to the webmaster not to do shit. note II: for the field type 'select' it's the number of min. selectable elements. if it doesn't have the 'multiple' property the setting is ignored. #### Tags:
var: | (not set = 0 = none)
Type: | int
[ Top ] #### $must = FALSE [line 692] tells whether the field has to be filled out or not. #### Tags:
var: | (not set = false)
Type: | bool
[ Top ] #### $mustBeUnique = [line 941] tells whether the field value must be unique in the db or not. useful for usernames for example. the check is made non-case-sensitive. if we cannot check the uniqueness because of missing or wrong db data, the value is accepted. (this happens on the first insert if the table doesn't exist yet.) note: setting is ignored for the types select and checkbox. //comment: hrm... review this. maybe this line is here because of a copy/paste error. 2002/03/04 --andrej #### Tags:
var: | (not set = false)
deprecated: | (all things that use a db are deprecated as of bs4.3)
Type: | bool
[ Top ] #### $mustContain = NULL [line 869] see $mustStartWith
Type: | mixed
[ Top ] #### $mustEndWith = NULL [line 859] see $mustStartWith
Type: | mixed
[ Top ] #### $mustIf = NULL [line 731] the field turns into a must field if the condition evaluates to true. the vector holds hashes with these 4 elements:
       1) operator => one of '&' or '|'. & means AND while | means OR.
                      default is '|'.
       2) field    => the input field.
       3) compare  => the way we compare the value. one of =, >, <, >=, <=, !=, s, !s  (s = soundex equal, !s = not soundex equal).
                      default is '='.
                      the compare is made like "field >= value" so the field is on the left,
                      the value is on the right side. this matters.
       4) value    => the value to be compared.
                      if not set, anything != '' is treated as "matches". this is useful
                      especially for cases where you want to have a field filled out when
                      another field is - or is not. for example a checkbox where you are not
                      sure if the value will be 1, '1' or TRUE.
example: we absolutely need the email address of a person filling out a form if the person either wants to receive our newsletter or orders one of our products. $mustIf = array(array('operator'=>'|', 'field'=>'wantNewsletter', 'compare'=>'=', 'value'=>'yes'), array('operator'=>'|', 'field'=>'orderAmount', 'compare'=>'>', 'value'=>'0'), ) in php code, this would be: (($wantNewsletter == 'yes') || ($orderAmount > 0)) ignored if $must is TRUE. it's on purpose that this is not language dependant cause i cannot think of an example where it would be of any use and it would make things alot more complicated. i can see problems with the fucked up php datatypes. compares are made == not ===. please test your code. #### Tags:
var: | (vector, see example)
Type: | array
[ Top ] #### $mustOneOf = NULL [line 741] at least one of (the fields in that array + this field) have to be filled in. ignored if $must or $mustIf is or evaluates to TRUE. #### Tags:
var: | (vector filled with fieldname strings)
todo: | not implemented in the gui. difficult.
Type: | array
[ Top ] #### $mustOneOfIf = NULL [line 758] at least one of (the fields in that array + this field) have to be filled in IF the condition evaluates to true. otherwise none of the fields are mandatory. this is a combination of mustIf and mustOneOf. data structure: it's a hash with the two keys 'fields' => array, exactly the same as for the $mustOneOf var. 'condition' => array, exactly the same as for the $mustIf var. ignored if $must, $mustIf or $mustOneOf is or evaluates to TRUE. #### Tags:
var: | (see above.)
todo: | not implemented in the gui. difficult.
Type: | array
[ Top ] #### $mustStartWith = NULL [line 849] the field input has to start with one of these values. not case sensitive. language dependant.
     examples:
       $mustStartWith = array('hi', 'hello');
       $mustStartWith = array('en'=>array('hi','hello'), 'de'=>'hallo', 'fr'=>array('salut','bonjour'));
     not allowed data structures:
       $mustStartWith = 'hello';                           => use: array('hello')
       $mustStartWith = array('en'=>'hi', 'de'=>'hallo');  => use: array('en'=>array('hi'), 'de'=>array('hallo'));
note: setting is ignored for the types select and radio. #### Tags:
var: | (vector, or hash holding vectors, see examples.)
Type: | array
[ Top ] #### $notContain = NULL [line 874] see $mustStartWith
Type: | mixed
[ Top ] #### $notEndWith = NULL [line 864] see $mustStartWith
Type: | mixed
[ Top ] #### $notEqualTo = [line 926] the field input may not be equal to the field(s) specified here. may be useful for username/password fields where the password must be different from the username. usually a string, may also be a zero-based array of strings.
     note  I: we only compare the data, not the datatype. (== not ===)

     note II: this could cause some headache. imagine that this field
              has to differ from another value, but for some reason, the other
              field was not sent (not editable, not visible to this user, ...).
              now what? we are not able to compare... we're going with
              the following: accept the value, (and log this case? todo).
              it could be fixed when $visibility=omit would send the value
              in an encrypted way. see var $visibility.

     note III: setting is ignored for the types select, checkbox and radio.
#### Tags:
todo: | the gui only supports string, not vector.
Type: | mixed
[ Top ] #### $notStartWith = NULL [line 854] see $mustStartWith
Type: | mixed
[ Top ] #### $onEnter = [line 473] see var Bs_Form->onEnter for description and details. if this var is set, it overwrites one value of Bs_Form->onEnter. #### Tags:
see: | var Bs_Form->onEnter
Type: | string
[ Top ] #### $onlyIf = [line 779] the field turns into an only-field if the condition evaluates to true. in other words: it may only be filled in if ... . it is a very similar thing like the mustIf option. so look there for details/description. new since 2002/03/12 --andrej #### Tags:
var: | (vector)
todo: | not implemented in the gui.
Type: | array
[ Top ] #### $onlyOneOf = NULL [line 765] only one of (the fields in that array + this field) may be filled out. #### Tags:
var: | (vector)
todo: | not implemented in the gui. difficult.
Type: | array
[ Top ] #### $onlyOneOfIf = [line 784] #### Tags:
todo: | not implemented yet. could be needed somewhen.
Type: | mixed
[ Top ] #### $regularExpression = NULL [line 962] regular expression(s) the value has to pass. language dependant.
     examples:
       $regularExpression = 'abc';
       $regularExpression = array('abc', 'abc');
       $regularExpression = array('en'=>array('abc','abc'), 'de'=>array('abc'), 'fr'=>array('abc','abc'));
     not allowed data structures:
       $regularExpression = array('en'=>'abc', 'de'=>'abc', 'fr'=>'abc');
note: setting is ignored for the types select and radio. usually a string, may also be an array (vector or hash) holding strings or vectors holding strings. #### Tags:
var: | (see examples)
Type: | mixed
[ Top ] #### $remove = [line 1067] remove string(s) from the user submitted value. language dependant. case sensitive.
     examples:
       $remove = array('abc');
       $remove = array('abc', 'abc');
       $remove = array('en'=>array('abc'), 'de'=>array('abc'), 'fr'=>array('abc'));
       $remove = array('en'=>array('abc','abc'), 'de'=>'abc', 'fr'=>array('abc','abc'));
     these structures are not allowed because they would make it hard to guess what is meant:
       $remove = 'abc';
       $remove = array('en'=>'abc', 'de'=>'abc', 'fr'=>'abc');

     so the datatype is a vector or a hash holding vectors.

     note: setting is ignored for the types select and radio and checkbox.
#### Tags:
var: | (see examples)
see: | var $removeI
access: | public
Type: | array
[ Top ] #### $removeI = [line 1075] same as $remove, but case insensitive. #### Tags:
see: | var $remove
access: | public
Type: | array
[ Top ] #### $replace = [line 1091] replaces strings with strings in the user submitted value. language dependant. case sensitive.
     examples:
       $replace = array('ä'=>'ae', 'hello'=>'hi');
       $replace = array('fr'=>array('é'=>'e'), 'de'=>array('ä'=>'ae','ö'=>'oe','ü'=>'ue');

     note: setting is ignored for the types select and radio and checkbox.
#### Tags:
var: | (associative array holding strings or associative arrays holding associative arrays. see examples)
access: | public
Type: | array
[ Top ] #### $replaceI = [line 1103] same as $replace, but case insensitive. note: if you specify to replace ö with oe, then Ö will be replaced with oe and not OE or Oe. #### Tags:
see: | var $replace
access: | public
Type: | array
[ Top ] #### $saveToDb = NULL [line 273] save the value of this field to the db or not? example: a checkbox "do you agree to the conditions" doesn't need to be saved.
Type: | bool
[ Top ] #### $styles = [line 431] associative array with style information. these keys can be used:
       - string class
       - string id
       - string style
       - (*) char accessKey[]
         a char or an associative array cause it's language dependant.
       - int tabIndex (ie4+)
       - (*) mixed title[]
         a string or an associative array cause it's language dependant.
         appears as a tool tip over the field.
       - (*) mixed label[] (ie4+)
         a string or an associative array cause it's language dependant.
         i really don't recommend to use that setting instead of the caption.
     (*) these options are not available in the gui. problem with explodable holding explodable.
check your html documentation for details. #### Tags:
see: | $this->_getTagStringStyles()
access: | public
Type: | array
[ Top ] #### $trim = [line 1043] trims white spaces from the user input. one of the php functions trim(), ltrim() and rtrim() is used, and so the following chars are considered white spaces: "\n", "\r", "\t", "\v", "\0", and a plain space. the value can be one of [none|left|right|both] note: setting is ignored for the types select and radio and checkbox. #### Tags:
var: | (not set = none = do nothing)
access: | public
Type: | string
[ Top ] #### $valueDefault = [line 202] the default value for that field. may be a string or a hash cause it's language dependant. for a multiple select field it's even worse. because of this, the following data structures are allowed: for all fields except select:
       string and hash:
       1) $valueDefault = 'foobar';
       2) $valueDefault = array('en'=>'foobar', 'de'=>'hello world');
     only for select: (no matter if they are multiple or not)
       string, vector, hash (key=language), hash (key=language) holding vectors
       1) $valueDefault = 'foobar';
       2) $valueDefault = array('foo', 'bar');
       3) $valueDefault = array('en'=>'foobar', 'de'=>'hello world');
       4) $valueDefault = array('en'=>array('foo', 'bar'), 'de'=>array('hello', 'world'));
       yes, this causes a problem cause 2) and 3) are both just arrays. but it can be done.
if this is an explodable field, the default value will be used in every exploded field. you cannot specify an array here to have another default value in each exploded field. //if it's not a select field //--huh? what should that comment? #### Tags:
see: | var $valueDefaultType, Bs_FormField::getValue()
Type: | mixed
[ Top ] #### $valueDefaultType = [line 226] sometimes you may not be satisfied with a hardcoded default value for a field. you want some php code to execute to make up the default value. or, for multiple select fields, the default value may be an array. that's what this var is for. the value (maybe inside a hash because of the language dependency) can be one of:
     'text'  => default. hardcoded default value.
     'code'  => some php code that returns a string. may return an array for multiple select
                fields only. executed in the scope of this class ($this->_evalWrap()).
     'field' => the user-supplied value of another field of a previous level (multi-level forms.)
     'array' => only for multiple select fields: when the default value is changed in the gui
                and the changes get submitted, the php code has to be executed so we can store
                the php array in $valueDefault. this case is needed cause we (hardly) can't
                submit a php array with an html form directly. example:
                return array('yes'=>'Yes', 'no'=>'No', 'validate'=>'Validate');
                a spreadsheet field needs an array aswell.
#### Tags:
see: | var $valueDefault, Bs_FormField::getValue()
Type: | string
[ Top ] #### $valueDisplay = NULL [line 246] the value we will display to the user/browser when we show the form (again). usually a string, may be a vector if it is a select field cause it can have multiple values. it's an array holding the same thing as usual if this is an explodable field.
Type: | mixed
[ Top ] #### $valueInternal = NULL [line 259] the value we use internally, eg to store in the database. usually a string, may be a vector if it is a select field cause it can have multiple values. it's an array holding the same thing as usual if this is an explodable field. note: the $bsDataType is taken into account to make up this value. example: if the user does not fill in a radio button field, and the radio button field is of $bsDataType 'boolean', then this $valueInternal will be bool FALSE.
Type: | mixed
[ Top ] #### $valueReceived = [line 238] the value we received directly from the user. usually a string, may be a vector if it is a select field cause it can have multiple values. it's an array holding the same thing as usual if this is an explodable field. note: until bs4.2 the value was bool FALSE if the form field has not been filled in. this is changed to the value NULL in bs4.3. --andrej
Type: | mixed
[ Top ] #### $_Bs_String = [line 72] a reference to the pseudostatic object Bs_String.
Type: | object
[ Top ] #### $_explodeArray = [line 397] #### Tags:
var: | a hash or a vector.
see: | Bs_FormField::setExplode(), Bs_FormField::isExplodable(), var $explodeEval
Type: | array
[ Top ] #### $_must = [line 686] computed must value, cached from isMust(). 2002/04/15 --andrej: this used to be a bool, but it is a string now telling which must case said that it was a must case. possibilities: must, mustIf, mustOneOf, mustOneOfIf if it's not a must field then it's empty (not set or empty string). #### Tags:
var: | (see above.)
see: | Bs_FormField::isMust()
Type: | string
[ Top ] ### Class Methods ### constructor Bs_FormField [line 1185]
`Bs_FormField Bs_FormField( )`
Constructor. [ Top ] ### method addEnforceCheckbox [line 1303]
`string addEnforceCheckbox( )`
add enforce checkbox if needed. #### Tags:
return: | an html checkbox, or an empty string.
todo: | name[] _enforce won't work with arrays.
access: | public
[ Top ] ### method applyOnEnterBehavior [line 2500]
`void applyOnEnterBehavior( )`
merges the onEnter javascript call into the events array if needed. #### Tags:
access: | public
[ Top ] ### method getAdvancedStyle [line 1334]
`string getAdvancedStyle( string $key)`
returns the advanced style for the given key. #### Tags:
see: | var Bs_Form->advancedStyles, Bs_FormField::getAdvancedStyleHelper()
throws: | bool FALSE (if no-one is set.)
access: | public
#### Parameters:
string | $key | (see see)
[ Top ] ### method getAdvancedStyleHelper [line 1361]
`string getAdvancedStyleHelper( [string $what = 'caption'])`
returns the advanced style for the field itself or the caption, taking the current mode into account. just say if you want the class name (style) for the caption or the field, the rest is done here. uses getAdvancedStyle() (returns its value). #### Tags:
see: | Bs_FormField::getAdvancedStyle()
throws: | bool FALSE (if no-one is set.)
access: | public
#### Parameters:
string | $what | (default is 'caption', can be 'field'.)
[ Top ] ### method getCaption [line 2867]
`string getCaption( [bool $useAccessKey = TRUE], [string $lang = null])`
Return the caption string (for the current language). overwrites parent method. #### Tags:
return: | the caption for this field.
see: | var $this->caption, $this->getLabel(), getCaptionForFormOutput().
Overridden in child classes as: Bs_FormFieldCheckbox::getCaption() Return the caption string (for the current language). Overrides Bs_FormElement::getCaption() (Return the caption string (for the current language).) #### Parameters:
bool | $useAccessKey | if we should 'highlight' the access key in the returned caption. default = TRUE.
string | $lang | (default is null. if not given then the lang setting of the form is used.)
[ Top ] ### method getCaptionForFormOutput [line 2882]
`string getCaptionForFormOutput( [bool $useAccessKey = TRUE], [string $lang = null])`
returns the caption string to use in the form output. so expect html here and not plaintext. overwrites parent method. #### Tags:
return: | (the caption for this field. usually an html string, not just plaintext.)
see: | Bs_FormField::getCaption()
Overrides 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.) #### Parameters:
bool | $useAccessKey | if we should 'highlight' the access key in the returned caption. default = TRUE.
string | $lang | (default is null. if not given then the lang setting of the form is used.)
[ Top ] ### method getDbDataType [line 2537]
`string getDbDataType( )`
returns the db datatype to use for this field. if $dbDataType is not set we have to make something up ourself. #### Tags:
see: | var $dbDataType
access: | public
[ Top ] ### method getDbFieldName [line 2616]
`string getDbFieldName( )`
returns the db field name you should use for this field. #### Tags:
see: | var $dbFieldName
access: | public
[ Top ] ### method getElement [line 1264]
`string &getElement( [array $optionList = null])`
Return some html code to display all the exploded fields on a website in a form. usually you want to use getField(), but if it is an explodable field, you need this. you may use getElement() instead of getField(), that's no problem. #### Tags:
return: | some html code
see: | Bs_FormField::getField(), Bs_FormField::isExplodable(), Bs_FormField::setExplode()
access: | public
Overrides Bs_FormElement::getElement() (Return some html code to display the element on a website in a form.) #### Parameters:
array | $optionList | (used to return just some of the radio options.)
[ Top ] ### method getError [line 2913]
`string getError( )`
returns the error message for the current field, or an empty string if no error. #### Tags:
return: | error message
access: | public
[ Top ] ### method getErrorMessage [line 3334]
`void getErrorMessage( [string $errorType = ''], [array $params = array()], [string $lang = NULL])`
returns a textual error message for the given error type. #### Tags:
todo: | finish this method, especially implement xml.
#### Parameters:
string | $errorType |
array | $params |
string | $lang |
[ Top ] ### method getField [line 1292]
`void getField( )`
overwrite this method in your subclass. Overridden in child classes as: Bs_FormFieldBtn::getField() Return some html code to display the button on a website in a form. Bs_FormFieldButton::getField() Return some html code to display the button on a website in a form. Bs_FormFieldCheckbox::getField() Return some html code to display the field on a website in a form. Bs_FormFieldCheckboxJs::getField() Return some html code to display the field on a website in a form. Bs_FormFieldHidden::getField() Return some html code to display the field on a website in a form. Bs_FormFieldImage::getField() Return some html code to display the field on a website in a form. Bs_FormFieldRadio::getField() Return some html code to display the field on a website in a form. Bs_FormFieldRadioJs::getField() Return some html code to display the field on a website in a form. Bs_FormFieldSelect::getField() Returns some html code to display the field on a website in a form. 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. Bs_FormFieldTextarea::getField() Return some html code to display the field on a website in a form. Bs_FormFieldTxt::getField() Return some html code to display the field on a website in a form. Bs_FormFieldFile::getField() Return some html code to display the field on a website in a form. Bs_FormFieldDatePicker::getField() Return some html code to display the field on a website in a form. Bs_FormFieldEmail::getField() overwrites and uses parent method. look there. Bs_FormFieldFileBrowser::getField() Return some html code to display the field on a website in a form. Bs_FormFieldFirstname::getField() overwrites and uses parent method. look there. Bs_FormFieldLastname::getField() overwrites and uses parent method. look there. Bs_DaFormFieldColorPicker2::getField() Return some html code to display the field on a website in a form. Bs_DaFormFieldDatePicker::getField() Return some html code to display the field on a website in a form. Bs_DaFormFieldSpinEdit::getField() Return some html code to display the field on a website in a form. Bs_FormFieldEditor::getField() Return some html code to display the field on a website in a form. Bs_FormFieldSlider::getField() Return some html code to display the field on a website in a form. Bs_FormFieldSpreadsheet::getField() Return some html code to display the field on a website in a form. Bs_FormFieldTree::getField() Return some html code to display the field on a website in a form. Bs_FormFieldWysiwyg::getField() Return some html code to display the field on a website in a form. [ Top ] ### method getFieldAsHidden [line 3034]
`string getFieldAsHidden( [mixed $explodeKey = NULL])`
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. and no matter what the visibility, editability etc. is. #### Tags:
return: | some html code
todo: | i'm sure this won't work for select fields with a multiple selection. need to overwrite it. also the value has to be tag-encoded, i bet.
access: | public
#### Parameters:
mixed | $explodeKey | (int or string)
[ Top ] ### method getHelp [line 2923]
`void getHelp( )`
returns the help text #### Tags:
todo: | all
[ Top ] ### method getLabel [line 1450]
`string getLabel( [bool $useAccessKey = TRUE])`
Return the label tag (for the current language). #### Tags:
return: | the label tag (html) for this field.
see: | $this->getCaption(), getCaptionForFormOutput().
#### Parameters:
bool | $useAccessKey | if we should 'highlight' the access key in the returned label. default = TRUE.
[ Top ] ### method getOnEnterBehavior [line 2452]
`string getOnEnterBehavior( )`
tells how this form field should behave when the user hits enter. the var of Bs_Form->onEnter is used if this->onEnter is not specified. if not set then the string 'nothing' will be returned. #### Tags:
access: | public
[ Top ] ### method getOnEnterCode [line 2476]
`string getOnEnterCode( )`
returns some javascript code (the call) to behave the way the coder wants. example return value: "bsEnterSubmit(event,this.form);" the function that takes this string has to merge it into the onKeyDown events. #### Tags:
return: | (html/javascript code, may be empty.)
access: | public
[ Top ] ### method getValue [line 2726]
`string getValue( [mixed $explodeKey = NULL])`
returns the value. the value depends on the step the form is in. if the step is 1 then we take the valueDefault. otherwise the valueDisplay is used. #### Tags:
see: | _getTagStringValue(), vars $this->valueDefault $this->valueDisplay
access: | public
#### Parameters:
mixed | $explodeKey | (int or string)
[ Top ] ### method hasJavascript [line 3068]
`bool hasJavascript( )`
tells whether the client browser has javascript support or not. #### Tags:
return: | TRUE if the client has javascript, FALSE if not.
throws: | NULL if we don't know
access: | public
[ Top ] ### method inputManipulate [line 1487]
`void inputManipulate( [array $paramValue = NULL])`
manipulate the user inputs according to the object vars.
     the order for data manipulation is:
       1) trim
       2) case
       3) remove
       4) removeI (insensitive)
       5) replace
       6) replaceI
if this is an explodable field, this method calls itself for every element. #### Tags:
access: | public
Overridden in child classes as: Bs_FormFieldBtn::inputManipulate() overwrites parent method. we don't need this here. Bs_FormFieldRadio::inputManipulate() overwrite parent method cause we don't want to manipulate anything here. Bs_FormFieldSelect::inputManipulate() overwrite parent method cause we don't want to manipulate anything here. #### Parameters:
array | $paramValue | (only used internally, for explodable fields) a vector with 2 elements.
[ Top ] ### method inputValidate [line 1731]
`mixed inputValidate( [mixed $paramValue = NULL])`
validate the user inputs according to the object vars.
     the order for data validation is:
       1) must         5) mustStartWith     9) mustContain    13) bsDataType/bsDataInfo
       2a) onlyOneOf   6) notStartWith     10) notContain     14) regularExpression
       2b) onlyIf
       3) minLength    7) mustEndWith      11) equalTo        15) additionalCheck
       4) maxLength    8) notEndWith       12) notEqualTo     16) mustBeUnique
when the first check fails, the method returns. $this->errorMessage will be filled (or unset if no error). all validating routines are in a separate method to make it isier for subclasses to overwrite and to just use the needed ones. if this is an explodable field, this method calls itself for every element. return: (bool)TRUE if the input passed all validation checks successfully. (string) an error message on failure. note: some of the field implementations overwrite this method (checkbox, select, radio, maybe others) so if you update something here, don't forget those. #### Tags:
return: | (see above)
access: | public
Overridden in child classes as: Bs_FormFieldBtn::inputValidate() overwrites parent method. we don't need this here. Bs_FormFieldCheckbox::inputValidate() validate the user inputs according to the object vars. Bs_FormFieldRadio::inputValidate() validate the user inputs according to the object vars. Bs_FormFieldSelect::inputValidate() validate the user inputs according to the object vars. Bs_FormFieldFile::inputValidate() overwrites parent method, look there. #### Parameters:
mixed | $paramValue | (only used internally, for explodable fields.)
[ Top ] ### method isExplodable [line 1320]
`bool isExplodable( )`
tells if this is an explodable field. #### Tags:
see: | Bs_FormField::setExplode()
access: | public
[ Top ] ### method isFilledIn [line 3290]
`bool isFilledIn( )`
tells if the user filled in this field *somehow*. does not tell if the input was ok/accepted. #### Tags:
access: | public
[ Top ] ### method isMust [line 3092]
`mixed isMust( [bool $useCached = TRUE], [bool $returnString = FALSE])`
tells if the field has to be filled in according to the current settings. param $returnString: the return of this method used to be bool. now the default is still bool. but you can change that by setting the param $returnString to TRUE. then you'll get one of 'must', 'mustIf', 'mustOneOf', 'mustOneOfIf' or an empty string '' if it's not a must field. #### Tags:
return: | (see param $returnType)
see: | vars $_must, Bs_FormField::$must, Bs_FormField::$mustIf, Bs_FormField::$mustOneOf, Bs_FormField::$mustOneOfIf
access: | public
#### Parameters:
bool | $useCached | default is true. in the code we call this method more than once for each field. so this helps for the performance.
bool | $returnString | (see above)
[ Top ] ### method postManipulateTrigger [line 1693]
`void postManipulateTrigger( )`
gets called after the user input has been set to the form fields, and the needed automatic manipulations have been done. subclasses may overwrite (and still make use of) this class. #### Tags:
see: | var $codePostManipulate, $this->postReceiveTrigger()
access: | public
[ Top ] ### method postReceiveTrigger [line 1678]
`void postReceiveTrigger( )`
gets called right after the user input has been set to the form fields. subclasses may overwrite (and still make use of) this class. #### Tags:
see: | var $codePostReceive, $this->postManipulateTrigger()
access: | public
Overridden in child classes as: Bs_FormFieldFile::postReceiveTrigger() overwrites and uses parent method. [ Top ] ### method setExplode [line 1422]
`void setExplode( [mixed $param = NULL])`
explode this field into multiple ones? if used, $param should be a string holding some php code that returns an array. the string will be evaluated (in a separade scope) using eval(), so escape it as you should, rtfm on that. if a parse error occures on your code or if it doesn't return an array, it is ignored. you are allowed to access the filesystem and databases, but not issueing shell commands in your code. example: (real world example) this is a caption field. but because your app supports different languages, just one string isn't enough. you want one for each supported language. thing is you don't know which languages are used. this information is in a global var: $APP['usedLanguages'] = array('en'=>'english', 'de'=>'deutsch', 'de_du'=>'deutsch du', 'de_si'=>'deutsch sie'); so every language used should have it's own caption field. your code for $param then looks like this: $param = "global \$APP; return \$APP['usedLanguages'];"; now for each element in that returned array, one form element is 'exploded'. the name for the form element is the key of the array, the caption is the value. for the submitted values, $this->valueReceived will be an array also, in this case a hash, where the key is 'en' for example, and the value is the user-submitted value. of course this also works with vecors. note: you have 3 possibilities to call this method. one is described above, meaning that you pass some php code. the 2nd is that you pass an array directly. the 3rd is that you don't use $param. it will then update $_explodeArray from $explodeEval. #### Tags:
see: | var $explodeEval, var $_explodeArray
#### Parameters:
mixed | $param | (php code as a string, or an array (vector or hash), or nothing. see above.)
[ Top ] ### method shouldPersist [line 2520]
`bool shouldPersist( )`
tells if the received value should be persisted (used) this time. it's possible that it was submitted (by the user), but has to be ignored. i wonder if i should rename this method to shouldUse(). #### Tags:
see: | $this->getVisibility()
access: | public
[ Top ] ### method unpersistTrigger [line 1663]
`void unpersistTrigger( )`
gets executed automatically in some circumstances: by the ObjPersister. read there for more info. or by the Bs_Form->postLoadTrigger() if called by the user or by the Bs_Form->doItYourself() if used by the user Overridden in child classes as: Bs_FormFieldSlider::unpersistTrigger() overwrites and uses parent method. so look there, in Bs_FormField->unpersistTrigger(). [ Top ] ### method validateAdditionalCheck [line 2317]
`void validateAdditionalCheck( mixed &$v, mixed &$vLength)`
additionalCheck [ Top ] ### method validateDataType [line 2101]
`void validateDataType( mixed &$v)`
bsDataType/bsDataInfo #### Tags:
todo: | finish this code
[ Top ] ### method validateEqualTo [line 2036]
`void validateEqualTo( mixed &$v)`
equalTo [ Top ] ### method validateMaxLength [line 1867]
`mixed validateMaxLength( mixed &$v, int &$vLength)`
checks the maxLength case. #### Tags:
return: | (bool)TRUE if ok, (string)error message if not.
see: | var $maxLength
access: | public
Overridden in child classes as: Bs_FormFieldSelect::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 1845]
`mixed validateMinLength( mixed &$v, int &$vLength)`
checks the minLength case. #### Tags:
return: | (bool)TRUE if ok, (string)error message if not.
see: | var $minLength
access: | public
Overridden in child classes as: Bs_FormFieldSelect::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 validateMust [line 1773]
`void validateMust( mixed &$v, mixed &$vLength)`
must [ Top ] ### method validateMustBeUnique [line 2347]
`mixed validateMustBeUnique( mixed &$v)`
checks the mustBeUnique case. the check is made non-case-sensitive. if we fail to do the test, the user-value is accepted. #### Tags:
return: | (bool)TRUE if ok, (string)error message if not.
see: | var $mustBeUnique
throws: | bs_exception (which is treated as not-string, so it's ok.)
access: | public
#### Parameters:
mixed | &$v | (the value the user submitted, should be a string here)
[ Top ] ### method validateMustContain [line 1984]
`void validateMustContain( mixed &$v)`
mustContain [ Top ] ### method validateMustEndWith [line 1933]
`void validateMustEndWith( mixed &$v)`
mustEndWith [ Top ] ### method validateMustStartWith [line 1882]
`void validateMustStartWith( mixed &$v)`
mustStartWith [ Top ] ### method validateNotContain [line 2011]
`void validateNotContain( mixed &$v)`
notContain [ Top ] ### method validateNotEndWith [line 1960]
`void validateNotEndWith( mixed &$v)`
notEndWith [ Top ] ### method validateNotEqualTo [line 2068]
`void validateNotEqualTo( mixed &$v)`
notEqualTo [ Top ] ### method validateNotStartWith [line 1910]
`void validateNotStartWith( mixed &$v)`
notStartWith [ Top ] ### method validateOnlyIf [line 1821]
`void validateOnlyIf( mixed &$v, mixed &$vLength)`
onlyIf [ Top ] ### method validateOnlyOneOf [line 1797]
`void validateOnlyOneOf( mixed &$v)`
onlyOneOf [ Top ] ### method validateRegularExpression [line 2292]
`void validateRegularExpression( mixed &$v)`
regularExpression [ Top ] Documentation generated on Mon, 29 Dec 2003 21:09:27 +0100 by phpDocumentor 1.2.3