BlueShoes Application Framework - Form

Bs_FormField

Bs_Object
   |
  +-- Bs_FormElement
     |
    +-- Bs_FormField

Form Field Class

public class Bs_FormField extends Bs_FormElement

Form Field Class
basic 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,

Authors andrej arn <andrej@arn.li>

Version 4.0.$id$

Copyright blueshoes.org

Direct known subclasses: Bs_FormFieldBtn, Bs_FormFieldCheckbox, Bs_FormFieldTxt, Bs_FormFieldHidden, Bs_FormFieldImage, Bs_FormFieldRadio, Bs_FormFieldSelect, Bs_FormFieldTextarea, Bs_FormFieldSpreadsheet, Bs_FormFieldWysiwyg

Methods inherited from Bs_FormElement

bs_formelement, hasformobject, setformobject, getelement, getlevel, _doelementstringformat, _getparamvalue, getlanguagedependentvalue

Methods inherited from Bs_Object

isex, isexception, tostring, tohtml, persist, unpersist, bs_object, bbsetoutput, bbawake, bbisawake, bbxmsg, bbxfunctionstart, bbxfunctionend, bbxecho, bbxvar, bbxvardump, bbforcetrace, bbbufferstart, bbbufferget, bbbufferendflush, bbbufferendclean

Public Method Summary
void	Bs_FormField() Constructor.
string	&getElement([ string $optionList ]) Return some html code to display all the exploded fields on a website in a form.
string	addEnforceCheckbox() add enforce checkbox if needed.
bool	isExplodable() tells if this is an explodable field.
string	getAdvancedStyle(string $key) returns the advanced style for the given key.
string	getAdvancedStyleHelper([ string $what ]) returns the advanced style for the field itself or the caption,
void	inputManipulate([ string $paramValue ]) manipulate the user inputs according to the object vars.
mixed	inputValidate([ mixed $paramValue ]) validate the user inputs according to the object vars.
mixed	validateMinLength(mixed &$v, int &$vLength) checks the minLength case.
mixed	validateMaxLength(mixed &$v, int &$vLength) checks the maxLength case.
mixed	validateMustBeUnique(mixed &$v) checks the mustBeUnique case. the check is made non-case-sensitive.
string	getVisibility() returns how this field should be visible and editable to the user.
string	getOnEnterBehavior() tells how this form field should behave when the user hits enter.
string	getOnEnterCode() returns some javascript code (the call) to behave the way the coder wants.
void	applyOnEnterBehavior() merges the onEnter javascript call into the events array if needed.
bool	shouldPersist() tells if the received value should be persisted (used) this time.
string	getDbDataType() returns the db datatype to use for this field.
string	getDbFieldName() returns the db field name you should use for this field.
string	getValue([ mixed $explodeKey ]) returns the value.
string	getError() returns the error message for the current field, or an empty string if no error.
string	getFieldAsHidden([ mixed $explodeKey ]) Return some some html code to send to the client. same as getField() but
bool	hasJavascript() tells whether the client browser has javascript support or not.
mixed	isMust([ string $useCached, string $returnString ]) tells if the field has to be filled in according to the current settings.
bool	isFilledIn() tells if the user filled in this field somehow. does not tell if the
void	unpersistTrigger() gets executed automatically by the ObjPersister. read there for more info.
void	getErrorMessage([ string $errorType, array $params, string $lang ]) returns a textual error message for the given error type.

