apidoc
[ class tree: apidoc ] [ index: apidoc ] [ all elements ]

Class: DB_DataObject_FormBuilder

Source Location: /DB_DataObject_FormBuilder-1.0.2/DB/DataObject/FormBuilder.php

Class Overview


This is the main class for FormBuilder. It does most of the real work.


Author(s):

Variables

Methods


Inherited Variables

Inherited Methods


Class Details

[line 133]
This is the main class for FormBuilder. It does most of the real work.

This class deals with all output agnostic portions of work, although there are still some bits of HTML generation and such to be cleaned out.

You cannot use this class on its own. You must use a driver. The correct way to instantiate a driver is:

  1.  $do = DB_DataObject::factory('someTable');
  2.  $options = array('someOption' +> 'someValue');
  3.  $formBuilder =DB_DataObject_FormBuilder::create($do$options'DriverName');
The easiest form, if you need to set no options via the create() and you wish to use HTML_QuickForm is:
  1.  $do = DB_DataObject::factory('someTable');
  2.  $formBuilder =DB_DataObject_FormBuilder::create($do);

  • See: DB_DataObject_FormBuilder_QuickForm


[ Top ]


Class Variables

$addFormHeader =  true

[line 172]

Add a header to the form - if set to true, the form will have a header element as the first element in the form.
  • See: formHeaderText
  • Access: public

Type:   mixed


[ Top ]

$booleanFields = array()

[line 554]

An array which holds the field names of those fields which are booleans.

They will be displayed as checkboxes.


Type:   mixed


[ Top ]

$clientRules =  false

[line 741]

If set to true, validation rules will also be client side.

Type:   mixed


[ Top ]

$createSubmit =  true

[line 404]

If set to false, no submit button will be created for your forms. Useful when used together with QuickForm_Controller when you already have submit buttons for next/previous page. By default, a button is being generated.

Type:   mixed


[ Top ]

$crossLinkExtraFields = array()

[line 658]

You can also specify extra fields to edit in the a crossLink table with

this option. For example, if the user_group table mentioned above had another field called 'role' which was a text field, you could specify it like this in the user_group DataObject class:

  1.  <?php
  2.  class DataObject_User_group extends DB_DataObject {
  3.    //normal stuff here
  4.  
  5.    var $fb_crossLinkExtraFields = array('role');
  6.  }
  7.  ?>

This would cause a text box to show up next to each checkbox in the user_group section of the form for the field 'role'.

You can specify as many fields as you want in the 'extraFields' array.

Note: If you specify a linked field in 'extraFields' you'll get a select box just like when you do a normal link field in a FormBuilder form. :-)


Type:   mixed


[ Top ]

$crossLinks = array()

[line 633]

The crossLinks array holds data pertaining to many-many links. If you have a table which links two tables together, you can use this to automatically create a set of checkboxes or a multi-select on your form.

The simplest way of using this is:

  1.  <?php
  2.  class DataObject_SomeTable extends DB_DataObject {
  3.  //...
  4.    var $fb_crossLinks = array(array('table' => 'crossLinkTable'));
  5.  }
  6.  ?>
Where crossLinkTable is the name of the linking table. You can have as many cross-link entries as you want. Try it with just the table ewntry first. If it doesn't work, you can specify the fields to use as well.
  1.  'fromField' => 'linkFieldToCurrentTable' //This is the field which links to the current (from) table
  2.  'toField' => 'linkFieldToLinkedTable' //This is the field which links to the "other" (to) table
To get a multi-select add a 'type' key which it set to 'select'.
  1.  <?php
  2.  class DataObject_SomeTable extends DB_DataObject {
  3.      //...
  4.      var $fb_crossLinks = array(array('table' => 'crossLinkTable''type' => 'select'));
  5.  }
  6.  ?>
An example: I have a user table and a group table, each with a primary key called id. There is a table called user_group which has fields user_id and group_id which are set up as links to user and group. Here's the configuration array that could go in both the user DO and the group DO:
  1.  <?php
  2.  $fb_crossLinks = array(array('table' => 'user_group'));
  3.  ?>
Here is the full configuration for the user DO:
  1.  <?php
  2.  $fb_crossLinks = array(array('table' => 'user_group',
  3.                               'fromField' => 'user_id',
  4.                               'toField' => 'group_id'));
  5.  ?>
And the full configuration for the group DO:
  1.  <?php
  2.  $fb_crossLinks = array(array('table' => 'user_group',
  3.                               'fromField' => 'group_id',
  4.                               'toField' => 'user_id'));
  5.  ?>

crossLinks can also be automatically collapsed only to the selected records by setting the 'collapse' key to true. The collapsed options can be viewed again by clicking the "Show All" link.

You can also specify the seperator between the elements with crossLinkSeperator.


Type:   mixed


[ Top ]

$crossLinkSeparator =  '<br/>'

[line 559]

The text to put between crosslink elements.

Type:   mixed


[ Top ]

$dateElementFormat =  'd-m-Y'

[line 240]

A format string that represents the display settings for QuickForm date elements.

