C:/usr/local/lib/php/blueshoes-4.2/core/html/form/Bs_FormField.class.phpandrej arnbasic implementation of an html form field. is never instanced alone,only extended by one of the following classes:- FormFieldText - FormFieldButton- FormFieldPassword - FormFieldSubmit- FormFieldRadio - FormFieldReset- FormFieldCheckbox - FormFieldSelect- FormFieldImage - FormFieldTextarea- FormFieldFile - FormFieldWysiwyg- FormFieldHiddenit has *lots* of properties.dependencies: Bs_FormElement, Bs_String, Bs_LanguageHandler, Bs_EmailValidator,Bs_Array, Bs_HtmlUtil, Bs_Date,Form Field Class4.0.$id$blueshoes.orgConstructor.getField()isExplodable()setExplode()(used to return just some of the radio options.)some html codeusually 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.Return some html code to display all the exploded fields on a website in a form.overwrite this method in your subclass.an html checkbox, or an empty string.add enforce checkbox if needed.tells if this is an explodable field.getAdvancedStyleHelper()(see see)bool FALSE (if no-one is set.)returns the advanced style for the given key.getAdvancedStyle()(default is 'caption', can be 'field'.)bool FALSE (if no-one is set.)taking the current mode into account.just say if you want the class name (style) for the caption orthe field, the rest is done here.uses getAdvancedStyle() (returns its value).returns the advanced style for the field itself or the caption,$explodeEval$_explodeArray(php code as a string, or an array (vector or hash), or nothing.)if used, $param should be a string holding some php code that returns anarray. the string will be evaluated (in a separade scope) using eval(), soescape it as you should, rtfm on that. if a parse error occures on your codeor if it doesn't return an array, it is ignored. you are allowed to accessthe 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 ina 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 thevalue. 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 theuser-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 anarray directly. the 3rd is that you don't use $param. it will thenupdate $_explodeArray from $explodeEval.explode this field into multiple ones?$thisgetCaptionForFormOutput()if we should 'highlight' the access key in the returned label. default = TRUE.the label tag (html) for this field.Return the label tag (for the current language).(only used internally, for explodable fields) a vector with 2 elements.the order for data manipulation is:1) trim2) case3) remove4) removeI (insensitive)5) replace6) replaceIif this is an explodable field, this method calls itself for everyelement.manipulate the user inputs according to the object vars.(only used internally, for explodable fields.) (see above)the order for data validation is:1) must 5) mustStartWith 9) mustContain 13) bsDataType/bsDataInfo2a) onlyOneOf 6) notStartWith 10) notContain 14) regularExpression2b) onlyIf3) minLength 7) mustEndWith 11) equalTo 15) additionalCheck4) maxLength 8) notEndWith 12) notEqualTo 16) mustBeUniquewhen the first check fails, the method returns. $this->errorMessage will befilled (or unset if no error).all validating routines are in a separate method to make it isier for subclassesto overwrite and to just use the needed ones.if this is an explodable field, this method calls itself for everyelement.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.validate the user inputs according to the object vars.mustonlyOneOfonlyIf$minLength(the value the user submitted, should be a string here)the length of $v. this way we don't have to do strlen() again. (bool)TRUE if ok, (string)error message if not.checks the minLength case.$maxLength(the value the user submitted, should be a string here)the length of $v. this way we don't have to do strlen() again. (bool)TRUE if ok, (string)error message if not.checks the maxLength case.mustStartWithnotStartWithmustEndWithnotEndWithmustContainnotContainequalTonotEqualTobsDataType/bsDataInforegularExpressionadditionalCheck$mustBeUnique(the value the user submitted, should be a string here) (bool)TRUE if ok, (string)error message if not. @throw bs_exception (which is treated as not-string, so it's ok.)if we fail to do the test, the user-value is accepted.checks the mustBeUnique case. the check is made non-case-sensitive.$this$thisone of 'read', 'readonly', 'show', 'invisible', 'omit', 'normal' (default).returns how this field should be visible and editable to the user.the var of Bs_Form->onEnter is used if this->onEnter is not specified.if not set then the string 'nothing' will be returned.tells how this form field should behave when the user hits enter. (html/javascript code, may be empty.)example return value: "bsEnterSubmit(event,this.form);"the function that takes this string has to merge it into the onKeyDownevents.returns some javascript code (the call) to behave the way the coder wants.merges the onEnter javascript call into the events array if needed.$thisit's possible that it was submitted (by the user), but has to be ignored.i wonder if i should rename this method to shouldUse().tells if the received value should be persisted (used) this time.$dbDataTypeif $dbDataType is not set we have to make something up ourself.returns the db datatype to use for this field.$dbFieldNamereturns the db field name you should use for this field.$this$thisa usable maxlength @throw NULL if we cannot make up a logical value.Return a usable maxLength for that field.$thisexample: " onClick=\"javascript:someFunction();\" onMouseOver=\"javascript:someFunction();\""returns a string with the events that are set._getTagStringValue()$this(int or string)the value depends on the step the form is in. if the step is 1 thenwe take the valueDefault. otherwise the valueDisplay is used.returns the value.getValue()(int or string) (usually string, but may be an array (eg radio fields))returns the value that will be sent to the client browser.$thisexample: " class=\"color: blue\" tabindex=\"10\""returns a string with the style tags that are set.$thisexample: " value='your value' checked"returns a string with the additional tags that are set.$this$thisgetCaptionForFormOutput()if we should 'highlight' the access key in the returned caption. default = TRUE.(default is null. if not given then the lang setting of the form is used.)the caption for this field.overwrites parent method.Return the caption string (for the current language).getCaption()if we should 'highlight' the access key in the returned caption. default = TRUE.(default is null. if not given then the lang setting of the form is used.) (the caption for this field. usually an html string, not just plaintext.)returns the caption string to use in the form output. so expect html here and not plaintext.error messagereturns the error message for the current field, or an empty string if no error.returns the help textgetCaption()_getAccessKey()getLabel()$styleshighlight access key in string and return new string$thisyou may pass the caption here so it doesn't need to be fetched again if it's needed.string a character, or NULL if none.returns the access key letter, if any.(int or string)some html codereturns the field like a hidden field, no matter what field type it is.Return some some html code to send to the client. same as getField() butif the field name is for an array like foo['bar'] then foo[bar]will be returned.makes the field name html-compatible.TRUE if the client has javascript, FALSE if not. @throw NULL if we don't knowtells whether the client browser has javascript support or not.$_must$must$mustIf$mustOneOf$mustOneOfIfdefault is true. in the code we call this method more than once for each field. so this helps for the performance.(see above) (see param $returnType)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 anempty string '' if it's not a must field.tells if the field has to be filled in according to the current settings.(object var mustIf, onlyIf or mustOneOfIf, so look there.)TRUE if it evaluates to TRUE, FALSE otherwise.used for mustIf, onlyIf and mustOneOfIf case. that's where the (method) name anyIf comes from.$thisthis method is called from the getField() method in each form fieldimplementation. this way it should work with templates.when a field gets used in a form, it is marked as used. (vector with 2 elements, see above)that applies for number values (bsDatType = 'number').element 1 is the lowest number, element 2 the highest number.if a value is not set, null is used instead.possible return value: array(50, null) (means a min number of 50, no max value.)returns a 2-dim vector with the min- and max value specified in bsDataInfo.input was ok/accepted.tells if the user filled in this field *somehow*. does not tell if thewe have it wrapped here so we are in the scope of this call and thuscan use $this-> things.evaluate code in it's own scope and return what the eval'd code returns.gets executed automatically by the ObjPersister. read there for more info.returns a textual error message for the given error type.a reference to the pseudostatic object Bs_String.reference to the global pseudostatic Bs_Array.reference to the global pseudostatic Bs_HtmlUtil.reference to the global pseudostatic Bs_Date.- text - checkbox - hidden - reset - wysiwyg- password - image - button - select (special case, not html, textarea- radio - file - submit - textarea is used if wysiwyg not supported.)the html field type as in <input type=$fieldType>. one of$thisgetCaptionForFormOutput()your birthday: <input type=text name=birthday>usually a string, can be a hash because it's language dependant.the title for this field. in this example, the caption is 'your birthday':$thisexample:$defaultErrorMessage['de']['must'] = 'your error message';specialized default error messages for that form field.$errorTypeis set with a textual error message if the validation of this field failed.$errorMessagewe might need to know which error occured. one of 'must', 'onlyOneOf' etc.the FormContainer uses a public one.fields have to inherit the information from their container. that's whythis PRIVATE var is here.this var is for internal use only in the formfield!$visibility$accessRightsone 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.is the field editable (now)? also depends on the state we're in.KEY DATA TYPE EXAMPLE DESCRIPTION'group' string 'admin' user or group, whatever. just a name to identify the ppl.'view' bool TRUE|FALSE|NULL if the user may view the form in view mode.'add' bool TRUE|FALSE|NULL if the user may view the form in add mode (and add records).'edit' bool TRUE|FALSE|NULL if the user may view the form in edit mode (and edit records).'delete' bool TRUE|FALSE|NULL if the user may view the form in delete mode (and delete records).'alter' bool TRUE|FALSE|NULL if the user may view the form in alter mode (and alter the structure).the form has this var too. so accessRights of the formfield overwrite theones of the form. if a key is not set here (or the value is set to NULL)then the value of the form won't be overwritten.the vector holds hashes with these keys:$editability$accessRightsinput field. if $visibility is not set, the visibility/changeability dependson $editability. it will be visible and editable, or visible but not editable.otherwise this value 'overwrites' $editability.these values are accepted:FIELD VISIBLE EDITABLE STORE (=use value)- 'normal' x x x- 'read' x - x- 'readonly' x - -- 'show' x - -- 'invisible' - - x- 'omit' - - -some background information for the coder:normal => well... field is sent the normal way, value will be used on theserver.read => value is not changeable by the user, but will be used on theserver. same as readonly, except it's used.i have spent about an hour to find names for these vars, anddid not come up with something better. sucks.readonly => will make the field hopefully not changeable by the user.eg for a text field that means set the params readonly (html 4.0)and disabled (ie4+) <input readonly disabled>in some cases we prolly need to omit sending an input field andsend the existing value as raw text so it's not changeable.if it happens that the user still can change it, it doesn't mattercause the value will be ignored on the receiving server anyway.conused about the name? and why the value won't be stored?it's "read only", so it can "only be read", not more.show shows the value "printed out". without a form field. just printedout like this text here.invisible => add the existing (default) value in a <input type='hidden'>.it's a little security hole cause someone could change the value.needs to be checked on the server side (todo).omit => field/value are not sent at all. however, it's possible that someinvisible information is sent so the receiving server knows thisfield exists.caution: see vars $equalTo and $notEqualTo.it's possible that we may not allow the user to change the value of thisFALSE$thiswill be used on the server side, means if visibility evaluates to 'normal','read' or 'invisible'. not if it's 'readonly' cause the value won't be used, andnot if it's 'omit' of course. default is FALSE.tells if the field is used in the form. will be set to true if the field value$valueDefaultTypegetValue()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 followingdata 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 vectors1) $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 explodedfield. you cannot specify an array here to have another default value in eachexploded field.//if it's not a select field //--huh? what should that comment?the default value for that field.$valueDefaultgetValue()want some php code to execute to make up the default value. or, for multiple selectfields, 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 selectfields 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 guiand the changes get submitted, the php code has to be executed so we can storethe php array in $valueDefault. this case is needed cause we (hardly) can'tsubmit a php array with an html form directly. example:return array('yes'=>'Yes', 'no'=>'No', 'validate'=>'Validate');a spreadsheet field needs an array aswell.sometimes you may not be satisfied with a hardcoded default value for a field. youa select field cause it can have multiple values.it's an array holding the same thing as usual if this is an explodable field.the value we received directly from the user. usually a string, may be a vector if it isNULLusually 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.the value we will display to the user/browser when we show the form (again).NULLusually 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.the value we use internally, eg to store in the database.NULLexample: a checkbox "do you agree to the conditions" doesn't need to be saved.save the value of this field to the db or not?$thisbe 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.i suggest you don't set anything here. if you don't, the var $this->name will$thisif not specified, we have to make something up somehow, see getDbDataType().something like 'varchar', 'int', ...the data type of the database field.if the db field is or should be defined NOT NULL.if the db field is or should be defined NOT NULL.if the db field is or should be defined as key.if the db field is or should be defined as fulltext index.if the db field is or should be defined as auto increment field.if the db field is or should be defined UNIQUE.the hash has the following keys:KEY DATATYPE COMMENTSmultiple 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 theform settings, and that isn't very secure. ...db string if not set then it's the same.table stringfield 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)if not set or not an array or empty then it's not a foreign key.additional db attributes as the db told us. comma-separated or so, i think. dunno really.setExplode()isExplodable()$_explodeArrayspecial case. the content of this string will be evaluated.setExplode()isExplodable()$explodeEvalone of ltr (left to right) <= defaultrtl (right to left)ie5+ only. not set means ltr, which won't be written to the browser.the direction in which the text is written in that field, as in <input dir="ltr">$this- 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.associative array with style information. these keys can be used:of the bs_form is used if set.it's the same. the value of this object is read first, and if it's not set, then the one$thisthe currently (2001/04/27) available events are:- onFocus - onClick - onMouseOver - onKeyDown- onBlur - onDblClick - onMouseMove - onKeyUp- onSelect - onMouseDown - onMouseOut- onChange - onMouseUp - onKeyPressnote: some field types do not support all 12 events.set the keys exactly like written above (case). otherwise we get in troublewhen 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.(javascript) events like onClick, ...if this var is set, it overwrites one value of Bs_Form->onEnter.see var Bs_Form->onEnter for description and details.$thissupported by these classes.examples:$additionalTags = array("value='your value'", "checked");=> <input name="name" ... value='your value' checked>$additionalTags = "value='your value' checked";=> <input name="name" ... 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?" checkedin 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).maybe you'd like to add more properties to the html tags, some that are not- number- boolean- text- blob- html- email- url- username- password- zipcode- price- creditcard- ip- domain- host- date- time- month- year- datetime- timestamp- phone- firstname- lastname//middlename fullname//fileUpload//img//path//fileof course some combinations, like "textarea => username", make no sense.the internal data type that we expect to receive. one of: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 1 = any characters, 2 = a-zA-Z0-9, 3 = a-zA-Zhtml => bool: validate the html code or not?email => int: 1 = syntax validation, 2 = 1+ host validation, 3 = 1+2+ account validationurl => int: 1 = syntax validation, 2 = 1+ host validation, 3 = 1+2+ url validationpassword => int: 1 = anything, 2 = no forbidden password, 3 = 2 + no dictionary word,4 = 2+3+ need alpha/num combination, 5 = 2+3+4+ special characterzipcode => 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 = 1931datetime => 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 = anything40 = ch any41 = ch fixnet42 = ch cellthe first option is always the default.additional information to the $bsDataType.the manipulations are not visible to the user, which means $valueInternal is changedwhile $valueDisplay is not.number =>text =>html => idea: tagsToUpper/tagsToLoweremail =>url =>password =>price => int: 1 = work around floating pointeg 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 gmt7 = 1 + 68 = 2 + 69 = 3 + 610 = 4 + 611 = 5 + 6some datatypes may be modified in some standard way. this depends on $bsDataType.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 thedifference 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 tellsthe value type, element 1 is the (mixed) value.$bsDataManipVar[0] = ['hard'|'eval'];$bsDataManipVar[1] = 'something';sometimes $bsDataManipulation needs additional information to know how to manipulatehash 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, mustStartWithnotStartWith, mustEndWith, notEndWith, mustContain, notContain, equalTonotEqualTo, mustBeUnique, regularExpression, additionalCheckexample: the user is asked to type in an url. $bsDataType is 'url' and$bsDataInfo is '2'. now he types in his website, but unfortunatelythe host check fails because a) the server is currently down orb) the domain will be activated tomorrow or whatever. the userdoesn't want to wait and come back when the problem is fixed, hewants to do it now, and you want to allow it. what you do isyou set $enforce['bsDataInfo'] to true so when he submits, he'llget the form again with the error shown, but with a checkbox thatsays "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 theminLength check, this *may not* skip the notStartWith check!enforce settings for validating rules.isMust()2002/04/15 --andrej:this used to be a bool, but it is a string now telling which must casesaid that it was a must case. possibilities:must, mustIf, mustOneOf, mustOneOfIfif it's not a must field then it's empty (not set or empty string).computed must value, cached from isMust().tells whether the field has to be filled out or not.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 usefulespecially for cases where you want to have a field filled out whenanother field is - or is not. for example a checkbox where you are notsure 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 eitherwants 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 anexample 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.the field turns into a must field if the condition evaluates to true.ignored if $must or $mustIf is or evaluates to TRUE.at least one of (the fields in that array + this field) have to be filled out.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.at least one of (the fields in that array + this field) have to be filled in IFonly one of (the fields in that array + this field) may be filled out.in other words: it may only be filled in if ... .it is a very similar thing like the mustIf option. so look there fordetails/description.new since 2002/03/12 --andrejthe field turns into an only-field if the condition evaluates to true.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 webmasternot 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.the min length the field value needs to be. if it's not a $must field,$thisif 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 => 19text => 500 password => 20 host => 80 timestamp => 8blob => 65535 zipcode => 10 date => 10html => 65535 price => 20 time => 8email => 80 creditcard => 16 month => 2url => 200 ip => 15 year => 4there'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 webmasternot 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.the max length the field value can be.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.the field input has to start with one of these values.see $mustStartWithsee $mustStartWithsee $mustStartWithsee $mustStartWithsee $mustStartWithmay 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 fieldhas to equal another value, but for some reason, the otherfield was not sent (not editable, not visible to this user, ...).now what? we are not able to compare... we're going withthe following: accept the value, and log this case.it could be fixed when $visibility=omit would send the valuein 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)the field input has to 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 fieldhas to differ from another value, but for some reason, the otherfield was not sent (not editable, not visible to this user, ...).now what? we are not able to compare... we're going withthe following: accept the value, (and log this case? todo).it could be fixed when $visibility=omit would send the valuein an encrypted way. see var $visibility.note III: setting is ignored for the types select, checkbox and radio.the field input may not be equal to the field(s) specified here.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 tabledoesn'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 --andrejtells whether the field value must be unique in the db or not.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.regular expression(s) the value has to pass. language dependant.$this$codePostLoad$thisyou 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 codeshould return bool(true), which means check succeeded. or a string or array toindicate that it failed, thus the input won't be accepted. your return value thenis the error message that'll be shown to the user. it can be a string, or a hashif 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 foreach 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 2vars 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 thewhole 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;";all the given validating rules may not be enough for you. you need something handmade.one of the php functions trim(), ltrim() and rtrim() is used, and so thefollowing 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.trims white spaces from the user input.$removeIexamples:$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.remove string(s) from the user submitted value. language dependant. case sensitive.$removesame as $remove, but case insensitive.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.replaces strings with strings in the user submitted value. language dependant. case sensitive.$replacesame as $replace, but case insensitive.- lower make a string all lowercase.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'- ucfirst make the first character of the string upper case (if it's a letter)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'note: setting is ignored for the types select and radio and checkbox.modify the case of the user input? one of:$this$codePostLoadand the other modification methods (case, replace, remove ...) have beendone already. also the vars valueDisplay and valueInternal have been assigned.but the validation things come later.the code is executed in $this->evalWrap() (so you can use $this-> stuff).this code is evaluated after the content has been received from the client$this$codePostReceivethe code is executed in a method of this class. (so you can use $this->stuff)this code is evaluated after it is unpersisted.4.0.$x$1bs_formelementhasformobjectsetformobjectgetelementgetlevel_doelementstringformat_getparamvaluegetlanguagedependentvalueisexisexceptiontostringtohtmlpersistunpersistbs_objectbbsetoutputbbawakebbisawakebbxmsgbbxfunctionstartbbxfunctionendbbxechobbxvarbbxvardumpbbforcetracebbbufferstartbbbuffergetbbbufferendflushbbbufferendclean$persister$persisterid$_form$name$elementtype$formid$container$orderid$elementstringformat$persistervarsettingsbs_formelement_versionbs_object_versionBs_FormElementBs_ObjectBs_ObjectBs_FormFieldBtnBs_FormFieldCheckboxBs_FormFieldTxtBs_FormFieldHiddenBs_FormFieldImageBs_FormFieldRadioBs_FormFieldSelectBs_FormFieldTextareaBs_FormFieldSpreadsheetBs_FormFieldWysiwyg