Private Method Summary
void	getField() overwrite this method in your subclass.
void	setExplode([ mixed $param ]) explode this field into multiple ones?
string	getLabel([ string $useAccessKey ]) Return the label tag (for the current language).
void	validateMust( &$v, &$vLength) must
void	validateOnlyOneOf( &$v) onlyOneOf
void	validateOnlyIf( &$v, &$vLength) onlyIf
void	validateMustStartWith( &$v) mustStartWith
void	validateNotStartWith( &$v) notStartWith
void	validateMustEndWith( &$v) mustEndWith
void	validateNotEndWith( &$v) notEndWith
void	validateMustContain( &$v) mustContain
void	validateNotContain( &$v) notContain
void	validateEqualTo( &$v) equalTo
void	validateNotEqualTo( &$v) notEqualTo
void	validateDataType( &$v) bsDataType/bsDataInfo
void	validateRegularExpression( &$v) regularExpression
void	validateAdditionalCheck( &$v, &$vLength) additionalCheck
int	_getMaxLength() Return a usable maxLength for that field.
string	_getTagStringEvents() returns a string with the events that are set.
mixed	_getTagStringValue([ mixed $explodeKey ]) returns the value that will be sent to the client browser.
string	_getTagStringStyles() returns a string with the style tags that are set.
string	_getTagStringAdditionalTags() returns a string with the additional tags that are set.
string	getCaption([ string $useAccessKey, string $lang ]) Return the caption string (for the current language).Warning: documentation is missing.
string	getCaptionForFormOutput([ string $useAccessKey, string $lang ]) returns the caption string to use in the form output. so expect html here and not plaintext.
void	getHelp() returns the help text
string	_highlightAccessKey(string $string) highlight access key in string and return new string
mixed	_getAccessKey([ string $caption ]) returns the access key letter, if any.
string	_getFieldNameForHtml(string $name) makes the field name html-compatible.
bool	_anyIfCase(array $myIf) used for mustIf, onlyIf and mustOneOfIf case. that's where the (method) name anyIf comes from.
void	_markAsUsed() when a field gets used in a form, it is marked as used.
array	_getBsDataInfoNumber() returns a 2-dim vector with the min- and max value specified in bsDataInfo.
void	_evalWrap( $string, string $security, string $suppressErrors, array $params) evaluate code in it's own scope and return what the eval'd code returns.
void	&serialize(string $encrypt) Warning: documentation is missing.
void	unserialize( &$string, string $decrypt) Warning: documentation is missing.
void	&encrypt( $string) Warning: documentation is missing.
void	&decrypt( $string) Warning: documentation is missing.
void	initFromPost() Warning: documentation is missing.

Fields inherited from Bs_FormElement

$persister, $persisterid, $_form, $name, $elementtype, $formid, $container, $orderid, $elementstringformat, $persistervarsettings

Public Field Summary
string	$editability is the field editable (now)? also depends on the state we're in.
string	$visibility it's possible that we may not allow the user to change the value of this
bool	$dbNotNull if the db field is or should be defined NOT NULL.
bool	$dbPrimaryKey if the db field is or should be defined NOT NULL.
bool	$dbKey if the db field is or should be defined as key.
bool	$dbIndexFulltext if the db field is or should be defined as fulltext index.
bool	$dbAutoIncrement if the db field is or should be defined as auto increment field.
bool	$dbUnique if the db field is or should be defined UNIQUE.
array	$dbForeignKey if not set or not an array or empty then it's not a foreign key.
unknown	$dbAttributes additional db attributes as the db told us. comma-separated or so, i think. dunno really.
string	$additionalCheck all the given validating rules may not be enough for you. you need something handmade.