Example: "d-m-Y". See QuickForm documentation for details on format strings. Legal letters to use in the format string that work with FormBuilder are: d,m,M,y,Y


Type:   mixed


[ Top ]

$dateFieldLanguage =  'en'

[line 218]

The language used in date fields. See documentation of HTML_Quickform's date element for more information.
  • See: HTML_QuickForm_date

Type:   mixed


[ Top ]

$dateFields = array()

[line 506]

A simple array of field names indicating which of the fields in a particular table/class are actually to be treated date fields. This is an unfortunate workaround that is neccessary because the DataObject generator script does not make a difference between any other datatypes than string and integer.

When it does, this can be dropped.


Type:   mixed


[ Top ]

$dateFromDatabaseCallback = array('DB_DataObject_FormBuilder','_date2array')

[line 225]

Callback method to convert a date from the format it is stored in the database to the format used by the QuickForm element that handles date values. Must have a format usable with call_user_func().

Type:   mixed


[ Top ]

$dateOptionsCallback =  null

[line 268]

Callback to get extra options for date elements. Defaults to 'dateOptions' in the DO.

Type:   mixed


[ Top ]

$dateTimeElementFormat =  'd-m-Y H:i:s'

[line 256]

A format string that represents the display settings for QuickForm datetime elements.

Example: "d-m-Y H:i:s". See QuickForm documentation for details on format strings. Legal letters to use in the format string that work with FormBuilder are: d,m,M,y,Y,H,i,s


Type:   mixed


[ Top ]

$dateTimeOptionsCallback =  null

[line 278]

Callback to get extra options for datetime elements. Defaults to 'dateTimeOptions' in the DO.

Type:   mixed


[ Top ]

$dateToDatabaseCallback = array('DB_DataObject_FormBuilder','_array2date')

[line 232]

Callback method to convert a date from the format used by the QuickForm element that handles date values to the format the database can store it in.

Must have a format usable with call_user_func().


Type:   mixed


[ Top ]

$dbDateFormat =  1

[line 263]

This is for the future support of string date formats other than ISO, but currently, that's the only supported one. Set to 1 for ISO, other values may be available later on.

Type:   mixed


[ Top ]

$elementNamePostfix =  ''

[line 775]

A postfix to put after element names in the form
  • See: DB_DataObject_FormBuilder::elementNamePrefix

Type:   mixed


[ Top ]

$elementNamePrefix =  ''

[line 769]

A string to prepend to element names. Together with elementNamePostfix, this option allows you to

alter the form element names that FormBuilder uses to create and process elements. The main use for this is to combine multiple forms into one. For example, if you wanted to use multiple FB forms for the same table within one actual HTML form you could do something like this: <?php $do = DB_DataObject::factory('table'); $fb = DB_DataObject_FormBuilder::create($do); $fb->elementNamePrefix = 'formOne'; $form = $fb->getForm();

$do2 = DB_DataObject::factory('table'); $fb2 = DB_DataObject_FormBuilder::create($do2); $fb->elementNamePrefix = 'formTwo'; $fb->useForm($form); $form = $fb->getForm();

//normal processing here ?>

If you assume that "table: has one field, "name", then the resultant form will have two elements: "formOnename" and "formTwoname".

Please note: You *cannot* use '[' or ']' anywhere in the prefix or postfix. Doing so will cause FormBuilder to not be able to process the form.


Type:   mixed


[ Top ]

$elementTypeAttributes = array()

[line 840]

Array of attributes for each element type. See the keys of elementTypeMap for the allowed element types.

The key is the element type. The value can be a valid attribute string or an associative array of attributes.


Type:   mixed


[ Top ]

$elementTypeMap = array('shorttext' => 'text',
                                'longtext'  => 'textarea',
                                'date'      => 'date',
                                'time'      => 'date',
                                'datetime'  => 'date',
                                'integer'   => 'text',
                                'float'     => 'text',
                                'select'    => 'select',
                                'multiselect'    => 'select',
                                'popupSelect' => 'popupSelect',
                                'elementGrid' => 'elementGrid')

[line 821]

Array to determine what QuickForm element types are being used for which

general field types. If you configure FormBuilder using arrays, the format is: array('nameOfFieldType' => 'QuickForm_Element_name', ...); If configured via .ini file, the format looks like this: elementTypeMap = shorttext:text,date:date,...

Allowed field types:

  • shorttext
  • longtext</
  • date
  • integer
  • float


Type:   mixed


[ Top ]

$enumFields = array()

[line 534]

A simple array of fields names which should be treated as ENUMs. A select box will be created with the enum options. If you add this field to the linkElementTypes array and give it a 'radio' type, you will get radio buttons instead.

The default handler for enums is only tested in mysql. If you are using a different DB backend, use enumOptionsCallback or enumOptions.


Type:   mixed


[ Top ]

$enumOptions = array()

[line 548]

An array which holds enum options for specific fields. Each key should be a field in the current table and each value holds a an array of strings which are the possible values for the enum. This will only be used if the field is listed in enumFields.

