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

Class: Bs_Form

Source Location: /core/html/form/Bs_Form.class.php

Class Overview

Bs_Object
   |
   --Bs_Form

Form Class


Author(s):

Version:

  • 4.3.$Revision: 1.8 $ $Date: 2003/12/14 09:52:03 $

Copyright:

  • blueshoes.org

Variables

Methods


Inherited Variables

Inherited Methods

Class: Bs_Object

Bs_Object::Bs_Object()
Bs_Object::getErrors()
Basic error handling: Get *all* errors as string array from the global Bs_Error-error stack.
Bs_Object::getLastError()
Basic error handling: Get last error string from the global Bs_Error-error stack.
Bs_Object::getLastErrors()
Basic error handling: Get last errors string array from the global Bs_Error-error stack sinc last call of getLastErrors().
Bs_Object::persist()
Persists this object by serializing it and saving it to a file with unique name.
Bs_Object::setError()
Basic error handling: Push an error string on the global Bs_Error-error stack.
Bs_Object::toHtml()
Dumps the content of this object to a string using PHP's var_dump().
Bs_Object::toString()
Dumps the content of this object to a string using PHP's var_dump().
Bs_Object::unpersist()
Fetches an object that was persisted with persist()

Class Details

[line 207]
Form Class

implementation of an html form. holds (uses) instances of FormElement. please read http://www.blueshoes.org/en/framework/html/form/

this flowchart shows how records can be added/edited using this form class. the delete mode works slightly different (there is no validation).

   +---------------------------+
   |                           |
   |      +----------------+   |   +--------------+
   |      |                |   |   |              |
   |      |        +----------------------+       |
   |      |        |        FORM          |       |
   |      |        |                      |       |
   |      |        |       |       |
   |    error      +----------------------+     error
   |   occured          |            |         occured
   |      |             |            |            |
   |      +---- < validate >      < validate > ---+
   |                    |            |
   |                    |            |
   |       +--------------------+    |
   |       |      PREVIEW       |    |
   |       |                    |    |
   |       |        |    |
   |       +--------------------+    |
   |           |           |         |
   +-----------+           |         |
                           |         |
                       +--------------------+
                       |        DONE        |
                       |                    |
                       |      thank you     |
                       +--------------------+

 

the hash 'bs_form' including the following hidden vars is submitted along with the form all the time:

   NAME             VALUE                          DESCRIPTION
   name             the INTERNAL 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 your server, but this is a bad idea. you'd block out users with old/strange clients that don't send the http_referer, ppl using anomyzers/firewalls, and 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, and thus which fields he has to validate? we could loop $HTTP_POST_VARS because every submitted field has a key in this array. but again, we get the *submitted* fields, and not those which someone has removed with the save-to-disc cheat.

so the only secure way is to send a cryptified list of fields as a hidden input. we'd need to crypt hidden values also, but let's not get paranoid at the moment.

also the use of the preview mode might be a risk. when submitting the preview page, the inputs are not checked again. good place to cheat...

features:

  • multilevel forms (yah! :)
  • templates (for the form AND for containers)
  • multilingual
  • very strong on (serverside) input validation
  • can deal with hitting enter in text fields
  • offers some nice domapi form element implementations
  • and some more ready-to-use out-of-the-box special fields.
  • can deal with include-once and onLoad javascript stuff

features to add: (wishlist)

  • cache the form (html output) for each language. then spit this out instead of generating the form on every (first) request. the cache needs to be updated if someone makes changes to form/elements. this will make the forms load alot faster on the first request, take some load from the cpu, and prolly give a headache to someone finding a bug cause there was a cached not-up-to-date form. especially if the form depends on realtime data. but for simple forms this might be neat.
  • prolly lots of documentation.
  • encryption of hidden inputs so they are not seen in plaintext.
  • some sort of fingerprint to make sure the unchangeable (hidden) values have not been tricked by the user. (saved the form to his harddisk, ...). checking the http_referer doesn't do it, of course.
  • if possible, detect if the user changed something at all (in edit mode). this could be useful to not update the data on the server. an update often starts a chain of human work. and if nothing changed anyway this only confuses ppl. hrm. mysql only updates the fields that you set to a different value anyway. but does it also not touch a timestamp if nothing changed? this would help... but doesn't help if you're going to update a datetime field yourself.

todo:

  • problem with valueDefault in multi-level forms. after level 1 it is not used anymore. step is 2 then, crap. recode a bit. 2002/05/06 --andrej
  • on the server side, only validate the real inputs, not the hidden fields, this is a waste of time.
  • write a nice tutorial. document all the features. ppl don't want to read the phpdoc :( especially more 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 some hidden 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




Tags:

copyright:  blueshoes.org
pattern:  singleton: (pseudostatic)
access:  public
version:  4.3.$Revision: 1.8 $ $Date: 2003/12/14 09:52:03 $
author:  andrej arn <at blueshoes dot org>


[ Top ]


Class Variables

$accessKeyTags =

[line 433]

if a form field uses the accessKey setting, how should it be visible to the user? the key usually has an underscore in the caption. so $accessKeyTags would be array('<u>', '</u>') but it can be anything you like.

example: $accessKeyTags = array('<u>', '</u>'); $caption = "Firstname"; $accessKey = "r"; => "Fi<u>r</u>stname"

if it's not set [correctly], and there are accessKey's set, array('<u>', '</u>') will be used.




Tags:

var:  (vector with 2 elements)
see:  var $useAccessKeys

Type:   array


[ Top ]

$action =

[line 317]

where to submit the form to, as in <form action=$action>.