Private Field Summary
object [unknown]	$_Bs_String a reference to the pseudostatic object Bs_String.
object [unknown]	$_Bs_Array reference to the global pseudostatic Bs_Array.
object [unknown]	$_Bs_HtmlUtil reference to the global pseudostatic Bs_HtmlUtil.
object [unknown]	$_Bs_Date reference to the global pseudostatic Bs_Date.
string	$fieldType the html field type as in <input type=$fieldType>. one of
mixed	$caption the title for this field. in this example, the caption is 'your birthday':
array	$defaultErrorMessage specialized default error messages for that form field.
string	$errorMessage is set with a textual error message if the validation of this field failed.
string	$errorType we might need to know which error occured. one of 'must', 'onlyOneOf' etc.
int	$level this var is for internal use only in the formfield!
array	$accessRights the vector holds hashes with these keys:
string	$isUsed tells if the field is used in the form. will be set to true if the field value
mixed	$valueDefault the default value for that field.
string	$valueDefaultType sometimes you may not be satisfied with a hardcoded default value for a field. you
mixed	$valueReceived the value we received directly from the user. usually a string, may be a vector if it is
string	$valueDisplay the value we will display to the user/browser when we show the form (again).
string	$valueInternal the value we use internally, eg to store in the database.
string	$saveToDb save the value of this field to the db or not?
string	$dbFieldName i suggest you don't set anything here. if you don't, the var $this->name will
string	$dbDataType the data type of the database field.
string	$explodeEval special case. the content of this string will be evaluated.
array	$_explodeArray
string	$direction the direction in which the text is written in that field, as in <input dir="ltr">
array	$styles associative array with style information. these keys can be used:
unknown	$advancedStyles it's the same. the value of this object is read first, and if it's not set, then the one
array	$events (javascript) events like onClick, ...
string	$onEnter see var Bs_Form->onEnter for description and details.
mixed	$additionalTags maybe you'd like to add more properties to the html tags, some that are not
string	$bsDataType the internal data type that we expect to receive. one of:
string	$bsDataInfo additional information to the $bsDataType.
unknown	$bsDataManipulation some datatypes may be modified in some standard way. this depends on $bsDataType.
unknown	$bsDataManipVar sometimes $bsDataManipulation needs additional information to know how to manipulate
array	$enforce enforce settings for validating rules.
string	$_must computed must value, cached from isMust().
bool	$must tells whether the field has to be filled out or not.
array	$mustIf the field turns into a must field if the condition evaluates to true.
array	$mustOneOf at least one of (the fields in that array + this field) have to be filled out.
array	$mustOneOfIf at least one of (the fields in that array + this field) have to be filled in IF
array	$onlyOneOf only one of (the fields in that array + this field) may be filled out.
array	$onlyIf the field turns into an only-field if the condition evaluates to true.
unknown	$onlyOneOfIf
int	$minLength the min length the field value needs to be. if it's not a $must field,
int	$maxLength the max length the field value can be.
array	$mustStartWith the field input has to start with one of these values.
unknown	$notStartWith see $mustStartWith
unknown	$mustEndWith see $mustStartWith
unknown	$notEndWith see $mustStartWith
unknown	$mustContain see $mustStartWith
unknown	$notContain see $mustStartWith
mixed	$equalTo the field input has to be equal to the field(s) specified here.
mixed	$notEqualTo the field input may not be equal to the field(s) specified here.
bool	$mustBeUnique tells whether the field value must be unique in the db or not.
mixed	$regularExpression regular expression(s) the value has to pass. language dependant.
string	$trim trims white spaces from the user input.
array	$remove remove string(s) from the user submitted value. language dependant. case sensitive.
array	$removeI same as $remove, but case insensitive.
array	$replace replaces strings with strings in the user submitted value. language dependant. case sensitive.
array	$replaceI same as $replace, but case insensitive.
string	$case modify the case of the user input? one of:
string	$codePostReceive this code is evaluated after the content has been received from the client
string	$codePostLoad this code is evaluated after it is unpersisted.
unknown	$this
unknown	$charsRule

Private Constant Summary
BS_FORMFIELD_VERSION	>>`4.0.$x$`<<	Warning: documentation is missing.
BS_FF_ERROR	>>`1`<<	Warning: documentation is missing.

Public Method Details

Bs_FormField

public void Bs_FormField( )

Constructor.

Returns

void

&getElement

public string &getElement( [ string $optionList ] )

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.

Parameter

string	$optionList	`= >>null<<`
	(used to return just some of the radio options.)

Returns

string