Type:   mixed


[ Top ]

$enumOptionsCallback = array()

[line 540]

A valid callback which will return the options in a simple array of strings for an enum field given the table and field names.

Type:   mixed


[ Top ]

$excludeFromAutoRules = array()

[line 431]

Array of fields for which no auto-rules may be generated.

If set to string "__ALL__" or the array includes "__ALL__", no rules are automatically generated for any field.


Type:   mixed


[ Top ]

$fieldAttributes = array()

[line 848]

Array of attributes for each specific field.

The key is the field name. The value can be a valid attribute string or an associative array of attributes.


Type:   mixed


[ Top ]

$fieldLabels = array()

[line 411]

Array of field labels. The key of the element is the field name. Use this if you want to keep the auto-generated elements, but still define your own labels for them.

Type:   mixed


[ Top ]

$fieldsRequired = array()

[line 437]

Array of fields which will be set required. This is in addition to all NOT NULL fields which are automatically set required.

Type:   mixed


[ Top ]

$fieldsToRender = array()

[line 418]

Array of fields to render elements for. If a field is not given, it will not be rendered. If empty, all fields will be rendered (except, normally, the primary key).

Type:   mixed


[ Top ]

$formHeaderText =  null

[line 181]

Text for the form header. If not set, the name of the database table this form represents will be used.
  • See: addFormHeader
  • Access: public

Type:   mixed


[ Top ]

$hidePrimaryKey =  true

[line 488]

By default, hidden fields are generated for the primary key of a DataObject. This behaviour can be deactivated by setting this option to false.

Type:   mixed


[ Top ]

$linkDisplayFields = array()

[line 334]

These fields will be used when displaying a link record. The fields listed will be seperated by ", ". If you specify a link field as a display field and linkDisplayLevel is not 0, the link will be followed and the display fields of the record linked to displayed within parenthesis.

For example, say we have these tables:

[person]

name = 130 gender_id = 129

[gender] id = 129 name = 130

this link:

[person] gender_id = gender:id

and this data: Person: name: "Justin Patrin" gender_id: 1 Gender: id: 1 name: "male"

If person's display fields are: <?php class DataObject_Person extends DB_DataObject { //... var $fb_linkDisplayFields = array('name', 'gender_id'); } ?>

and gender's display fields are: <?php class DataObject_Gender extends DB_DataObject { //... var $fb_linkDisplayFields = array('name'); } ?>

and we set linkDisplayLevel to 0, the person record will be displayed as: "Justin Patrin, 1"

If we set linkDisplayLevel to 1, the person record will be displayed as: "Justin Patrin, (male)"


Type:   mixed


[ Top ]

$linkDisplayLevel =  0

[line 570]

If this is set to 1 or above, links will be followed in the display fields and the display fields of the record linked to will be used for display.

If this is set to 2, links will be followed in the linked record as well. This can be set to any number of links you wish but could easily slow down your application if set to more than 1 or 2 (but only if you have links in your display fields that go that far ;-)). For a more in-depth example, see the docs for linkDisplayFields.


Type:   mixed


[ Top ]

$linkElementTypes = array()

[line 523]

Array to configure the type of the link elements. By default, a select box will be used. The key is the name of the link element. The value is 'radio' or 'select'. If you choose 'radio', radio buttons will be made instead of a select box.

Type:   mixed


[ Top ]

$linkNewValue = array()

[line 373]

If set to true, all links which are renderered as select boxes (see linkElementTypes)

will have a "--New Value--" option on the bottom which displays a form for the linked to table for creating a new record. Upon submit, the sub-form will be checked for validity as normal and, if valid, will be used to enter a new record in the linked-to table which this record will now link to.

If set to false, all link select boxes will only have entered options (as normal) If set to true, all link select boxes will have a New Value entry You may also set this to be an array with the names of the link fields to create New Value entries for.


Type:   mixed


[ Top ]

$linkNewValueText =  '--New Value--'

[line 392]

The text which will show up in the link new value select entry. Make sure that this is unique!

Type:   mixed


[ Top ]

$linkOrderFields = array()

[line 359]

The fields to be used for sorting the options of an auto-generated link