if not set or an empty string, we submit to the user-requested page. note: we don't submit to $_SERVER['PHP_SELF'] but use Bs_Url::getUrlJunk('8') instead. rtfm.



Type:   string


[ Top ]

$additionalParams =

[line 728]

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'), and element[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'.




Tags:

var:  (hash holding vector with 3 elements)
access:  public

Type:   array


[ Top ]

$advancedStyles =

[line 406]

you may want to display the input fields and their captions differently based on the facts if the fields need to be filled out and if the input was ok. that's what this var is for.

hash with the following keys: captionMust captionMustOkay captionMustWrong captionMay captionMayOkay captionMayWrong fieldMust fieldMustOkay fieldMustWrong fieldMay fieldMayOkay fieldMayWrong

caption: the caption for a field. field : the field itself. must : the field is a must field. may : the field is not a must field. : the form is displayed for the first time. (not okay nor wrong, just nothing) okay : the form has been submitted and the input (if any) was accepted. wrong : the form has been submitted and the input (if any) was not accepted.

the values for your keys are the css class names (not style definitions themself, actually). if a key is not set or empty, it is not used at all.




Tags:

access:  public

Type:   array


[ Top ]

$bsDb =

[line 272]

reference to the globally used db object.

used for the saveToDb option.



Type:   object


[ Top ]

$Bs_TextUtil =

[line 293]

reference to the global pseudostatic Bs_TextUtil.



Tags:

access:  public

Type:   object


[ Top ]

$buttons =

[line 651]

we always need buttons to submit a form. because they change when we change the form mode, we need to be able to define different buttons for each mode.

you can - for example for a contact form where you need no edit mode - define a "submit" button and use that one. and ignore this var. but if you want to use debedoo, you certainly want this option.

data structure: one of buttons[mode][button] = caption //all languages use the same caption buttons[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 clients want different captions 5 minutes before going live). if so, you can set $buttons to string 'default'. in that case the $buttons var 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.




Tags:

var:  (string, hash or bool FALSE, see above)
see:  _getButtonString()
access:  public

Type:   mixed


[ Top ]

$clearingHouse =

[line 830]

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 other containers, which again only knows about its elements. with this clearing house we have a reference to every element object.




Tags:

var:  (a hash, key = element name, value = reference to the object)
see:  $this->seedClearingHouse()
access:  public

Type:   array


[ Top ]

$dbDsn =

[line 690]

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 the form settings, and that isn't very secure. although it's set to be cryptified. a stackdump could be dangerous.




Tags:

var:  (hash, see above)
access:  public

Type:   array


[ Top ]

$dbName =

[line 700]

the db where the data should be stored automatically.

if not given, the currently used db (global db) will be used.




Tags:

todo:  make use of this var.
see:  vars $saveToDb, Bs_Form::$dbTableName
access:  public

Type:   string


[ Top ]

$dbTableName =

[line 711]

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 the string 'form'.

if not given, the var $internalName is used with the prefix 'form'.




Tags:

see:  vars $saveToDb, Bs_Form::$dbName
access:  public

Type:   string


[ Top ]

$direction =

[line 443]

dir="rtl" the direction in which the text is written.

one of ltr (left to right) <= default rtl (right to left) ie5+




Tags:

var:  (not set means ltr)

Type:   string


[ Top ]

$disabledMode =

[line 500]

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




Tags:

access:  public

Type:   int


[ Top ]

$elementContainer =

[line 879]

an instance of Bs_FormContainer to keep track of all form elements.

this is a pseudo container to make things easier.




Tags:

access:  public

Type:   object


[ Top ]

$elementLayouts =

[line 558]

layouts for the elements (form fields etc).

example: $elementLayouts = array( 'field' => array( '_default' => '<tr><td nowrap valign="top" align="left" width="20%">__CAPTION_FOR_FORM_OUTPUT__</td><td>__ELEMENT__</td></tr>', 'button' => '<tr><td colspan="100%">__ELEMENT__</td></tr>', 'reset' => '_button', 'submit' => '_button', ), '_default' => '<tr><td colspan="2" valign="top" align="left">__ELEMENT__</td></tr>', 'container' => '<tr><td colspan="2" valign="top" align="left">__ELEMENT__</td></tr>', );




Tags:

see:  $this->loadSkin(), Bs_FormElement->getElementLayout(), var Bs_FormElement->elementLayout etc
since:  bs4.3
access:  public

Type:   array


[ Top ]

$encType =

[line 344]

what encryption type to use, as in <form enctype=$enctype>.

one of application/x-www-form-urlencoded => default multipart/form-data => required for INPUT TYPE=FILE text/plain => for mailto: only

if not set, it's omitted. it is the recommended way not to add the enctype=$enctype to the form tag if it's the default.

if there is an <input type=file> used in the form, this var is automatically set to 'multipart/form-data' no matter what you set it to.




Tags:

see:  $this->isMultipart()

Type:   string


[ Top ]

$errors =

[line 902]

holds the errors that occured during the validating of the form fields.

usually it's just a hash holding another hash, where the key of the first hash is the fieldname, the key/value of the 2nd hash is the field caption and error message. it may have vector elements with just a string as text.

example: $errors['0'] = "some error text"; $errors['username'] = array('Username' => 'too short'); $errors['password'] = array('Password' => 'may not be equal to username');

if not set, no errors occured and everything is fine.



Type:   array


[ Top ]

$errorTableLayout =  ''

[line 571]

Mini layout of the error table that is used in the form when an error occured.

example: $errorTableLayout = '<table><tr><td><img src='error.gif'></td><td>__*__</td></tr></table>';




Tags:

see:  $this->getErrorTable()
since:  bs4.3
access:  public

Type:   string


[ Top ]

$events =

[line 460]

(javascript) events like onSubmit, ...

the currently (2001/04/27) available events are:

  • onSubmit - onDblClick - onMouseOver - onKeyPress
  • onRest - onMouseDown - onMouseMove - onKeyDown
  • onClick - onMouseUp - onMouseOut - onKeyUp
set the keys exactly like written above (case). otherwise we get in trouble when merging more events into one, and there may be bugs. i'd prefer to have it all lowercase, that would be easier. i should have done that right from the start. but now we're here and i cannot change it. :/




Tags:

var:  (hash)

Type:   array


[ Top ]

$fieldsUsed =

[line 845]

tells which fields have been submitted.

when the form has been submitted, there is a hidden field with the information about which fields have been sent to the client. so we only work with these fields. gets set in setBsFormData().

multilevel forms: fields that have been used in previous levels won't be included in that array. of course the same applies for fields (and elements) that will be used in later levels.




Tags:

var:  (vector, value is the internal field name.)
see:  Bs_Form::setBsFormData(), Bs_Form::getUsedFields()

Type:   array


[ Top ]

$hasJavascript =

[line 886]

cached information if the client browser has javascript support.



Tags:

see:  $this->hasJavascript()

Type:   bool


[ Top ]

$internalName =

[line 661]

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



Tags:

access:  public

Type:   string


[ Top ]

$jumpToFirstError =  FALSE

[line 1144]

When the form has been submitted but something is wrong in a field, the cursor can be set into the first faulty field automatically using javascript.

the javascript function jumpToFirstError() is needed, it is located in the js file. see var $useJsFile.




Tags:

var:  (default is FALSE)
see:  var $useJsFile
access:  public

Type:   bool


[ Top ]

$language =

[line 1073]

the language we use for that form.

example: $language = 'en';




Tags:

access:  public

Type:   string


[ Top ]

$level =

[line 977]

this form class is multi-level capable. think of it like a

multi-step form. (the name 'step' was already reserved, there is already such a var for another thing. don't mix them.) imo a multi-level form can do more than a multi-step form, so the name is even more accurate. multi-level means that we don't have to follow step 1-2-3-4-5, it can be different.

lemme give you an example: a client wants to order something in your shop.

 +----------------------------------------------------------------------+
 | LEVEL | COMMENT     | USER INPUT (SELECT OPTION OR FILL IN)          |
 +----------------------------------------------------------------------+
 | 1) choose products              5x redbull, 2x wodka red :)          |
 |                                        |                             |
 |                       -----------------------------------------------|
 |                                        |                             |
 | 2) how to get it        2a) pickup         2b) send by mail          |
 |                               \                |                     |
 | 3)                             \            fill in address          |
 |                                 \              |                     |
 |                       -----------------------------------------------|
 | 4) payment           4a) credit card     4b) bill           4c) cash |
 |                              |               |                   |   |
 | 5)                    give card info    give bill address        |   |
 |                                         or select that it's      |   |
 |                                         the same as delivery.    |   |
 |                              \               |                   /   |
 |                       -----------------------------------------------|
 | 6) done                      THANK    YOU    FOR    YOUR    ORDER.   |
 |                                                                      |
 +----------------------------------------------------------------------+
 

comments (about the example):

  • if you choose 2a) 'pickup' you will directly go to 4a).
  • if you move back in 4a) you want to go directly to 2a) if you came from there.
  • in level 4c) 'cash' is only meaningfull if the client selected 'pickup' (in step 2a).
  • in level 5) the option to select 'same as delivery' is only available if user selected 2b) 'send by mail'.
note that the vars $viewCount, $startTimestamp, $usedTime and maybe others don't care about the level. they are here once for all levels together.

note also that only containers can be assigned to levels. so put everything of each level into a separate pseudocontainer. that makes our live much easier. we have to deal with girlfriends, that's enough trouble.




Tags:

see:  Bs_Form::isMultiLevel(), Bs_Form::isFirstLevel(), Bs_Form::isLastLevel(), Bs_Form::getNumbersOfLevels(), vars $_prevLevel, $_nextLevel
access:  public

Type:   int


[ Top ]

$mailNice1Bcc =

[line 790]

email bcc address



Tags:

var:  one email address
see:  var $sendMailNice1

Type:   string


[ Top ]

$mailNice1Cc =

[line 783]

email cc address



Tags:

var:  one email address
see:  var $sendMailNice1

Type:   string


[ Top ]

$mailNice1Subject =

[line 797]

email subject



Tags:

see:  var $sendMailNice1

Type:   string


[ Top ]

$mailNice1Template =

[line 804]

email template



Tags:

var:  a blob
see:  var $sendMailNice1

Type:   string


[ Top ]

$mailNice1To =

[line 776]

email to address



Tags:

var:  one email address
see:  var $sendMailNice1

Type:   string


[ Top ]

$mailRawBcc =

[line 756]

email bcc address



Tags:

var:  one email address
see:  var $sendMailRaw

Type:   string


[ Top ]

$mailRawCc =

[line 749]

email cc address



Tags:

var:  one email address
see:  var $sendMailRaw

Type:   string


[ Top ]

$mailRawSubject =

[line 763]

email subject



Tags:

see:  var $sendMailRaw

Type:   string


[ Top ]

$mailRawTo =

[line 742]

email to address



Tags:

var:  one email address
see:  var $sendMailRaw

Type:   string


[ Top ]

$md5Key =

[line 871]

the md5 fingerprint to use to make sure the user did not cheat when submitting the form data.