some html code

See Also getField(), isExplodable(), setExplode()

addEnforceCheckbox

public string addEnforceCheckbox( )

add enforce checkbox if needed.

Returns

string

an html checkbox, or an empty string.

isExplodable

public bool isExplodable( )

tells if this is an explodable field.

Returns

bool

getAdvancedStyle

public string getAdvancedStyle( string $key )

returns the advanced style for the given key.

Parameter

string	$key
	(see see)

Returns

string

Throws bool FALSE (if no-one is set.)

getAdvancedStyleHelper

public string getAdvancedStyleHelper( [ string $what ] )

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 orthe field, the rest is done here.uses getAdvancedStyle() (returns its value).

Parameter

string	$what	`= >>'caption'<<`
	(default is 'caption', can be 'field'.)

Returns

string

Throws bool FALSE (if no-one is set.)

inputManipulate

public void inputManipulate( [ string $paramValue ] )

manipulate the user inputs according to the object vars.
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.

Parameter

string	$paramValue	`= >>NULL<<`
	(only used internally, for explodable fields) a vector with 2 elements.

Returns

void

inputValidate

public mixed inputValidate( [ mixed $paramValue ] )

validate the user inputs according to the object vars.
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.

Parameter

mixed	$paramValue	`= >>NULL<<`
	(only used internally, for explodable fields.)

Returns

mixed

(see above)

validateMinLength

public mixed validateMinLength( mixed &$v, int &$vLength )

checks the minLength case.

Parameter

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.

Returns

mixed

(bool)TRUE if ok, (string)error message if not.

validateMaxLength

public mixed validateMaxLength( mixed &$v, int &$vLength )

checks the maxLength case.

Parameter

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.

Returns

mixed

(bool)TRUE if ok, (string)error message if not.

validateMustBeUnique

public 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.

Parameter

mixed	&$v
	(the value the user submitted, should be a string here)

Returns

mixed

