BlueShoes Application Framework - Form

Bs_Form

Bs_Object
|
+-- Bs_Form

Form Class

public class Bs_Form extends Bs_Object

Form Class
implementation of an html form. holds (uses) instances of FormElement.this flowchart shows how records can be added/editedusing this form class. the delete mode works slightlydifferent (there is no validation).+---------------------------+| || +----------------+ | +--------------+| | | | | || | +----------------------+ || | | FORM | || | | | || | | <preview> <save> | || error +----------------------+ error| occured | | occured| | | | || +---- < validate > < validate > ---+| | || | || +--------------------+ || | PREVIEW | || | | || | <edit> <save> | || +--------------------+ || | | |+-----------+ | || |+--------------------+| DONE || || thank you |+--------------------+the hash 'bs_form' including the following hidden vars is submitted alongwith the form all the time:NAME VALUE DESCRIPTIONname the name of this form (see var $internalName)mode add|edit|delete|view (see var $mode)step 2 (see var $step)recordId 5541 (see var $recordId)viewCount int (see var $viewCount)startTimestamp unix timestamp (see var $startTimestamp)language de|en|fr... (see var $language)state form|preview|done (see var $state)user ''|guest|member|root|... (see var $user)avoid cheating and the use of templates:with most forms you can cheat in that you save the form on your harddisk,change hidden and default values, and submit it from your disk.you could check the http_referer to see if the request comes from yourserver, but this is a bad idea. you'd block out users with old/strangeclients that don't send the http_referer, ppl using anomyzers/firewalls,and then a cheater could send a modified http_referer anyway.now with form templates thing is that not all form fields may be used.how does the validater know which fields have been in the form, andthus which fields he has to validate? we could loop $HTTP_POST_VARSbecause every submitted field has a key in this array. but again,we get the *submitted* fields, and not those which someone has removedwith the save-to-disc cheat.so the only secure way is to send a cryptified list of fields as ahidden input. we'd need to crypt hidden values also, but let's notget paranoid at the moment.also the use of the preview mode might be a risk. when submitting thepreview page, the inputs are not checked again. good place to cheat...features:o) multilevel forms (yah! :)o) templates (for the form AND for containers)o) multilingualo) very strong on input validationo) can deal with hitting enter in text fieldso) offers some nice domapi form element implementationso) and some more ready-to-use out-of-the-box special fields.o) can deal with include-once and onLoad javascript stufffeatures to add: (wishlist)o) cache the form (html output) for each language. then spit this outinstead of generating the form on every (first) request. the cacheneeds to be updated if someone makes changes to form/elements. thiswill make the forms load alot faster on the first request, take someload from the cpu, and prolly give a headache to someone findinga bug cause there was a cached not-up-to-date form. especially ifthe form depends on realtime data. but for simple forms this mightbe neat.o) prolly lots of documentation.o) encryption of hidden inputs so they are not seen in plaintext.o) some sort of hash to make sure the unchangeable (hidden) valueshave not been tricked by the user. (saved the form to his harddisk,...). checking the http_referer doesn't do it, of course.o) if possible, detect if the user changed something at all (in editmode). this could be useful to not update the data on the server.an update often starts a chain of human work. and if nothing changedanyway this only confuses ppl. hrm. mysql only updates the fieldsthat you set to a different value anyway. but does it also not toucha timestamp if nothing changed? this would help... but doesn't helpif you're going to update a datetime field yourself.todo:o) problem with valueDefault in multi-level forms. after level 1 itis not used anymore. step is 2 then, crap. recode a bit. 2002/05/06 --andrejo) on the server side, only validate the real inputs, not the hiddenfields, this is a waste of time.o) write a nice tutorial. document all the features. ppl don't wantto read the phpdoc :( especially step-by-step examples are needed.note: after the <form> tag there is the tag <bs_after_formopen_tag/>before the </form> tag there is the tag <bs_before_formclose_tag/>feel free to replace them with anything you want. eg add in somehidden fields, some html text, whatever.dependencies: Bs_FormContainer, Bs_ObjPersisterForMySql, Bs_FormTemplateParser,Bs_Db (for the saveToDb option), Bs_Array, Bs_HtmlUtil, $APP,Bs_Url, Bs_TextUtil, Bs_LanguageHandler

Authors andrej arn <andrej@arn.li>

Version 4.0.$id$

Copyright blueshoes.org

Methods inherited from Bs_Object

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

Public Method Summary
void	Bs_Form() Constructor.
string	&getForm([ string $withErrorTable ]) Returns html code to send to the browser which will display the web form
string	getFormTag() returns the form tag.
string	getFormHead() returns the 'form head' which includes the <form> tag, [javascripts]
string	getFormFoot() returns the 'form foot' which includes the </form> tag and the used fields (hidden).
void	getUsedFields() returns an html string that will be sent to the client inside the form.
bool	isMultiLevel() tells if this form is a multilevel form.
int	getNumbersOfLevels() returns the number of levels used in that form.
bool	isFirstLevel() tells if we're in the first level of a multilevel form.
bool	isLastLevel() tells if we're in the last level of a multilevel form.
bool	isMultipart() Tells whether this form is (or has to be treated as) a multipart form.
string	getMode() returns the form mode we're in.
bool	hasJavascript() tells whether the client browser has javascript support or not.
string	getElement(string $elementName, [ string $what, string $optionList ]) returns the element of one of the elements of this form.
bool	validate() validates the inputs of all fields that were sent. fills $this->errors if needed.
string	getErrorTable([ string $title ], string $style) returns a basic html string (html table) filled with the error messages
void	addError(string $errorMsg, [ string $fieldName, string $fieldCaption ]) adds an error to this form.
bool	isFieldFilledIn(string $fieldName) tells if the user filled in the given field somehow. does not tell if the
array	getFieldValue(string $fieldName, [ string $valueType ]) returns the field value you want.
void	setValuesToDefault() sets the fields valueInternal and valueDisplay to the same value as valueDefault is.
bool	setReceivedValues(array &$array) Sets the received values to the form fields of this form.
void	setLoadedValues(array &$array) Sets the loaded values to the form fields of this form.
void	postLoadTrigger() calls the post load triggers of the fields of this form.
void	seedClearingHouse([ string $onlyIfNotSet ]) seeds the var $clearingHouse.
bool	addIncludeOnce( $scriptUrl) adds a javascript source file to the include-once todo list.
mixed	getIncludeOnce([ string $how ]) returns the include-once script files.
bool	addOnLoadCode(string $code) javascript code that needs to be executed in the onLoad event of the page.
string	getOnLoadCode([ string $withCodeTags ]) returns the javascript code that needs to be executed in the onLoad event
string	getInHeadCode() returns the code that should be added in the document head.
void	setPersisterID(int $persisterID) set the form id for all elements.
mixed	saveToDb() saves the received form inputs according to the settings.
bool	doesDbTableExist([ string $dbTableName, string $useCache ]) tells if the db table exists. i mean the db table where the submitted
bool	createDbTable([ string $dbTableName ], array &$saveToDbArray) creates the db table. i mean the db table where the submitted values should get persisted.
bool	updateDbTableStructure([ string $dbTableName ], array &$saveToDbArray, [ string $checkOnly ]) checks if the db table structure is up-to-date and updates what's needed.
array	getSaveToDbArray() creates a hash with the information about which data to persist, and how.
array	getValuesArray([ string $shouldUseOnly, string $valueType, string $withCaption, string $captionLang, string $printable, string $useLevels ]) returns the desired values of the submitted fields (that we should use).
string	getInterfaceText(string $key, [ string $lang ]) returns a text string.

Private Method Summary
string	_getButtonString() returns a html string with the buttons to use.
bool	setBsFormData(array &$hash) sets the appropriate bs_form vars.
void	addIntoHead( $code) adds some code into the _inHead array that can later be included in the
bool	persist([ string $withElements ]) persist the form settings (with the attached form elements by default).Warning: documentation is missing.
bool	unPersist([ string $internalName, string $withElements ]) unpersist (load) the form settings (with the attached form elements by default).Warning: documentation is missing.
bool	getDbTableName() tells if the db table exists. i mean the db table where the submitted
string	_alterTableLineHelper( $fieldName, $dataType) returns an sql fragment that can be used in create/alter table queries.
bool	_loadInterfaceLanguage([ string $wantLang ]) loads a language file to be able to communicate with the user in the
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	jumpToFirstError( $useJsFile, $useJsFile, $useJsFile, $useJsFile, $useJsFile, $useJsFile, $jumpToFirstError, $jumpToFirstError, $useJsFile, $useJsFile, $useJsFile, $useJsFile, $useJsFile, string $jumpToFirstError) Warning: documentation is missing.

Public Field Summary
object [unknown]	$bsDb reference to the globally used db object.
object [unknown]	$Bs_TextUtil reference to the global pseudostatic Bs_TextUtil.
int	$disabledMode how disabled fields should be sent to the client. one of:
string	$mustFieldsVisualMode how must fields should be 'highlighted' in the browser.
bool	$useTemplate if we should use a template when an appropriate one is available. false unless
string	$templatePath the absolute path to the template(s). if not given then
mixed	$buttons we always need buttons to submit a form. because they change when
string	$internalName the name of this form in the database. may be different than $this->name
bool	$saveToDb save the values of this form to the db or not?
array	$dbDsn if the form has to be saved to another database/server/whatever
string	$dbName the db where the data should be stored automatically.
string	$dbTableName the table where the data should be stored autmatically. only a-z A-Z 0-9
array	$additionalParams hash holding additional data that needs to be persisted in the db.
bool	$sendMailRaw should we send the submitted data in an autogenerated email to somewhere?
array	$clearingHouse this is something between a hack, an optimization and a needed
string	$serializeType one of 'wddx' or 'php' (default).
string	$md5Key the md5 key to use to make sure the user did not cheat when submitting the form.
object [unknown]	$elementContainer an instance of Bs_FormContainer to keep track of all form elements.
int	$level this form class is multi-level capable. think about it like a

Private Field Summary
string	$persister instance of Bs_ObjPersisterForMySql to persist the settings.
int	$persisterID reserved var for the persister. don't fuck with this.
object [unknown]	$_Bs_Array reference to the global pseudostatic Bs_Array.
object [unknown]	$_Bs_HtmlUtil reference to the global pseudostatic Bs_HtmlUtil.
array	$_APP reference to the global settings array $APP.
string	$name the form name, as in <form name=$name>.
string	$action where to submit the form to, as in <form action=$action>.
string	$method what submit method to use, as in <form method=$method>.
string	$encType what encryption type to use, as in <form enctype=$enctype>.
string	$target to which target should the form be submitted to? as in <form target=$target>
array	$styles hash with style information. these keys can be used:
array	$advancedStyles you may want to display the input fields and their captions differently based on
bool	$useAccessKeys if set to true, access keys will be used for the fields even if the field
array	$accessKeyTags if a form field uses the accessKey setting, how should it be visible to the
string	$direction dir="rtl"
array	$events (javascript) events like onSubmit, ...
string	$onEnter browsers act differently when one hits enter in an input field.
string	$mailRawTo email to address
string	$mailRawCc email cc address
string	$mailRawBcc email bcc address
string	$mailRawSubject email subject
bool	$sendMailNice1 should we send the submitted data using a template by email to somewhere?
string	$mailNice1To email to address
string	$mailNice1Cc email cc address
string	$mailNice1Bcc email bcc address
string	$mailNice1Subject email subject
string	$mailNice1Template email template
array	$_guiLangHash language strings loaded from files.
array	$fieldsUsed when the form has been submitted, there is a hidden field with the
bool	$hasJavascript cached information if the client browser has javascript support.
array	$errors holds the errors that occured during the validating of the form fields.
string	$mode the form mode we're in. one of 'add', 'edit', 'delete' and 'view'.
int	$_prevLevel hrm.
int	$_nextLevel hrm.
integer	$step the form step we're in. default is 1, can be 2.
string	$state the form state we're in. default is 'form', one of
integer	$viewCount counts the number of times the form was displayed to the client until it was
mixed	$startTimestamp the timestamp when the form was sent to the browser for the first time.
int	$usedTime once the form is 'done' this is set to the used time. (actual time - $startTimestamp)
string	$language the language we use for that form.
int	$recordId usually the form is here to edit data from a database. which record? this one.
string	$user the user/group (based on a session?) that is using the form.
array	$accessRights the vector holds hashes with these keys:
string	$useJsFile use the externally linked js file? (Bs_FormUtil.lib.js)
array	$_includeOnce javascript source files that need to be included - but only once for that page.
array	$_onLoad javascript code that needs to be executed in the onLoad event of the page.
array	$_inHead stuff (html/javascript/...) to put into the document head.
string	$jumpToFirstError if we should insert the javascript trigger to jump into the first
array	$persisterVarSettings
unknown	$this

Private Constant Summary
BS_FORM_VERSION	>>`4.0.$x$`<<	Warning: documentation is missing.

Public Method Details

Bs_Form

public void Bs_Form( )

Constructor.

Returns

void

&getForm

public string &getForm( [ string $withErrorTable ] )

Returns html code to send to the browser which will display the web form
with all its form fields.

Parameter

string	$withErrorTable	`= >>FALSE<<`
	(if the error table should automatically come with it if errors occured. default is FALSE.)

Returns

string

(html code)

See Also getIncludeOnce(), getOnLoadCode()

getFormTag

public string getFormTag( )

returns the form tag.

Returns

string

some html code.

getFormHead

public string getFormHead( )

returns the 'form head' which includes the <form> tag, [javascripts]
and hidden/internal fields.

Returns

string

some html code.

getFormFoot

public string getFormFoot( )

returns the 'form foot' which includes the </form> tag and the used fields (hidden).

Returns

string

some html code.

getUsedFields

public void getUsedFields( )

returns an html string that will be sent to the client inside the form.
it has 2 hidden fields, one for the fields used, one md5 to avoid cheating.you have to call this method after doing the $this->elementContainer->getElement()because otherwise the fields don't know yet if they will be used or not.does not move the pointer of $this->clearingHouse.

Returns

void

isMultiLevel

public bool isMultiLevel( )

tells if this form is a multilevel form.

Returns

bool

See Also $this

getNumbersOfLevels

public int getNumbersOfLevels( )

returns the number of levels used in that form.
if it's not a multilevel form then 1 is returned.a simple form can be seen as a 1-level form.

Returns

int

isFirstLevel

public bool isFirstLevel( )

tells if we're in the first level of a multilevel form.
note: also returns TRUE if it's not a multilevel form causethen it's the first level aswell.

Returns

bool

isLastLevel

public bool isLastLevel( )

tells if we're in the last level of a multilevel form.
note: also returns TRUE if it's not a multilevel form causethen it's the last level aswell.

Returns

bool

isMultipart

public bool isMultipart( )

Tells whether this form is (or has to be treated as) a multipart form.
a multipart form is one with at least one <input type=file> field.the form turns into a multipart form when one of these conditions is true:1) the user set $this->encType to 'multipart/form-data'2) the form has at least one file field which is in use.