element. You can specify ASC and DESC in these options as well: <?php class DataObject_SomeTable extends DB_DataObject { //... var $fb_linkOrderFields = array('field1', 'field2 DESC'); } ?>

You may also want to escape the field names if they are reserved words in the database you're using: <?php class DataObject_SomeTable extends DB_DataObject { //... function preGenerateForm() { $db = $this->getDatabaseConnection(); $this->fb_linkOrderFields = array($db->quoteIdentifier('config'), $db->quoteIdentifier('select').' DESC'); } } ?>


Type:   mixed


[ Top ]

$postGenerateFormCallback =  null

[line 790]

The callback to use for postGenerateForm calls. Defaults to postGenerateForm() in the DataObject.

Type:   mixed


[ Top ]

$postProcessFormCallback =  null

[line 800]

The callback to use for postProcessForm calls. Defaults to postProcessForm() in the DataObject.

Type:   mixed


[ Top ]

$preDefElements = array()

[line 464]

Array of user-defined QuickForm elements that will be used for the field

matching the array key. If no match is found, the element for that field will be auto-generated. Make your element objects either in the preGenerateForm() method or in the getForm() method. Use HTML_QuickForm::createElement() to do this.

If you wish to put in a group of elements in place of a single element, you can put an array in preDefElements instead of a single element. The name of the group will be the name of the replaced element.


Type:   mixed


[ Top ]

$preDefGroups = array()

[line 443]

Array of groups to put certain elements in. The key is an element name, the value is the group to put the element in.

Type:   mixed


[ Top ]

$preDefOrder = array()

[line 451]

Indexed array of element names. If defined, this will determine the order in which the form elements are being created. This is useful if you're using QuickForm's default renderer or dynamic templates and the order of the fields in the database doesn't match your needs.

Type:   mixed


[ Top ]

$preGenerateFormCallback =  null

[line 785]

The callback to use for preGenerateForm calls. Defaults to preGenerateForm() in the DataObject.

Type:   mixed


[ Top ]

$prepareLinkedDataObjectCallback =  null

[line 805]

The callback to use for prepareLinkedDataObject calls. Defaults to prepareLinkedDataObject() in the DataObject.

Type:   mixed


[ Top ]

$preProcessFormCallback =  null

[line 795]

The callback to use for preProcessForm calls. Defaults to preProcessForm() in the DataObject.

Type:   mixed


[ Top ]

$radioAddEmptyLabel =  ''

[line 481]

A string to put in the "empty option" added to radio fields

Type:   mixed


[ Top ]

$requiredRuleMessage =  'The field %s is required.'

[line 199]

Text that is displayed as an error message if a required field is left empty. Use %s to insert the field name.
  • See: ruleViolationMessage
  • Access: public

Type:   mixed


[ Top ]

$reverseLinkNewValue = array()

[line 387]

If set to true, all reverseLinks will have a SubForm to create a new linked record.

Upon submit the sub-form will be checked for validity as normal and, if valid, will create a new record in the reverseLink table.

If set to false all reverseLinks will only display existing reverseLink records.

You may also set this to be an array with the names of the reverseLink elements to create new linked record sub-forms for. You can simply use '__reverseLink_table_field'=>true, or set to an integer to display a number of sub-forms.


Type:   mixed


[ Top ]

$reverseLinks = array()

[line 736]

Holds reverseLink configuration.

A reverseLink is a table which links back to the current table. For example, let say we have a "gender" table which has Male and Female in it and a "person" table which has the fields "name", which holds the person's name and "genre_id" which links to the genre. If you set up a form for the gender table, the person table can be a reverseLink. The setup in the gender table would look like this:

  1.  <?php
  2.  class DataObject_Gender extends DB_DataObject {
  3.  //normal stuff here
  4.  
  5.    var $fb_reverseLinks = array(array('table' => 'person'));
  6.  }
  7.  ?>
Now a list of people will be shown in the gender form with a checkbox next to it which is checked if the record currently links to the one you're editing. In addition, some special text will be added to the end of the label for the person record if it's linked to another gender.

Say we have a person record with the name "Justin Patrin" which is linked to the gender "Male". If you view the form for the gender "Male", the checkbox next to "Justin Patrin" will be checked. If you choose the "Female" gender the checkbox will be unchecked and it will say: Justin Patrin - currently linked to - Male

If the link field is set as NOT NULL then FormBuilder will not process an unchecked checkbox unless you specify a default value to set the link to. If null is allowed, the link will be set to NULL. To specify a default value:

  1.  <?php
  2.  class DataObject_Gender extends DB_DataObject {
  3.  //normal stuff here
  4.  
  5.    var $fb_reverseLinks = array(array('table' => 'person',
  6.                                       'defaultLinkValue' => 5));
  7.  }
  8.  ?>
Now if a checkbox is unchecked the link field will be set to 5...whatever that means. Be careful here as you need to make sure you enter the correct value here (probably the value of the primary key of the record you want to link to by default).

You may also set the text which is displayed between the record and the currently linked to record.

  1.  <?php
  2.  class DataObject_Gender extends DB_DataObject {
  3.      //normal stuff here
  4.  
  5.    var $fb_reverseLinks = array(array('table' => 'person',
  6.                                       'linkText' => ' is currently listed as a '));
  7.  }
  8.  ?>
If you select "Female" the Justin Patrin entry would now say: Justin Patrin__ is currently listed as a Male__


Type:   mixed


[ Top ]

$ruleViolationMessage =  '%s: The value you have entered is not valid.'

[line 190]

Text that is displayed as an error message if a validation rule is violated by the user's input. Use %s to insert the field name.
  • See: requiredRuleMessage
  • Access: public

Type:   mixed


[ Top ]

$selectAddEmpty = array()

[line 471]

An array of the link or date fields which should have an empty option added to the select box. This is only a valid option for fields which link to another table or date fields.

Type:   mixed


[ Top ]

$selectAddEmptyLabel =  ''

[line 476]

A string to put in the "empty option" added to select fields

Type:   mixed


[ Top ]

$submitText =  'Submit'

[line 397]

The caption of the submit button, if created.

Type:   mixed


[ Top ]

$textFields = array()

[line 497]

A simple array of field names indicating which of the fields in a particular table/class are actually to be treated as textareas. This is an unfortunate workaround that is neccessary because the DataObject generator script does not make a difference between any other datatypes than string and integer.

When it does, this can be dropped.


Type:   mixed


[ Top ]

$timeElementFormat =  'H:i:s'

[line 248]

A format string that represents the display settings for QuickForm time elements.

Example: "H:i:s". See QuickForm documentation for details on format strings. Legal letters to use in the format string that work with FormBuilder are: H,i,s


Type:   mixed


[ Top ]

$timeFields = array()

[line 515]

A simple array of field names indicating which of the fields in a particular table/class are actually to be treated time fields. This is an unfortunate workaround that is neccessary because the DataObject generator script does not make a difference between any other datatypes than string and integer.

When it does, this can be dropped.


Type:   mixed


[ Top ]

$timeOptionsCallback =  null

[line 273]

Callback to get extra options for time elements. Defaults to 'timeOptions' in the DO.

Type:   mixed


[ Top ]

$tripleLinks = array()

[line 672]

Holds triple link data.

The tripleLinks array can be used to display checkboxes for "triple-links". A triple link is set up with a table which links to three different tables. These will show up as a table of checkboxes The initial setting (table) is the same as for crossLinks. The field configuration keys (if you need them) are:

  1.     'fromField'
  2.     'toField1'
  3.     'toField2'


Type:   mixed


[ Top ]

$useAccessors =  false

[line 868]

Set to true to use accessor methods (getters) for accessing field values, if they exist.

If this is set to true and a method exists of the name getFieldName where FieldName is the name of the field then it will be called to get the value of the field.

Note: The following field names will not work with getters due to function collisions in DB_DataObject. Do not use fields with these names in conjunction with useAccessors. * Link * Links * LinkArray * DatabaseConnection * DatabaseResult

Note: Accessors may not be used to get link field values. Link field values are internal to a database and are assumed not to need accessors.


Type:   mixed


[ Top ]

$useCallTimePassByReference =  false

[line 780]

Whether or not to use call-time-pass-by-reference when calling DataObject callbacks

Type:   mixed


[ Top ]

$useMutators =  false

[line 883]

Set to true to use mutator methods (setters) for setting field values, if they exist.

If this is set to true and a method exists of the name setFieldName where FieldName is the name of the field then it will be called to set the value of the field.

Note: Do not use a field named From if you use this option. DB_DataObject has a default method setFrom which will cause problems.

Note: Mutators may not be used to set link fields. Link field values are internal to a database and are assumed not to need mutators.


Type:   mixed


[ Top ]

$userEditableFields = array()

[line 424]

Array of fields which the user can edit. If a field is rendered but not specified in this array, it will be frozen. Ignored if not given.

Type:   mixed


[ Top ]

$validateOnProcess =  false

[line 210]

If set to TRUE, the current DataObject's validate method is being called before the form data is processed. If errors occur, no insert/update operation will be made on the database. Use getValidationErrors() to retrieve the reasons for a failure.

Defaults to FALSE.

  • Access: public

Type:   mixed


[ Top ]

$_form =  false

[line 143]

If you want to use the generator on an existing form object, pass it to useForm().
  • See: DB_DataObject_Formbuilder()
  • Access: protected

Type:   mixed


[ Top ]

$_queryType =  DB_DATAOBJECT_FORMBUILDER_QUERY_AUTODETECT

[line 157]

Used to determine which action to perform with the submitted data in processForm()
  • Access: protected

Type:   mixed


[ Top ]

$_validationErrors =  false

[line 150]

Contains the last validation errors, if validation checking is enabled.
  • Access: protected

Type:   mixed


[ Top ]



Method Detail

DB_DataObject_FormBuilder (Constructor)   [line 965]

DB_DataObject_FormBuilder DB_DataObject_FormBuilder( &$do, [array $options = false], object $do)

DB_DataObject_FormBuilder::DB_DataObject_FormBuilder()

The class constructor.

  • Access: public

Parameters:

object   $do   —  The DB_DataObject-derived object for which a form shall be built
array   $options   —  An optional associative array of options.
   &$do   — 

[ Top ]

create   [line 908]

object DB_DataObject_FormBuilder &create( &$do, [array $options = false], [string $driver = 'QuickForm'], [ $mainClass = 'DB_DataObject_FormBuilder'], object $do)

DB_DataObject_FormBuilder::create()

Factory method. As this is meant as an abstract class, it is the only supported method to make a new object instance. Pass the DataObject-derived class you want to build a form from as the first parameter. Use the second to pass additional options.

Options can be any option for FormBuilder (see properties which do not start with _)

The third parameter is the name of a driver class. A driver class will take care of the actual form generation. This way it's possible to have FormBuilder build different forms for different types of output media from the same set of DataObjects.

Currently available driver classes:

  • QuickForm (stable)
  • XUL (experimental!)

  • Return: or PEAR_Error object
  • Access: public

Parameters:

object   $do   —  The DB_DataObject-derived object for which a form shall be built
array   $options   —  An optional associative array of options.
string   $driver   —  Optional: Name of the driver class for constructing the form object. Default: QuickForm.
   &$do   — 
   $mainClass   — 

[ Top ]

debug   [line 3236]

void debug( string $message)

DB_DataObject_FormBuilder::debug()

Outputs a debug message, if the debug setting in the DataObject.ini file is set to 1 or higher.

  • See: DB_DataObject::debugLevel()
  • Access: public

Parameters:

string   $message   —  The message to printed to the browser

[ Top ]

forceQueryType   [line 3210]

boolean forceQueryType( [integer $queryType = DB_DATAOBJECT_FORMBUILDER_QUERY_AUTODETECT])

DB_DataObject_FormBuilder::forceQueryType()

You can force the behaviour of the processForm() method by passing one of the following constants to this method:

  • DB_DATAOBJECT_FORMBUILDER_QUERY_FORCEINSERT: The submitted data will always be INSERTed into the database
  • DB_DATAOBJECT_FORMBUILDER_QUERY_FORCEUPDATE: The submitted data will always be used to perform an UPDATE on the database
  • DB_DATAOBJECT_FORMBUILDER_QUERY_FORCENOACTION: The submitted data will overwrite the properties of the DataObject, but no action will be performed on the database.
  • DB_DATAOBJECT_FORMBUILDER_QUERY_AUTODETECT: The processForm() method will try to detect for itself if an INSERT or UPDATE query has to be performed. This will not work if no primary key field can be detected for the current DataObject. In this case, no action will be performed. This is the default behaviour.

  • Access: public

Parameters:

integer   $queryType   —  The type of the query to be performed. Please use the preset constants for setting this.

[ Top ]

getDataObjectString   [line 1984]

string getDataObjectString( DB_DataObject &$do, [mixed $displayFields = false], [int $linkDisplayLevel = null], [int $level = 1])

DB_DataObject_FormBuilder::getDataObjectString()

Returns a string which identitfies this dataobject. If multiple display fields are given, will display them all seperated by ", ". If a display field is a foreign key (link) the display value for the record it points to will be used as long as the linkDisplayLevel has not been reached. Its display value will be surrounded by parenthesis as it may have multiple display fields of its own.

May be called statically.

Will use display field configurations from these locations, in this order: 1) $displayFields parameter 2) the fb_linkDisplayFields member variable of the dataobject 3) the linkDisplayFields member variable of this class (if not called statically) 4) all fields returned by the DO's table() function

  • Return: select display value for this field
  • Access: public

