Class: DB_DataObject_FormBuilder

The class constructor.

Parameters:

Factory method. Although not really needed at the moment, it is the recommended method to make a new object instance. Benefits: Checks the passed parameters and returns a PEAR_Error object in case something is wrong. Also, it will make your code forward-compatible to future versions of this class, which might include other types or forms, resulting in this being a stripped-down base class that returns a specialized class for the desired purpose (i.e. for generating GTK form elements for use with PHP-GTK, WML forms for WAP...).

Options can be:

• 'rule_violation_message' : See description of similarly-named class property
• 'add_form_header' : See description of similarly-named class property
• 'form_header_text' : See description of similarly-named class property

Parameters:

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

Parameters:

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.

Parameters:

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. (Its display value will be surrounded by parenthesis as it may have multiple display fields of its own.)

Will use display field configurations from these locations, in this order:
1) $displayfield parameter
2) databaseName.formBuilder.ini file, section [tableName__display_fields]
3) the select_display_field member variable of the dataobject
4) global 'select_display_field' setting for DB_DataObject_FormBuilder

Parameters:

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

Parameters:

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

Parameters:

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 "select_display_field". If that one is not present, it will try to use the global configuration setting "select_display_field". Can also be called with a second parameter containing the name of the display field - this will override all other settings. Same goes for "select_order_field", 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.

Parameters:

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

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:

 if ($form->validate()) {

     $form->freeze();
     $form->process(array(&$formGenerator,'processForm'), false);
 }

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 "preProcess()" 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 "postProcess()", 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. ...

Parameters:

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

Parameters:

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

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.

Beware: For the date conversion to work, you must at least use the letters "d", "m" and "Y" in your format string (see "date_element_format" 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.

Parameters:

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

Parameters:

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

Returns the QuickForm element type associated with the given field type, as defined in the _elementTypeMap property. If an unknown field type is given, the returned type name will default to 'text'.

Parameters:

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 "preDefOrder" in your DataObject-derived classes which contains an array with the correct element order to use this feature.