Returns

bool

true if it's a multipart form, false if not.

See Also $this

getMode

public string getMode( )

returns the form mode we're in.

Returns

string

one of 'add', 'edit', 'delete', 'view'. the mode that is set, or '' if nothing is set.

See Also $this

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

getElement

public string getElement( string $elementName, [ string $what, string $optionList ] )

returns the element of one of the elements of this form.
caution: moves the pointer of $this->clearingHouse.

Parameter

string	$elementName
	(the name of the form field or element)

string	$what	`= >>'element'<<`
	one of 'element' (default), 'caption', 'text', 'error', 'help'.

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

Returns

string

(text or html)

Throws empty string '' if no such element.

validate

public bool validate( )

validates the inputs of all fields that were sent. fills $this->errors if needed.
changes $this->state, $this->step and $this->level if needed.sets $this->usedTime if needed.caution: moves the pointer of $this->clearingHouse.

Returns

bool

See Also $this

getErrorTable

public string getErrorTable( [ string $title ], string $style )

returns a basic html string (html table) filled with the error messages
to display on the website.

Parameter

string	$title	`= >>NULL,<<`
	a string (may include html) that is set above of the html table. $param string $style default is 'default', nothing available yet.

string	$style
	Warning: documentation is missing.

Returns

string

an html string.