Parameters:

DB_DataObject   &$do   —  the dataobject to get the display value for, must be populated
mixed   $displayFields   —  field to use to display, may be an array with field names or a single field. Will only be used for this DO, not linked DOs. If you wish to set the display fields all DOs the same, set the option in the FormBuilder class instance.
int   $linkDisplayLevel   —  the maximum link display level. If null, $this->linkDisplayLebel will be used if it exists, otherwise 3 will be used. {@see DB_DataObject_FormBuilder::linkDisplayLevel}
int   $level   —  the current recursion level. For internal use only.

[ Top ]

getFieldLabel   [line 1933]

string getFieldLabel( $fieldName $fieldName)

DB_DataObject_FormBuilder::getFieldLabel()

Returns the label for the given field name. If no label is specified, the fieldname will be returned with ucfirst() applied.

  • Access: public

Parameters:

$fieldName   $fieldName   —  string The field name

[ Top ]

getFieldName   [line 1787]

string getFieldName( string $fieldName)

Gets the name of the field to use in the form.
  • Return: field name to use with form

Parameters:

string   $fieldName   —  field's name

[ Top ]

getForm   [line 2404]

object &getForm( [string $action = false], [string $target = '_self'], [string $formName = false], [string $method = 'post'])

DB_DataObject_FormBuilder::getForm()