(bool)TRUE if ok, (string)error message if not.
@throw bs_exception (which is treated as not-string, so it's ok.)

getVisibility

public string getVisibility( )

returns how this field should be visible and editable to the user.

Returns

string

one of 'read', 'readonly', 'show', 'invisible', 'omit', 'normal' (default).

getOnEnterBehavior

public 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.

Returns

string

getOnEnterCode

public 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 onKeyDownevents.

Returns

string

(html/javascript code, may be empty.)

applyOnEnterBehavior

public void applyOnEnterBehavior( )

merges the onEnter javascript call into the events array if needed.

Returns

void

shouldPersist

public 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().

Returns

bool

See Also $this

getDbDataType

public string getDbDataType( )

returns the db datatype to use for this field.
if $dbDataType is not set we have to make something up ourself.

Returns

string

getDbFieldName

public string getDbFieldName( )

returns the db field name you should use for this field.

Returns

string

getValue

public string getValue( [ mixed $explodeKey ] )

returns the value.
the value depends on the step the form is in. if the step is 1 thenwe take the valueDefault. otherwise the valueDisplay is used.

Parameter

mixed	$explodeKey	`= >>NULL<<`
	(int or string)

Returns

string

getError

public string getError( )

returns the error message for the current field, or an empty string if no error.

Returns

string

error message

getFieldAsHidden

public string getFieldAsHidden( [ mixed $explodeKey ] )

Return some 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.

Parameter

mixed	$explodeKey	`= >>NULL<<`
	(int or string)

Returns

string

some html code

hasJavascript

public bool hasJavascript( )

tells whether the client browser has javascript support or not.

Returns

bool

TRUE if the client has javascript, FALSE if not.
@throw NULL if we don't know

isMust

public mixed isMust( [ string $useCached, string $returnString ] )

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 anempty string '' if it's not a must field.

Parameter

string	$useCached	`= >>TRUE,<<`
	default is true. in the code we call this method more than once for each field. so this helps for the performance.

string	$returnString	`= >>FALSE<<`
	(see above)

Returns

mixed

(see param $returnType)

See Also $_must, $must, $mustIf, $mustOneOf, $mustOneOfIf

isFilledIn

public bool isFilledIn( )

tells if the user filled in this field *somehow*. does not tell if the
input was ok/accepted.

Returns

bool

unpersistTrigger

public void unpersistTrigger( )

gets executed automatically by the ObjPersister. read there for more info.

Returns

void

getErrorMessage

public void getErrorMessage( [ string $errorType, array $params, string $lang ] )

returns a textual error message for the given error type.

Parameter

string	$errorType	`= >>''<<`

array	$params	`= >>array()<<`

string	$lang	`= >>NULL<<`

Returns

void

Private Method Details

getField

private void getField( )

overwrite this method in your subclass.

Returns

void

setExplode

private void setExplode( [ mixed $param ] )

explode this field into multiple ones?
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.

Parameter

mixed	$param	`= >>NULL<<`
	(php code as a string, or an array (vector or hash), or nothing.)

Returns

void

getLabel

private string getLabel( [ string $useAccessKey ] )

Return the label tag (for the current language).

Parameter

string	$useAccessKey	`= >>TRUE<<`
	if we should 'highlight' the access key in the returned label. default = TRUE.

Returns

string

the label tag (html) for this field.

See Also $this, getCaptionForFormOutput()

validateMust

private void validateMust( &$v, &$vLength )

must

Parameter

	&$v
	Warning: documentation is missing.

	&$vLength
	Warning: documentation is missing.

Returns

void

validateOnlyOneOf

private void validateOnlyOneOf( &$v )

onlyOneOf

Parameter

	&$v
	Warning: documentation is missing.

Returns

void

validateOnlyIf

private void validateOnlyIf( &$v, &$vLength )

onlyIf

Parameter

	&$v
	Warning: documentation is missing.

	&$vLength
	Warning: documentation is missing.

Returns

void

validateMustStartWith

private void validateMustStartWith( &$v )

mustStartWith

Parameter

	&$v
	Warning: documentation is missing.

Returns

void

validateNotStartWith

private void validateNotStartWith( &$v )

notStartWith

Parameter

	&$v
	Warning: documentation is missing.

Returns

void

validateMustEndWith

private void validateMustEndWith( &$v )

mustEndWith

Parameter

	&$v
	Warning: documentation is missing.

Returns

void

validateNotEndWith

private void validateNotEndWith( &$v )

notEndWith

Parameter

	&$v
	Warning: documentation is missing.

Returns

void

validateMustContain

private void validateMustContain( &$v )

mustContain

Parameter

	&$v
	Warning: documentation is missing.

Returns

void

validateNotContain

private void validateNotContain( &$v )

notContain

Parameter

	&$v
	Warning: documentation is missing.

Returns

void

validateEqualTo

private void validateEqualTo( &$v )

equalTo

Parameter

	&$v
	Warning: documentation is missing.

Returns

void

validateNotEqualTo

private void validateNotEqualTo( &$v )

notEqualTo

Parameter

	&$v
	Warning: documentation is missing.

Returns

void

validateDataType

private void validateDataType( &$v )

bsDataType/bsDataInfo

Parameter

	&$v
	Warning: documentation is missing.

Returns

void

validateRegularExpression

private void validateRegularExpression( &$v )

regularExpression

Parameter

	&$v
	Warning: documentation is missing.

Returns

void

validateAdditionalCheck

private void validateAdditionalCheck( &$v, &$vLength )

additionalCheck

Parameter

	&$v
	Warning: documentation is missing.

	&$vLength
	Warning: documentation is missing.

Returns

void

_getMaxLength

private int _getMaxLength( )

Return a usable maxLength for that field.

Returns

int

a usable maxlength
@throw NULL if we cannot make up a logical value.

_getTagStringEvents

private string _getTagStringEvents( )

returns a string with the events that are set.
example: " onClick=\"javascript:someFunction();\" onMouseOver=\"javascript:someFunction();\""

Returns

string

See Also $this

_getTagStringValue

private mixed _getTagStringValue( [ mixed $explodeKey ] )

returns the value that will be sent to the client browser.

Parameter

mixed	$explodeKey	`= >>NULL<<`
	(int or string)

Returns

mixed

(usually string, but may be an array (eg radio fields))

_getTagStringStyles

private string _getTagStringStyles( )

returns a string with the style tags that are set.
example: " class=\"color: blue\" tabindex=\"10\""

Returns

string

See Also $this

_getTagStringAdditionalTags

private string _getTagStringAdditionalTags( )

returns a string with the additional tags that are set.
example: " value='your value' checked"

Returns

string

See Also $this

getCaption

private string getCaption( [ string $useAccessKey, string $lang ] )

Return the caption string (for the current language).
overwrites parent method.

Warning: documentation is missing.

Parameter

string	$useAccessKey	`= >>TRUE,<<`
	if we should 'highlight' the access key in the returned caption. default = TRUE.

string	$lang	`= >>null<<`
	(default is null. if not given then the lang setting of the form is used.)

Returns

string

the caption for this field.

See Also $this, $this, getCaptionForFormOutput()

getCaptionForFormOutput

private string getCaptionForFormOutput( [ string $useAccessKey, string $lang ] )

returns the caption string to use in the form output. so expect html here and not plaintext.

Parameter

string	$useAccessKey	`= >>TRUE,<<`
	if we should 'highlight' the access key in the returned caption. default = TRUE.

string	$lang	`= >>null<<`
	(default is null. if not given then the lang setting of the form is used.)

Returns

string

(the caption for this field. usually an html string, not just plaintext.)

getHelp

private void getHelp( )

returns the help text

Returns

void

_highlightAccessKey

private string _highlightAccessKey( string $string )

highlight access key in string and return new string

Parameter

string	$string

Returns

string

See Also getCaption(), _getAccessKey(), getLabel(), $styles

_getAccessKey

private mixed _getAccessKey( [ string $caption ] )

returns the access key letter, if any.

Parameter

string	$caption	`= >>NULL<<`
	you may pass the caption here so it doesn't need to be fetched again if it's needed.

Returns

mixed

string a character, or NULL if none.

See Also $this

_getFieldNameForHtml

private string _getFieldNameForHtml( string $name )

makes the field name html-compatible.
if the field name is for an array like foo['bar'] then foo[bar]will be returned.

Parameter

string	$name

Returns

string

_anyIfCase

private bool _anyIfCase( array $myIf )

used for mustIf, onlyIf and mustOneOfIf case. that's where the (method) name anyIf comes from.

Parameter

array	$myIf
	(object var mustIf, onlyIf or mustOneOfIf, so look there.)

Returns

bool

TRUE if it evaluates to TRUE, FALSE otherwise.

_markAsUsed

private void _markAsUsed( )

when a field gets used in a form, it is marked as used.
this method is called from the getField() method in each form fieldimplementation. this way it should work with templates.

Returns

void

See Also $this

_getBsDataInfoNumber

private array _getBsDataInfoNumber( )

returns a 2-dim vector with the min- and max value specified in bsDataInfo.
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

array

(vector with 2 elements, see above)

_evalWrap

private void _evalWrap( $string, string $security, string $suppressErrors, array $params )

evaluate code in it's own scope and return what the eval'd code returns.
we have it wrapped here so we are in the scope of this call and thuscan use $this-> things.

Parameter

	$string
	Warning: documentation is missing.

string	$security
	Warning: documentation is missing.

string	$suppressErrors
	Warning: documentation is missing.

array	$params
	Warning: documentation is missing.

Returns

void

&serialize

private void &serialize( string $encrypt )

Warning: documentation is missing.

Parameter

string	$encrypt
	Warning: documentation is missing.

Returns

void

unserialize

private void unserialize( &$string, string $decrypt )

Warning: documentation is missing.

Parameter

	&$string
	Warning: documentation is missing.

string	$decrypt
	Warning: documentation is missing.

Returns

void

&encrypt

private void &encrypt( $string )

Warning: documentation is missing.

Parameter

	$string
	Warning: documentation is missing.

Returns

void

&decrypt

private void &decrypt( $string )

Warning: documentation is missing.

Parameter

	$string
	Warning: documentation is missing.

Returns

void

initFromPost

private void initFromPost( )

Warning: documentation is missing.

Returns

void

Public Field Details
$editability
public string $editability >><< 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.
See Also	$visibility, $accessRights

$visibility
public string $visibility >><< it's possible that we may not allow the user to change the value of this input 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.
See Also	$editability, $accessRights

$dbNotNull
public bool $dbNotNull >><< if the db field is or should be defined NOT NULL.

$dbPrimaryKey
public bool $dbPrimaryKey >><< if the db field is or should be defined NOT NULL.

BlueShoes Application Framework - Form

Bs_FormField

public class Bs_FormField extends Bs_FormElement

Methods inherited from Bs_FormElement

Methods inherited from Bs_Object

Public Method Summary

Bs_FormField()

&getElement([ string $optionList ])

addEnforceCheckbox()

isExplodable()

getAdvancedStyle(string $key)

getAdvancedStyleHelper([ string $what ])

inputManipulate([ string $paramValue ])

inputValidate([ mixed $paramValue ])

validateMinLength(mixed &$v, int &$vLength)

validateMaxLength(mixed &$v, int &$vLength)

validateMustBeUnique(mixed &$v)

getVisibility()

getOnEnterBehavior()

getOnEnterCode()

applyOnEnterBehavior()

shouldPersist()

getDbDataType()

getDbFieldName()

getValue([ mixed $explodeKey ])

getError()

getFieldAsHidden([ mixed $explodeKey ])

hasJavascript()

isMust([ string $useCached, string $returnString ])

isFilledIn()

unpersistTrigger()

getErrorMessage([ string $errorType, array $params, string $lang ])

Private Method Summary

getField()

setExplode([ mixed $param ])

getLabel([ string $useAccessKey ])

validateMust( &$v, &$vLength)

validateOnlyOneOf( &$v)

validateOnlyIf( &$v, &$vLength)

validateMustStartWith( &$v)

validateNotStartWith( &$v)

validateMustEndWith( &$v)

validateNotEndWith( &$v)

validateMustContain( &$v)

validateNotContain( &$v)

validateEqualTo( &$v)

validateNotEqualTo( &$v)

validateDataType( &$v)

validateRegularExpression( &$v)

validateAdditionalCheck( &$v, &$vLength)

_getMaxLength()

_getTagStringEvents()

_getTagStringValue([ mixed $explodeKey ])

_getTagStringStyles()

_getTagStringAdditionalTags()

getCaption([ string $useAccessKey, string $lang ])

getCaptionForFormOutput([ string $useAccessKey, string $lang ])

getHelp()

_highlightAccessKey(string $string)

_getAccessKey([ string $caption ])

_getFieldNameForHtml(string $name)

_anyIfCase(array $myIf)

_markAsUsed()

_getBsDataInfoNumber()

_evalWrap( $string, string $security, string $suppressErrors, array $params)

&serialize(string $encrypt)

unserialize( &$string, string $decrypt)

&encrypt( $string)

&decrypt( $string)

initFromPost()

Fields inherited from Bs_FormElement

Public Field Summary

$editability

$visibility

$dbNotNull

$dbPrimaryKey

$dbKey

$dbIndexFulltext

$dbAutoIncrement

$dbUnique