by default $APP['forms']['md5Key'] is used. and if that is not available or empty, this var will be initialized with the string: "Von der Wiege bis zur Bahre: Formulare" (which is the same as the default value of the $APP['forms']['md5Key'] var).




Tags:

access:  public

Type:   string


[ Top ]

$method =

[line 324]

what submit method to use, as in <form method=$method>.

one of get or post. if not set to 'get' exactly, post is used.



Type:   string


[ Top ]

$mode =

[line 919]

the form mode we're in.

one of 'add', 'edit', 'delete' and 'view'.

if not set then an unknown mode is chosen. you may get strange form output in that case (fields not seen/not editable). an unknown mode may be desired for a search or login form or so.




Tags:

todo:  rethink the available modes.
see:  $this->getMode().

Type:   string


[ Top ]

$mustFieldsVisualMode =  'starLeft'

[line 509]

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




Tags:

var:  mustFieldsVisualMode
access:  public

Type:   string


[ Top ]

$name =

[line 309]

the form name, as in <form name=$name>.

if not set, it's omitted.



Type:   string


[ Top ]

$onEnter =

[line 489]

Browsers act differently when one hits enter in an input field.

Usually the form gets submitted immediatly. This behavior may not be desired. Details can be found here:

http://ppewww.ph.gla.ac.uk/~flavell/www/formquestion.html http://www.cs.tut.fi/~jkorpela/forms/enter.html http://www.google.com :)

possible values: 'ignore' => ignores the hit of enter. does not submit the form. 'tab' => enter acts like the tab key. the cursor/focus jumps into/to the next field. 'submit' => submits the form. 'nothing' => ignores this option. sends nothing to the browser. 'js:doThis' => the name of a javascript function that gets executed, prepended with the string 'js:'. in this example the function that gets executed is doThis(). to keep things simple you cannot give any params that should be passed to this function. but you can wrap a final function in a dummy function, whatever. this feature was added in bs4.3.

this all works by adding javascript events to the code. you need to have the js file included (see var $useJsFile). if you don't set anything, no javascript will be set, nothing will be done.




Tags:

see:  var Bs_FormField->onEnter (fields can overwrite this form property.)

Type:   string


[ Top ]

$persister =  NULL

[line 216]

instance of Bs_ObjPersisterForMySql to persist the settings.


Type:   object


[ Top ]

$persisterID =

[line 223]

reserved var for the persister. don't fuck with this.



Tags:

see:  $this->setPersisterID()

Type:   int


[ Top ]

$persisterVarSettings = array('internalName'         => array('mode'=>'lonely',        'metaType'=>'string',      'index'=>TRUE),'name'=>array('mode'=>'stream'),'action'=>array('mode'=>'stream'),'method'=>array('mode'=>'stream'),'encType'=>array('mode'=>'stream'),'target'=>array('mode'=>'stream'),'styles'=>array('mode'=>'stream'),'advancedStyles'=>array('mode'=>'stream'),'useAccessKeys'=>array('mode'=>'stream'),'accessKeyTags'=>array('mode'=>'stream'),'direction'=>array('mode'=>'stream'),'events'=>array('mode'=>'stream'),'onEnter'=>array('mode'=>'stream'),'disabledMode'=>array('mode'=>'stream'),'mustFieldsVisualMode'=>array('mode'=>'stream'),'useTemplate'=>array('mode'=>'stream'),'templatePath'=>array('mode'=>'stream'),'buttons'=>array('mode'=>'stream'),'useJsFile'=>array('mode'=>'stream'),'jumpToFirstError'=>array('mode'=>'stream'),'saveToDb'=>array('mode'=>'stream'),'dbDsn'=>array('mode'=>'stream','crypt'=>TRUE),'dbName'=>array('mode'=>'stream'),'dbTableName'=>array('mode'=>'stream'),'additionalParams'=>array('mode'=>'stream'),'sendMailRaw'=>array('mode'=>'stream'),'mailRawTo'=>array('mode'=>'stream'),'mailRawCc'=>array('mode'=>'stream'),'mailRawBcc'=>array('mode'=>'stream'),'mailRawSubject'=>array('mode'=>'stream'),'sendMailNice1'=>array('mode'=>'stream'),'mailNice1To'=>array('mode'=>'stream'),'mailNice1Cc'=>array('mode'=>'stream'),'mailNice1Bcc'=>array('mode'=>'stream'),'mailNice1Subject'=>array('mode'=>'stream'),'mailNice1Template'=>array('mode'=>'stream'))

[line 225]


Type:   mixed


[ Top ]

$recordId =

[line 1080]

usually the form is here to edit data from a database. which record? this one.



Tags:

deprecated:  (as all db related things)

Type:   int


[ Top ]

$saveToDb =

[line 669]

save the values of this form to the db or not?



Tags:

see:  var $dbTableName
access:  public

Type:   bool


[ Top ]

$sendMailNice1 =

[line 769]

should we send the submitted data using a template by email to somewhere?


Type:   bool


[ Top ]

$sendMailRaw =

[line 735]

should we send the submitted data in an autogenerated email to somewhere?



Tags:

access:  public

Type:   bool


[ Top ]

$serializeType =  'php'

[line 861]

one of 'wddx' or 'php' (default).

old comment: i have used php (serialize()) before, until unserialize() just did not work on one windows machine in php406. so i had to switch.

new comment 2002/04/08: have switched back to default = 'php' cause wddx is not installed on all systems by default (linux). --andrej




Tags:

access:  public

Type:   string


[ Top ]

$skinName =

[line 580]

the name for the skin that should be loaded.



Tags:

see:  $this->loadSkin(), vars $this->skinPath, $this->elementLayouts
since:  bs4.3
access:  public

Type:   string


[ Top ]

$skinPath =

[line 590]

the path for skin files.

not set means use the default one (core/html/form/skin/).




Tags:

see:  $this->loadSkin(), var $this->skinName etc
since:  bs4.3
access:  public

Type:   string


[ Top ]

$startTimestamp =

[line 1057]

the timestamp when the form was sent to the browser for the first time.

datatype: not sure if that's an int or double for php, but when it comes from a submitted form it's a string.




Tags:

var:  a unix timestamp.
see:  var $usedTime

Type:   mixed


[ Top ]

$state =  'form'

[line 1038]

the form state we're in. default is 'form', one of 'form', 'preview', 'done'.

i don't think this one is in use/coded yet.



Type:   string


[ Top ]

$step =  1

[line 1029]

the form step we're in. default is 1, can be 2.

if the form is displayed for the first time, the step is 1. if the form has been submitted by the user incorrectly (data missing or so) we're in step 2 (no matter how many times the user submits the form).

if it's a multilevel form and for example the form level 3 is displayed for the first time, step is 1.




Tags:

see:  var $postedLevels
access:  public

Type:   int


[ Top ]

$styles =

[line 371]

hash with style information. these keys can be used:

  • string class
  • string id
  • string style
  • (*1) mixed title[] a string or an associative array cause it's language dependant. appears as a tool tip over input fields if they don't have a title specified. (*1) = i have removed this from the feature list. no support until further notice.
check your html documentation for details.




Tags:

access:  public

Type:   array


[ Top ]

$target =

[line 353]

to which target should the form be submitted to? as in <form target=$target> you can name a real target, or use one of the html values '_top', '_parent', '_self', '_blank'.

if not set, it's omitted, which means send to the current target.



Type:   string


[ Top ]

$templatePath =

[line 536]

the absolute path to the template(s). if not given then getAbsolutePath() . '../templates/' will be used which kinda sucks. so you better set that...



Tags:

todo:  i think we should use the $_SERVER['DOCUMENT_ROOT'] or so. at least that var should be used.
see:  var $useTemplate
access:  public

Type:   string


[ Top ]

$useAccessKeys =

[line 414]

If set to true, access keys will be used for the fields even if the field has no special setting for it. then the first letter will be used.



Tags:

see:  var $accessKeyTags

Type:   bool


[ Top ]

$usedTime =

[line 1065]

once the form is 'done' this is set to the used time. (actual time - $startTimestamp)



Tags:

var:  (seconds)
see:  var $startTimestamp

Type:   int


[ Top ]

$useJsFile =  TRUE

[line 1105]

use the externally linked js file? (Bs_FormUtil.lib.js)

it's a problem if it's not linked in the <head></head> for ns 4.x. :/

now because of those browser problems we don't include the js file before the body tag anymore. that js call goes into the $_includeOnce array. some user code may have to be updated. sorry. 2002/04/29 --andrej




Tags:

var:  (default is TRUE (since bs4.3))

Type:   bool


[ Top ]

$user =

[line 1092]

the user/group (based on a session, whatever) that is using the form.

something like 'guest', 'member', 'admin', ...

i think that you prolly want to store a group name in here, rather than a user.




Tags:

see:  var Bs_FormField->accessRights
access:  public

Type:   string


[ Top ]

$useTemplate =

[line 525]

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

For an example have a look at: http://www.blueshoes.org/_bsCore/html/form/examples/withTemplate1/

note: containers can now have their own templates.




Tags:

var:  useTemplate
see:  var $templatePath
access:  public

Type:   bool


[ Top ]

$viewCount =  1

[line 1047]

counts the number of times the form was displayed to the client until it was filled out correctly.

this is not the same as step, and they should not be mixed or put together.



Type:   int


[ Top ]



Class Methods


constructor Bs_Form [line 1150]

Bs_Form Bs_Form( )

Constructor.



[ Top ]

method addError [line 1926]

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

adds an error to this form.

if $fieldName is NULL it is considered a vector element. see $this->errors.




Tags:

see:  var $this->errors
access:  public


Parameters:

string   $errorMsg  
string   $fieldName  
string   $fieldCaption  

[ Top ]

method addHiddenData [line 2430]

void addHiddenData( array $data, [string $varName = ''])

adds the given data as hidden fields to the form.

the given array elements will be treated as if they all were normal hidden form fields! if you use a template, you need to put placeholders for these fields. it all behaves just like if you would add these fields manually.

the given $data may be a boxed array, it will be looped recursively. WARNING: make sure it has no recursive references! this method calls itself recursively. WARNING: make sure the hash keys are not used as form field names already. if that could happen you may want to put your data into a dummy hash, something like $array('hiddenData'=>$yourData). then your hidden fields will look like: <input type="hidden" name="hiddenData[key]" value="foo"> if you need further information check Bs_HtmlUtil->arrayToHiddenFormFields().

note: instead of using this method you may use Bs_HtmlUtil->arrayToHiddenFormFields() yourself. then you can replace the <bs_before_formclose_tag/> tag (see header documentation) with that html string. and then read from the $_POST array. then the fields won't be treated as 'normal form fields', the form itself won't know about their existence.




Tags:

see:  Bs_HtmlUtil->arrayToHiddenFormFields()
since:  bs4.3
access:  public


Parameters:

array   $data   (hash)
string   $varName   (not needed for most cases, used internally.)

[ Top ]

method addIncludeOnce [line 2246]