Returns a HTML form that was automagically created by _generateForm(). You need to use the get() method before calling this one in order to prefill the form with the retrieved data.

If you have a method named "preGenerateForm()" in your DataObject-derived class, it will be called before _generateForm(). This way, you can create your own elements there and add them to the "fb_preDefElements" property, so they will not be auto-generated.

If you have your own "getForm()" method in your class, it will be called instead of _generateForm(). This enables you to have some classes that make their own forms completely from scratch, without any auto-generation. Use this for highly complex forms. Your getForm() method needs to return the complete HTML_QuickForm object by reference.

If you have a method named "postGenerateForm()" in your DataObject-derived class, it will be called after _generateForm(). This allows you to remove some elements that have been auto-generated from table fields but that you don't want in the form.

Many ways lead to rome.

  • Access: public

Parameters:

string   $action   —  The form action. Optional. If set to false (default), $_SERVER['PHP_SELF'] is used.
string   $target   —  The window target of the form. Optional. Defaults to '_self'.
string   $formName   —  The name of the form, will be used in "id" and "name" attributes. If set to false (default), the class name is used, prefixed with "frm"
string   $method   —  The submit method. Defaults to 'post'.

[ Top ]

getSelectOptions   [line 2054]

array getSelectOptions( string $field, [string $displayFields = false], [bool $selectAddEmpty = false], [string $emptyLabel = false])