Throws string an empty string if no errors occured.

addError

public void addError( string $errorMsg, [ string $fieldName, string $fieldCaption ] )

adds an error to this form.
if $fieldName is NULL it is considered a vector element. see $this->errors.

Parameter

string	$errorMsg

string	$fieldName	`= >>NULL,<<`

string	$fieldCaption	`= >>NULL<<`

Returns

void

See Also $this

isFieldFilledIn

public bool isFieldFilledIn( string $fieldName )

tells if the user filled in the given field *somehow*. does not tell if the
input was ok/accepted.does not move the pointer of $this->clearingHouse.

Parameter

string	$fieldName

Returns

bool

Throws NULL if no such field, not a field, or not capable to tell.

getFieldValue

public array getFieldValue( string $fieldName, [ string $valueType ] )

returns the field value you want.
does not move the pointer of $this->clearingHouse.

Parameter

string	$fieldName

string	$valueType	`= >>'internal'<<`
	one of 'internal' (default), 'default', 'received', 'display'.

Returns

array

a vector with exactly one element (key = 0) that holds the field value. this way of returning is needed to make a difference to 'dunno'.

Throws NULL if no such field, not a field, or not capable to tell.

setValuesToDefault

public void setValuesToDefault( )

sets the fields valueInternal and valueDisplay to the same value as valueDefault is.
caution: moves the pointer of $this->clearingHouse.