bool addIncludeOnce( $scriptUrl $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.




Tags:

return:  (TRUE if the script was added, FALSE if it was already there.)
see:  var $_includeOnce, Bs_Form::getIncludeOnce()
access:  public


Parameters:

$scriptUrl   $scriptUrl  

[ Top ]

method addIntoHead [line 2385]

void addIntoHead( mixed $code)

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



Tags:

see:  var $_inHead


[ Top ]

method addOnLoadCode [line 2319]

bool addOnLoadCode( string $code)

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



Tags:

return:  TRUE.
see:  var $_onLoad, Bs_Form::getOnLoadCode()
access:  public


Parameters:

string   $code   (javascript code)

[ Top ]

method createDbTable [line 2725]

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

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



Tags:

return:  TRUE on success
see:  $this->doesDbTableExist(), $this->updateDbTableStructure(), ...
throws:  Bs_Exception
access:  public


Parameters:

string   $dbTableName   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().

[ Top ]

method doesDbTableExist [line 2705]

bool doesDbTableExist( [string $dbTableName = NULL], [bool $useCache = TRUE])

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



Tags:

return:  TRUE if it exists, FALSE if not
see:  $this->getDbTableName(), var $saveToDb, var $dbTableName
throws:  Bs_Exception
access:  public


Parameters:

string   $dbTableName   default is NULL which means get it yourself. you may pass it here if you already have it as optimization.
bool   $useCache   default is TRUE. if the table could have been created lately you better set it to FALSE.

[ Top ]

method doItYourself [line 1186]

mixed doItYourself( [array $postData = NULL])

if the form has been submitted, it will be validated and then be spitted out with errors if there were any. if it has never been submitted before, you'll get a clean form back.

simplifies the work using the form object. you can do all this in your code instead.

this method is useful if you have built your form yourself. don't use it if you've used the objpersister to unpersist a form. (otherwise the postLoadTrigger() would be executed twice.)




Tags:

return:  (bool TRUE after a successful form post, hash from getAll() otherwise.)
access:  public


Parameters:

array   $postData   (default is NULL which means $_POST will be used.)

[ Top ]

method getAll [line 1239]

array getAll( [mixed $includeOnceHow = 'array'], [mixed $onLoadWithCodeTags = FALSE], string $how, bool $withCodeTags)

returns 'everything' of the form output at once, in a hash with these keys:

'form' => the html form code, see $this->getForm() 'include' => the include once code, see $this->getIncludeOnce() 'onLoad' => the onLoad code, see $this->getOnLoadCode() 'head' => the "in head" code, see $this->getInHeadCode() 'errors' => only set if there were any, see $this->getErrorTable() // removed this, not needed. only fucks up dump() of the return. 'formObj' => reference to this form object




Tags:

since:  bs4.3
see:  $this->getForm(), $this->getIncludeOnce(), $this->getOnLoadCode(), $this->getInHeadCode(), $this->getErrorTable(), $this->getInfo()
access:  public


Parameters:

string   $how   (default is 'array', see the param of $this->getIncludeOnce().)
bool   $withCodeTags   (default is FALSE, see the param of $this->getOnLoadCode().)

[ Top ]

method getDbTableName [line 2686]

bool getDbTableName( string $dbTableName, bool $useCache)

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



Tags:

return:  TRUE if it exists, FALSE if not
see:  var $saveToDb, var $dbTableName, $this->doesDbTableExist()
throws:  Bs_Exception


Parameters:

string   $dbTableName   default is NULL which means get it yourself. you may pass it here if you already have it as optimization.
bool   $useCache   default is FALSE. if the table could have been created lately you better don't set it to true.

[ Top ]

method getElement [line 1770]

string getElement( string $elementName, [string $what = 'element'], [array $optionList = null])

returns the element of one of the elements of this form.

caution: moves the pointer of $this->clearingHouse.




Tags:

return:  (text or html)
throws:  empty string '' if no such element.
access:  public


Parameters:

string   $elementName   (the name of the form field or element)
string   $what   one of 'element' (default), 'caption', 'text', 'error', 'help'.
array   $optionList   (used to return just some of the radio options.)

[ Top ]

method getErrorTable [line 1887]

string getErrorTable( [string $title = NULL], [mixed $style = 'default'])

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



Tags:

return:  an html string.
throws:  string an empty string if no errors occured.
access:  public


Parameters:

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

[ Top ]

method getFieldValue [line 1962]

array getFieldValue( string $fieldName, [string $valueType = 'internal'])

returns the field value you want.

does not move the pointer of $this->clearingHouse.




Tags:

return:  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.
access:  public


Parameters:

string   $fieldName  
string   $valueType   one of 'internal' (default), 'default', 'received', 'display'.

[ Top ]

method getForm [line 1260]

string &getForm( [bool $withErrorTable = FALSE])

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



Tags:

return:  (html code)
see:  Bs_Form::getIncludeOnce(), Bs_Form::getOnLoadCode()
access:  public


Parameters:

bool   $withErrorTable   (if the error table should automatically come with it if errors occured. default is FALSE.)

[ Top ]

method getFormFoot [line 1428]

string getFormFoot( )

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



Tags:

return:  some html code.
access:  public


[ Top ]

method getFormHead [line 1390]

string getFormHead( )

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



Tags:

return:  some html code.
access:  public


[ Top ]

method getFormTag [line 1349]

string getFormTag( )

returns the form tag.



Tags:

return:  some html code.
access:  public


[ Top ]

method getIncludeOnce [line 2270]

mixed getIncludeOnce( [string $how = 'array'])

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 echo to your browser (empty string if none).




Tags:

return:  (array or string, see param $how)
see:  var $_includeOnce, Bs_Form::addIncludeOnce(), Bs_Form::includeOnceToHtml()
access:  public


Parameters:

string   $how   (see above)

[ Top ]

method getInfo [line 1334]

array getInfo( )

returns a hash with the following keys:

'viewCount' => integer, see var $viewCount 'startTimestamp' => datetime, see var $startTimestamp 'usedTime' => integer, see var $usedTime 'language' => string, see var $language

use this after a successful form submit.

hint: to create a human-readable gmt date string of the startTimestamp, use something along the lines $formInfo = $form->getInfo(); gmdate('Y-m-d H:i:s', $formInfo['startTimestamp']);

viewCount is done -1 so that if the user submitted the form successfully the 2nd time, the value will be 2 (not 3).




Tags:

return:  (hash, see above)
since:  bs4.3
access:  public


[ Top ]

method getInHeadCode [line 2396]

string getInHeadCode( )

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



Tags:

see:  var $_inHead
access:  public


[ Top ]

method getInterfaceText [line 2954]

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

returns a text string.



Tags:

see:  _loadInterfaceLanguage(), var $_guiLangHash
throws:  empty string '' if a key is not defined or a language can in no way be loaded.
access:  public


Parameters:

string   $key  
string   $lang  

[ Top ]

method getMode [line 1729]

string getMode( )

returns the form mode we're in.



Tags:

return:  one of 'add', 'edit', 'delete', 'view'. the mode that is set, or '' if nothing is set.
see:  var $this->mode
access:  public


[ Top ]

method getNumbersOfLevels [line 1655]

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.




Tags:

see:  Bs_Form::$level
access:  public


[ Top ]

method getOnLoadCode [line 2344]

string getOnLoadCode( [string $withCodeTags = TRUE])

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'> <!-- onload=function() { //javascript code is here } // --> </script>




Tags:

return:  (may be empty)
see:  var $_onLoad, Bs_Form::addOnLoadCode(), Bs_Form::onLoadCodeToHtml()
access:  public


Parameters:

string   $withCodeTags   (default is TRUE, see above.)

[ Top ]

method getSaveToDbArray [line 2869]

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, but take 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's what we made up for it. the the received value doesn't fit 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 never downsize anything. a few notes: char is always converted to varchar. varchar always uses the 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 into the db directly and set an index, so we will never remove one. all we do is add it if the field has become mutBeUnique suddenly. shouldPersist tells us if we should persist the data we got this time. for example in edit mode we don't update some things.




Tags:

return:  (hash, see above)
access:  public


[ Top ]

method getUsedFields [line 1478]

string 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 prevent 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.




Tags:

return:  (html code)


[ Top ]

method getValuesArray [line 2886]

array getValuesArray( [bool $shouldUseOnly = TRUE], [string $valueType = 'valueDisplay'], [bool $withCaption = FALSE], [string $captionLang = null], [bool $printable = FALSE], [array $useLevels = null])

returns the desired values of the submitted fields (that we should use).

does not move the pointer of $this->clearingHouse.




Tags:

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


Parameters:

bool   $shouldUseOnly   default is TRUE. if set to true, only the fields are returned that should be used/persisted on the serverside.
string   $valueType   one of 'valueInternal', 'valueDisplay' (default), 'valueReceived', 'valueDefault'
bool   $withCaption   (default is FALSE. would return a hash holding vectors where element 0 is the caption and element 1 is the value. see param $captionLang.)
string   $captionLang   (default is null. if not given then the lang setting of the form is used. see param $withCaption.)
bool   $printable   (if you want nice human-readable output for values, set this to true. eg checkboxes return 'yes/no' instead of 0/1 values.)
array   $useLevels   (vector filled with integers, null means all steps.)

[ Top ]

method hasJavascript [line 1755]

bool hasJavascript( )

tells whether the client browser has javascript support or not.



Tags:

return:  TRUE if the client has javascript, FALSE if not.
see:  var $hasJavascript
throws:  NULL if we don't know
access:  public


[ Top ]

method includeOnceToHtml [line 2288]

string includeOnceToHtml( array $includeOnce)

if you have the includeOnce data as array and want to spit it out, use this.



Tags:

return:  (like what you get from getIncludeOnce('string'))
since:  bs4.3
access:  public


Parameters:

array   $includeOnce   (output from getIncludeOnce('array'))

[ Top ]

method isFieldFilledIn [line 1945]

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.




Tags:

throws:  NULL if no such field, not a field, or not capable to tell.
access:  public


Parameters:

string   $fieldName  

[ Top ]

method isFirstLevel [line 1675]

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 cause then it's the first level aswell.




Tags:

see:  Bs_Form::$level
access:  public


[ Top ]

method isLastLevel [line 1694]

bool isLastLevel( [mixed $afterSubmit = TRUE], bool $beforeSubmit)

tells if we're in the last level of a multilevel form.

WARNING: it it really matters if we are in the rendering mode to show the last level, or if we have received the inputs of the last level.

note: also returns TRUE if it's not a multilevel form cause then it's the last level anyway.




Tags:

see:  Bs_Form::$level
access:  public


Parameters:

bool   $beforeSubmit   (default is FALSE, see above)

[ Top ]

method isMultiLevel [line 1642]

bool isMultiLevel( )

tells if this form is a multilevel form.



Tags:

see:  $this->level
access:  public


[ Top ]

method isMultipart [line 1716]

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.




Tags:

return:  true if it's a multipart form, false if not.
todo:  finish this code
see:  var $this->encType
access:  public


[ Top ]

method loadSkin [line 1530]

bool loadSkin( string $skinName, [string $basePath = NULL])

loads a predefined skin.



Tags:

see:  var $this->elementLayouts etc
since:  bs4.3
access:  public


Parameters:

string   $skinName  
string   $basePath   (default is NULL which means use the core/html/form/skin/ folder.)

[ Top ]

method onLoadCodeToHtml [line 2364]

string onLoadCodeToHtml( string $onLoadCode)

if you have the onLoadCode data as string but without the needed tags to spit it out, use this.



Tags:

return:  (like what you get from getOnLoadCode(TRUE))
since:  bs4.3
access:  public


Parameters:

string   $onLoadCode   (output from getOnLoadCode(FALSE))

[ Top ]

method persist [line 2478]

bool persist( [bool $withElements = TRUE])

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



Tags:

return:  true on success
throws:  bs_exception on error (db exception)


Overrides Bs_Object::persist() (Persists this object by serializing it and saving it to a file with unique name.)

Parameters:

bool   $withElements   default is TRUE

[ Top ]

method postLoadTrigger [line 2196]

void postLoadTrigger( )

calls the post load triggers of the fields of this form.

caution: moves the pointer of $this->clearingHouse.

multilevel forms: hrm, do we need to load all form elements, even those from levels that come later?




Tags:

access:  public


[ Top ]

method saveToDb [line 2583]

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 structure will be updated. on an insert, $this->recordId will be set.




Tags:

return:  (bool FALSE if nothing had to be saved, bool TRUE on a successful update, int >=1 on a successful insert (=the new record id))
todo:  only works with insert yet, not update.
see:  var $saveToDb, var $dbTableName
throws:  bs_exception if something should have been saved but failed somewhere.
access:  public


[ Top ]

method seedClearingHouse [line 2222]

void seedClearingHouse( [bool $onlyIfNotSet = TRUE])

seeds the var $clearingHouse.



Tags:

todo:  this method is called from somewhere when the elementcontainers are not ready yet. maybe fix this, altough it doesn't break the code, it's just unclean.
see:  var $clearingHouse
access:  public


Parameters:

bool   $onlyIfNotSet   default is TRUE. if set to true it will only be done if $clearingHouse is not set yet.

[ Top ]

method setBsFormData [line 2147]

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.




Tags:

return:  TRUE on success, FALSE if there's a problem with the md5 stuff. (cheater)
todo:  i have to do something with the return if it's false. log, whatever. don't know what's best at the moment, leaving it for later.


Parameters:

array   &$hash   (see class description for details)

[ Top ]

method setLoadedValues [line 2104]

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.




Tags:

see:  $this->setReceivedValues(), $this->setValuesToDefault()
access:  public


Parameters:

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

[ Top ]

method setPersisterID [line 2461]

void setPersisterID( int $persisterID)

set the form id for all elements.

special method for the persister. rtfm.




Tags:

see:  var $persisterID
access:  public


Parameters:

int   $persisterID  

[ Top ]

method setReceivedValues [line 1997]

bool setReceivedValues( mixed &$postData, array &$array)

Sets the received values to the form fields of this form.

also calls setBsFormData() if needed. then calls the postReceiveTrigger().

caution: moves the pointer of $this->clearingHouse.

change: does not modify $step any more. 2002/05/07 --andrej




Tags:

return:  TRUE
see:  $this->setLoadedValues(), $this->setBsFormData(), $this->setValuesToDefault()
throws:  bs_exception
access:  public


Parameters:

array   &$array  

[ Top ]

method setValuesToDefault [line 2129]

void setValuesToDefault( )

sets the fields valueInternal and valueDisplay to the same value as valueDefault is.

caution: moves the pointer of $this->clearingHouse.

the form classes don't use this method at all, but maybe you find it useful. don't recall why i've added this. hrm maybe it was for unpersisted forms.




Tags:

see:  $this->setLoadedValues()
access:  public


[ Top ]

method unPersist [line 2503]

bool unPersist( [string $internalName = NULL], [bool $withElements = TRUE])

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



Tags:

return:  true on success, false on failure
throws:  bs_exception on error (db exception)


Parameters:

string   $internalName   the internally used form name. if not set, $this->persisterID is used. so set it before!
bool   $withElements   default is TRUE

[ Top ]

method updateDbTableStructure [line 2789]

bool updateDbTableStructure( [string $dbTableName = NULL], array &$saveToDbArray, [bool $checkOnly = FALSE])

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



Tags:

return:  TRUE if we have made changes, FALSE if not
todo:  finish this code. it already adds missing fields, but doesn't alter fields that need to be changed.
throws:  bs_exception
access:  public


Parameters:

string   $dbTableName   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().
bool   $checkOnly   default is FALSE. if set to true, no changes will be made.

[ Top ]

method validate [line 1815]

bool validate( )

- manipulates and validates the inputs of all fields that were used and sent.

  • fills $this->errors if needed.
  • changes $this->state, $this->step, $this->level and $this->postedLevels if needed.
  • sets $this->usedTime if needed.
  • does not work on fields that were submitted in a previous level (multilevel forms) and included as hidden fields to pass along.
caution: moves the pointer of $this->clearingHouse.




Tags:

see:  var $this->errors.
access:  public


[ Top ]

method _evalWrap [line 3027]

void _evalWrap( mixed $string, [mixed $security = 'high'], [mixed $suppressErrors = FALSE], [mixed $params = array()])

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 thus can use $this-> things.




Tags:

see:  global evalWrap()


[ Top ]


Documentation generated on Mon, 29 Dec 2003 21:09:12 +0100 by phpDocumentor 1.2.3