DB_DataObject_FormBuilder::getSelectOptions()

Returns an array of options for use with the HTML_QuickForm "select" element. It will try to fetch all related objects (if any) for the given field name and build the array. For the display name of the option, it will try to use the settings in the database.formBuilder.ini file. If those are not found, the linked object's property "fb_linkDisplayFields". If that one is not present, it will try to use the global configuration setting "linkDisplayFields". Can also be called with a second parameter containing the name of the display field - this will override all other settings. Same goes for "linkOrderFields", which determines the field name used for sorting the option elements. If neither a config setting nor a class property of that name is set, the display field name will be used.

  • Return: strings representing all of the records in the table $field links to.
  • Access: public

Parameters:

string   $field   —  The field to fetch the links from. You should make sure the field actually *has* links before calling this function (see: DB_DataObject::links())
string   $displayFields   —  (Optional) The name of the field used for the display text of the options
bool   $selectAddEmpty   —  (Optional) If true, an empty option will be added to the list of options If false, the selectAddEmpty member var will be checked
string   $emptyLabel   —  (Optional) Label to use for empty options (defaults to $this->selectAddEmptyLabel)

[ Top ]

getValidationErrors   [line 2637]

mixed getValidationErrors( )

DB_DataObject_FormBuilder::getValidationErrors()

Returns errors from data validation. If errors have occured, this will be an array with the fields that have errors, otherwise a boolean.

  • See: DB_DataObject::validate()
  • Access: public

[ Top ]

isCallableAndExists   [line 3322]

void isCallableAndExists( $callback)


Parameters:

   $callback   — 

[ Top ]

populateOptions   [line 2161]

void populateOptions( )

DB_DataObject_FormBuilder::populateOptions()

Populates public member vars with fb_ equivalents in the DataObject.


[ Top ]

prettyName   [line 1952]

string prettyName( $name $name)

DB_DataObject_FormBuilder::prettyName()

"Pretties" a name. 'fieldName' => 'Field Name' 'TABLE_NAME' => 'Table Name'

  • Access: public

Parameters:

$name   $name   —  string The name to "pretty"

[ Top ]

processForm   [line 2695]

mixed processForm( array $values)

DB_DataObject_FormBuilder::processForm()

This will take the submitted form data and put it back into the object's properties. If the primary key is not set or NULL, it will be assumed that you wish to insert a new element into the database, so DataObject's insert() method is invoked. Otherwise, an update() will be performed. <b>Careful:</b> If you're using natural keys or cross-referencing tables where you don't have one dedicated primary key, this will always assume that you want to do an update! As there won't be a matching entry in the table, no action will be performed at all - the reason for this behaviour can be very hard to detect. Thus, if you have such a situation in one of your tables, simply override this method so that instead of the key check it will try to do a SELECT on the table using the current settings. If a match is found, do an update. If not, do an insert. This method is perfect for use with QuickForm's process method. Example:

  1.  if ($form->validate()) {
  2.      $form->freeze();
  3.      $form->process(array(&$formGenerator,'processForm')false);
  4.  }

If you wish to enforce a special type of query, use the forceQueryType() method.

Always remember to pass your objects by reference - otherwise, if the operation was an insert, the primary key won't get updated with the new database ID because processForm() was using a local copy of the object!

If a method named "preProcessForm()" exists in your derived class, it will be called before processForm() starts doing its magic. The data that has been submitted by the form will be passed to that method as a parameter. Same goes for a method named "postProcessForm()", with the only difference - you might have guessed this by now - that it's called after the insert/update operations have been done. Use this for filtering data, notifying users of changes etc.pp. ...

  • Return: TRUE if database operations were performed, FALSE if not, PEAR_Error on error
  • Access: public

Parameters:

array   $values   —  The values of the submitted form

[ Top ]

useForm   [line 1915]

boolean useForm( $form &$form, [$append $append = false])

DB_DataObject_FormBuilder::useForm()

Sometimes, it might come in handy not just to create a new QuickForm object, but to work with an existing one. Using FormBuilder together with HTML_QuickForm_Controller or HTML_QuickForm_Page is such an example ;-) If you do not call this method before the form is generated, a new QuickForm object will be created (default behaviour).

  • Return: Returns false if the passed object was not a HTML_QuickForm object or a QuickForm object was already created
  • Access: public

Parameters:

$form   &$form   —  object A HTML_QuickForm object (or extended from that)
$append   $append   —  boolean If TRUE, the form will be appended to the one generated by FormBuilder. If false, FormBuilder will just add its own elements to this form.

[ Top ]