Returns

void

setReceivedValues

public bool setReceivedValues( array &$array )

Sets the received values to the form fields of this form.
also calls setBsFormData() if needed.!!! does not modify $step any more. 2002/05/07 --andrejcaution: moves the pointer of $this->clearingHouse.

Parameter

array	&$array

Returns

bool

TRUE

Throws bs_exception

setLoadedValues

public void setLoadedValues( array &$array )

Sets the loaded values to the form fields of this form.
also sets $step to 1. call setBsFormData() yourself if you need it.caution: moves the pointer of $this->clearingHouse.

Parameter

array	&$array
	(hash where key=fieldname and value=value.)

Returns

void

postLoadTrigger

public void postLoadTrigger( )

calls the post load triggers of the fields of this form.
caution: moves the pointer of $this->clearingHouse.

Returns

void

seedClearingHouse

public void seedClearingHouse( [ string $onlyIfNotSet ] )

seeds the var $clearingHouse.

Parameter

string	$onlyIfNotSet	`= >>TRUE<<`
	default is TRUE. if set to true it will only be done if $clearingHouse is not set yet.

Returns

void

addIncludeOnce

public bool addIncludeOnce( $scriptUrl )

adds a javascript source file to the include-once todo list.
it's a good practise to write them the same way all the time (relative/absolute)to avoid problems.

Parameter

	$scriptUrl
	Warning: documentation is missing.

Returns

bool

(TRUE if the script was added, FALSE if it was already there.)

See Also $_includeOnce, getIncludeOnce()

getIncludeOnce

public mixed getIncludeOnce( [ string $how ] )

returns the include-once script files.
param $how: can be 'array' (default) or 'string'.for 'array' you get a vector with all script url's (empty array if none).for 'string' you get an html string with the script tags to echoto your browser (empty string if none).

Parameter

string	$how	`= >>'array'<<`
	(see above)

Returns

mixed

(array or string, see param $how)

See Also $_includeOnce, addIncludeOnce()

addOnLoadCode

public bool addOnLoadCode( string $code )

javascript code that needs to be executed in the onLoad event of the page.

Parameter

string	$code
	(javascript code)

Returns

bool

TRUE .

getOnLoadCode

public string getOnLoadCode( [ string $withCodeTags ] )

returns the javascript code that needs to be executed in the onLoad event
of the page.if param $withCodeTags is TRUE then you'll get script tags wrapped around,everything is prepared to paste it into the html-document. example:<script type='text/javascript'></script>

Parameter

string	$withCodeTags	`= >>TRUE<<`
	(default is TRUE, see above.)

Returns

string

getInHeadCode

public string getInHeadCode( )

returns the code that should be added in the document head.

Returns

string

setPersisterID

public void setPersisterID( int $persisterID )

set the form id for all elements.
special method for the persister. rtfm.

Parameter

int	$persisterID

Returns

void

saveToDb

public mixed saveToDb( )

saves the received form inputs according to the settings.
if the db table doesn't exist yet, it will be created automatically.if it exists and problems occure while inserting, the table structurewill be updated.on an insert, $this->recordId will be set.

Returns

mixed

(bool FALSE if nothing had to be saved, bool TRUE on a successful update, int >=1 on a successful insert (=the new record id))
@throw bs_exception if something should have been saved but failed somewhere.

doesDbTableExist

public bool doesDbTableExist( [ string $dbTableName, string $useCache ] )

tells if the db table exists. i mean the db table where the submitted
values should get persisted.

Parameter

string	$dbTableName	`= >>NULL,<<`
	default is NULL which means get it yourself. you may pass it here if you already have it as optimization.

string	$useCache	`= >>TRUE<<`
	default is TRUE. if the table could have been created lately you better set it to FALSE.

Returns

bool

TRUE if it exists, FALSE if not
@throw Bs_Exception

createDbTable

public bool createDbTable( [ string $dbTableName ], array &$saveToDbArray )

creates the db table. i mean the db table where the submitted values should get persisted.

Parameter

string	$dbTableName	`= >>NULL,<<`
	default is NULL which means get it yourself. you may pass it here if you already have it as optimization.

array	&$saveToDbArray
	the output of $this->getSaveToDbArray().

Returns

bool

TRUE on success
@throw Bs_Exception

updateDbTableStructure

public bool updateDbTableStructure( [ string $dbTableName ], array &$saveToDbArray, [ string $checkOnly ] )

checks if the db table structure is up-to-date and updates what's needed.

Parameter

string	$dbTableName	`= >>NULL,<<`
	default is NULL which means get it yourself. you may pass it here if you already have it as optimization.

array	&$saveToDbArray
	the output of $this->getSaveToDbArray().

string	$checkOnly	`= >>FALSE<<`
	default is FALSE. if set to true, no changes will be made.

Returns

bool

TRUE if we have made changes, FALSE if not
@throw bs_exception

getSaveToDbArray

public array getSaveToDbArray( )