validateData   [line 2621]

mixed validateData( )

DB_DataObject_FormBuilder::validateData()

Makes a call to the current DataObject's validate() method and returns the result.

  • See: DB_DataObject::validate()
  • Access: public

[ Top ]

_array2date   [line 2516]

mixed _array2date( $dateInput, [boolean $timestamp = false], array $date)

DB_DataObject_FormBuilder::_array2date()

Takes a date array as used by the QuickForm date element and turns it back into a string representation suitable for use with a database date field (format 'YYYY-MM-DD'). If second parameter is true, it will return a unix timestamp instead. //FRANK: Not at this point it wont

Beware: For the date conversion to work, you must at least use the letters "d", "m" and "Y" in your format string (see "dateElementFormat" option). If you want to enter a time as well, you will have to use "H", "i" and "s" as well. Other letters will not work! Exception: You can also use "M" instead of "m" if you want plain text month names.

  • Access: protected

Parameters:

array   $date   —  An array representation of a date, as user in HTML_QuickForm's date element
boolean   $timestamp   —  Optional. If true, return a timestamp instead of a string. Defaults to false.
   $dateInput   — 

[ Top ]

_date2array   [line 2442]

array _date2array( mixed $date)

DB_DataObject_FormBuilder::_date2array()

Takes a string representing a date or a unix timestamp and turns it into an array suitable for use with the QuickForm data element. When using a string, make sure the format can be handled by the PEAR::Date constructor!

Beware: For the date conversion to work, you must at least use the letters "d", "m" and "Y" in your format string (see "dateElementFormat" option). If you want to enter a time as well, you will have to use "H", "i" and "s" as well. Other letters will not work! Exception: You can also use "M" instead of "m" if you want plain text month names.

  • Access: protected

Parameters:

mixed   $date   —  A unix timestamp or the string representation of a date, compatible to strtotime()

[ Top ]

_explodeArrString   [line 1808]

array _explodeArrString( string $str)

DB_DataObject_FormBuilder::_explodeArrString()

Internal method, will convert string representations of arrays as used in .ini files to real arrays. String format example: key1:value1,key2:value2,key3:value3,...

  • Access: protected

Parameters:

string   $str   —  The string to convert to an array

[ Top ]

_generateForm   [line 1123]

object &_generateForm( [string $action = false], [string $target = '_self'], [string $formName = false], [string $method = 'post'])

DB_DataObject_FormBuilder::_generateForm()

Builds a simple HTML form for the current DataObject. Internal function, called by the public getForm() method. You can override this in child classes if needed, but it's also possible to leave this as it is and just override the getForm() method to simply fine-tune the auto-generated form object (i.e. add/remove elements, alter options, add/remove rules etc.). If a key with the same name as the current field is found in the fb_preDefElements property, the QuickForm element object contained in that array will be used instead of auto-generating a new one. This allows for complete step-by-step customizing of your forms.

Note for date fields: HTML_QuickForm allows passing of an options array to the HTML_QuickForm_date element. You can define your own options array for date elements in your DataObject-derived classes by defining a method "dateOptions($fieldName)". FormBuilder will call that method whenever it encounters a date field and expects to get back a valid options array.


Parameters:

string   $action   —  The form action. Optional. If set to false (default), PHP_SELF is used.
string   $target   —  The window target of the form. Optional. Defaults to '_self'.
string   $formName   —  The name of the form, will be used in "id" and "name" attributes. If set to false (default), the class name is used
string   $method   —  The submit method. Defaults to 'post'.

[ Top ]

_getSelectOptions   [line 2089]

array _getSelectOptions( string $table, [array $displayFields = false], [bool $selectAddEmpty = false], [string $field = false], [string $valueField = false], [string $emptyLabel = false])

Internal function to get the select options for a table.
  • Return: strings representing all of the records in $table.
  • Access: protected

Parameters:

string   $table   —  The table to get the select display strings for.
array   $displayFields   —  array of diaply fields to use. Will default to the FB or DO options.
bool   $selectAddEmpty   —  If set to true, there will be an empty option in the returned array.
string   $field   —  the field in the current table which we're getting options for
string   $valueField   —  the field to use for the value of the options. Defaults to the PK of the $table
string   $emptyLabel   —  label to use for an empty option (defaults to $this->selectAddEmptyLabel)

[ Top ]

_reorderElements   [line 1837]

array _reorderElements( )

DB_DataObject_FormBuilder::_reorderElements()

Changes the order in which elements are being processed, so that you can use QuickForm's default renderer or dynamic templates without being dependent on the field order in the database.

Make a class property named "fb_preDefOrder" in your DataObject-derived classes which contains an array with the correct element order to use this feature.

  • Return: Array in correct order or same as _getFieldsToRender if preDefOrder is not set
  • Author: Fabien Franzen <atelierfabien@home.nl>
  • Access: protected

[ Top ]


Documentation generated on Mon, 11 Mar 2019 15:48:18 -0400 by phpDocumentor 1.4.4. PEAR Logo Copyright © PHP Group 2004.