creates a hash with the information about which data to persist, and how.
the scructure looks like this:$hash['fieldName'] = array('valueInternal' =>'something','neededDataType' =>'varchar','neededIndex' =>FALSE,'availableDataType' =>'varchar','availableIndex' =>FALSE,'shouldModifyType' =>FALSE,'shouldAddIndex' =>FALSE,'shouldPersist' =>TRUE);so the key of the hash is the fieldname (as it should be in the db).valueInternal is what we got from the browser. mostly a string, buttake care, it might be an array (explodable fields,select fields with property 'multiple').it is a reference, so don't fuck with it.neededDataType is $dbDataType of the field, or if not set then it'swhat we made up for it. the the received value doesn'tfit into that, then we might have to use some imagination.neededIndex is TRUE if the field is set to mustBeUnique, FALSE otherwise.availableDataType is the field type that we currently have in the db.availableIndex is if there's currently an index set in the db.shouldModifyType is true if we should convert the field type. we neverdownsize anything. a few notes:char is always converted to varchar. varchar always usesthe max (255) as size. int is never downsized to tinyint, etc.shouldAddIndex as you can see, the var name is shouldADD not shouldMODIFY.we never 'downsize' here also. someone could have gone intothe db directly and set an index, so we will never remove one.all we do is add it if the field has become mutBeUniquesuddenly.shouldPersist tells us if we should persist the data we got this time.for example in edit mode we don't update some things.

Returns

array

(hash, see above)

getValuesArray

public array getValuesArray( [ string $shouldUseOnly, string $valueType, string $withCaption, string $captionLang, string $printable, string $useLevels ] )

returns the desired values of the submitted fields (that we should use).
does not move the pointer of $this->clearingHouse.

Parameter

string	$shouldUseOnly	`= >>TRUE,<<`
	default is TRUE. if set to true, only the fields are returned that should be used/persisted on the serverside.

string	$valueType	`= >>'valueDisplay'<<`
	one of 'valueInternal', 'valueDisplay' (default), 'valueReceived', 'valueDefault'

string	$withCaption	`= >>FALSE,<<`
	(default is FALSE. would return a hash holding vectors where element 0 is the value and element 1 is the caption (in the current language).)

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

string	$printable	`= >>FALSE,<<`
	(if you want nice human-readable output for values, set this to true. eg checkboxes return 'yes/no' instead of 0/1 values.)

string	$useLevels	`= >>null<<`
	(vector filled with integers, null means all steps.)

Returns

array

(hash where key is the internally used field name, value the value or a hash (see param $withCaption). may be an empty array if nothing is available.)

getInterfaceText

public string getInterfaceText( string $key, [ string $lang ] )

returns a text string.

Parameter

string	$key

string	$lang	`= >>null<<`

Returns

string

Throws empty string '' if a key is not defined or a language can in no way be loaded.

See Also _loadInterfaceLanguage(), $_guiLangHash

Private Method Details

_getButtonString

private string _getButtonString( )

returns a html string with the buttons to use.
the return value depends on the mode we're in.

Returns

string

setBsFormData

private bool setBsFormData( array &$hash )

sets the appropriate bs_form vars.
so if you want to use different values, have this method be called first,then change what you want.

Parameter

array	&$hash
	(see class description for details)

Returns

bool

TRUE on success, FALSE if there's a problem with the md5 stuff. (cheater)

addIntoHead

private void addIntoHead( $code )

adds some code into the _inHead array that can later be included in the
document head.

Parameter

	$code
	Warning: documentation is missing.

Returns

void

persist

private bool persist( [ string $withElements ] )

persist the form settings (with the attached form elements by default).

Warning: documentation is missing.

Parameter

string	$withElements	`= >>TRUE<<`
	default is TRUE

Returns

bool

true on success
@throw bs_exception on error (db exception)

unPersist

private bool unPersist( [ string $internalName, string $withElements ] )

unpersist (load) the form settings (with the attached form elements by default).

Warning: documentation is missing.

Parameter

string	$internalName	`= >>NULL,<<`
	the internally used form name. if not set, $this->persisterID is used. so set it before!

string	$withElements	`= >>TRUE<<`
	default is TRUE

Returns

bool

true on success, false on failure
@throw bs_exception on error (db exception)

getDbTableName

private bool getDbTableName( )

tells if the db table exists. i mean the db table where the submitted
values should get persisted.

Returns

bool

TRUE if it exists, FALSE if not
@throw Bs_Exception

_alterTableLineHelper

private string _alterTableLineHelper( $fieldName, $dataType )

returns an sql fragment that can be used in create/alter table queries.
moved here so it can be used from createDbTable() and updateDbTableStructure().

Parameter

	$fieldName
	Warning: documentation is missing.

	$dataType
	Warning: documentation is missing.

Returns

string

See Also createDbTable(), updateDbTableStructure()

_loadInterfaceLanguage

private bool _loadInterfaceLanguage( [ string $wantLang ] )

loads a language file to be able to communicate with the user in the
desired language.it is possible that we need to load more than one language for a form,for example if the customer fills in the form in german, but the webmasterwants the results by email in english. at least with field captions that'sthe case, not sure here. but it could be possible, so we code it that way.if the lang is already loaded, it won't be done again.

Parameter

string	$wantLang	`= >>null<<`
	(what lang you want to load, if not specified then the lang of this form will be loaded.)

Returns

bool

(TRUE on success, FALSE on failure. also TRUE if already loaded.)

See Also getInterfaceText(), $_guiLangHash

_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

jumpToFirstError

private void jumpToFirstError( $useJsFile, $useJsFile, $useJsFile, $useJsFile, $useJsFile, $useJsFile, $jumpToFirstError, $jumpToFirstError, $useJsFile, $useJsFile, $useJsFile, $useJsFile, $useJsFile, string $jumpToFirstError )

Warning: documentation is missing.

Parameter

	$useJsFile
	Warning: documentation is missing.

	$useJsFile
	Warning: documentation is missing.

	$useJsFile
	Warning: documentation is missing.

	$useJsFile
	Warning: documentation is missing.

	$useJsFile
	Warning: documentation is missing.

	$useJsFile
	Warning: documentation is missing.

	$jumpToFirstError
	Warning: documentation is missing.

	$jumpToFirstError
	Warning: documentation is missing.

	$useJsFile
	Warning: documentation is missing.

	$useJsFile
	Warning: documentation is missing.

	$useJsFile
	Warning: documentation is missing.

	$useJsFile
	Warning: documentation is missing.

	$useJsFile
	Warning: documentation is missing.

string	$jumpToFirstError
	Warning: documentation is missing.

Returns

void

Public Field Details
$bsDb
public object [unknown] $bsDb >><< reference to the globally used db object. used for the saveToDb option.

$Bs_TextUtil
public object [unknown] $Bs_TextUtil >><< reference to the global pseudostatic Bs_TextUtil.

$disabledMode
public int $disabledMode >><< how disabled fields should be sent to the client. one of: 1 => (default) internet explorer style with the properties 'disabled' and 'readonly'depending on the tag.2 => javascript; javascript prevents the user from making changes.3 => html; type=text will be sent as plain text, for radio/checkboxes images are sent...

$mustFieldsVisualMode
public string $mustFieldsVisualMode >>`'starLeft'`<< how must fields should be 'highlighted' in the browser. one of 'none', 'starLeft', 'starRight'. (i hope 'star' is the right word for a '*'.)if nothing is set, 'starLeft' is used (so it's the default).

$useTemplate
public bool $useTemplate >><< if we should use a template when an appropriate one is available. false unless set to TRUE.to see how templates are named see the phpdoc of Bs_FormTemplateParser->loadTemplate().note: containers can now have their own templates.
See Also	$templatePath

$templatePath
public string $templatePath >><< the absolute path to the template(s). if not given then getAbsolutePath() . '../templates/'will be used which kinda sucks. so you better set that...
See Also	$useTemplate

$buttons
public mixed $buttons >><< we always need buttons to submit a form. because they change when we change the form mode, we need to be able to define differentbuttons for each mode.you can - for example for a contact form where you need no editmode - define a "submit" button and use that one. and ignore thisvar. but if you want to use debedoo, you certainly want this option.data structure:one ofbuttons[mode][button] = caption //all languages use the same captionbuttons[mode][button][lang] = caption //language dependant$buttons = array('view' => array('edit' => array('en'=>'edit', 'de'=>'bearbeiten'),'delete' => array('en'=>'delete', 'de'=>'l�schen'),'cancel' => array('en'=>'overview', 'de'=>'�bersicht')),'edit' => array('save' => array('en'=>'save', 'de'=>'speichern'),'cancel' => array('en'=>'cancel', 'de'=>'abbrechen'),'next' => array('en'=>'next', 'de'=>'weiter'),'back' => array('en'=>'back', 'de'=>'zur�ck')),'add' => array('save' => array('en'=>'add', 'de'=>'hinzuf�gen'),'cancel' => array('en'=>'cancel', 'de'=>'abbrechen'),'next' => array('en'=>'next', 'de'=>'weiter'),'back' => array('en'=>'back', 'de'=>'zur�ck')),'delete' => array('save' => array('en'=>'delete', 'de'=>'l�schen'),'cancel' => array('en'=>'cancel', 'de'=>'abbrechen')),'search' => array('go' => array('en'=>'search', 'de'=>'suchen')));what you can do is set the caption of the buttons. define your language.if a button caption is not defined at all, the button won't be used.example: $buttons['view']['cancel'] = null;special case:maybe you're happy with default captions (although i bet most clientswant different captions 5 minutes before going live).if so, you can set $buttons to string 'default'. in that case the $buttonsvar will be used like what you see in the definiton above.if you don't want this at all set it to FALSE or don't set it at all.
See Also	_getButtonString()

$internalName
public string $internalName >><< the name of this form in the database. may be different than $this->name because of javascripts that depend on a name.

$saveToDb
public bool $saveToDb >><< save the values of this form to the db or not?
See Also	$dbTableName

$dbDsn
public array $dbDsn >><< if the form has to be saved to another database/server/whatever then you can give the db information here. it's a dsn as always:KEYS:'host''port''syntax''type''user''pass'be aware of the fact that this data has to be stored along with theform settings, and that isn't very secure. although it's set tobe cryptified. a stackdump could be dangerous.

$dbName
public string $dbName >><< the db where the data should be stored automatically. if not given, the currently used db (global db) will be used.
See Also	$saveToDb, $dbTableName

$dbTableName
public string $dbTableName >><< the table where the data should be stored autmatically. only a-z A-Z 0-9 is allowed, no underscore, no 'minus' (_-). it has to start with thestring 'form'.if not given, the var $internalName is used with the prefix 'form'.
See Also	$saveToDb, $dbName

$additionalParams
public array $additionalParams >><< hash holding additional data that needs to be persisted in the db. you may need to store data into the db that does not come from the user input.it may be computed from some user input, for example.the key is the field name, the value needs to be a vector with exactly 3 elements.element[0] tells the type ('text' (default) or 'code'),element[1] is the mode (one of 'add', 'edit', 'both', 'none'), andelement[2] is the value.for 'code' the value is treated as php code and thus evaluated (in $this->_evalWrap()).it is only done if the mode matches, of course. invalid mode is treated as 'none'.

$sendMailRaw
public bool $sendMailRaw >><< should we send the submitted data in an autogenerated email to somewhere?

$clearingHouse
public array $clearingHouse >><< this is something between a hack, an optimization and a needed construct. normally the form wouldn't know directly which elements(and fields) are attached to it. it only knows about$elementContainer, which knows its elements including othercontainers, which again only knows about its elements.with this clearing house we have a reference to every element object.
See Also	$this

$serializeType
public string $serializeType >>`'php'`<< one of 'wddx' or 'php' (default). old comment:i have used

BlueShoes Application Framework - Form

Bs_Form

public class Bs_Form extends Bs_Object

Methods inherited from Bs_Object

Public Method Summary

Bs_Form()

&getForm([ string $withErrorTable ])

getFormTag()

getFormHead()

getFormFoot()

getUsedFields()

isMultiLevel()

getNumbersOfLevels()

isFirstLevel()

isLastLevel()

isMultipart()

getMode()

hasJavascript()

getElement(string $elementName, [ string $what, string $optionList ])

validate()

getErrorTable([ string $title ], string $style)

addError(string $errorMsg, [ string $fieldName, string $fieldCaption ])

isFieldFilledIn(string $fieldName)

getFieldValue(string $fieldName, [ string $valueType ])

setValuesToDefault()

setReceivedValues(array &$array)

setLoadedValues(array &$array)

postLoadTrigger()

seedClearingHouse([ string $onlyIfNotSet ])

addIncludeOnce( $scriptUrl)

getIncludeOnce([ string $how ])

addOnLoadCode(string $code)

getOnLoadCode([ string $withCodeTags ])

getInHeadCode()

setPersisterID(int $persisterID)

saveToDb()

doesDbTableExist([ string $dbTableName, string $useCache ])

createDbTable([ string $dbTableName ], array &$saveToDbArray)

updateDbTableStructure([ string $dbTableName ], array &$saveToDbArray, [ string $checkOnly ])

getSaveToDbArray()

getValuesArray([ string $shouldUseOnly, string $valueType, string $withCaption, string $captionLang, string $printable, string $useLevels ])

getInterfaceText(string $key, [ string $lang ])

Private Method Summary

_getButtonString()

setBsFormData(array &$hash)

addIntoHead( $code)

persist([ string $withElements ])

unPersist([ string $internalName, string $withElements ])

getDbTableName()

_alterTableLineHelper( $fieldName, $dataType)

_loadInterfaceLanguage([ string $wantLang ])

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

jumpToFirstError( $useJsFile, $useJsFile, $useJsFile, $useJsFile, $useJsFile, $useJsFile, $jumpToFirstError, $jumpToFirstError, $useJsFile, $useJsFile, $useJsFile, $useJsFile, $useJsFile, string $jumpToFirstError)

Public Field Summary

$bsDb

$Bs_TextUtil

$disabledMode

$mustFieldsVisualMode

$useTemplate

$templatePath

$buttons

$internalName

$saveToDb

$dbDsn

$dbName

$dbTableName

$additionalParams

$sendMailRaw

$clearingHouse

$serializeType

$md5Key

$elementContainer

$level

Private Field Summary

$persister

$persisterID

$_Bs_Array

$_Bs_HtmlUtil

$_APP

$name