Ferreteria/v2/usage/forms

About

Forms in Ferreteria consist of several sets of classes that work together:

• control classes render editable (and eventually non-editable) data fields
• field classes handle translating values between internal storage and on-disk storage (database)

The Forms classes are being rewritten from scratch; this page applies to the new version (2). Version 1 is here.

Files Template:Ferreteria/code fcFormControl (abstract) fcFormControl_HTML ← fcFormControl fcFormControl_HTML_TextArea ← fcFormControl_HTML fcFormControl_HTML_Hidden ← fcFormControl_HTML fcFormControl_HTML_DropDown ← fcFormControl_HTML fcFormControl_HTML_CheckBox ← fcFormControl_HTML Template:Ferreteria/code fcFormField fcFormField_Num ← fcFormField fcFormField_Time ← fcFormField Template:Ferreteria/code fcForm (abstract) fcForm_keyed ← fcForm Template:Ferreteria/code fcForm_DB ← fcForm_keyed Template:Ferreteria/code clsDataRecord_admin ← clsDataSet

Classes fcForm (abstract) fcForm_keyed ← fcForm fcForm_DB ← fcForm_keyed fcFormField fcFormField_Num ← fcFormField fcFormField_Time ← fcFormField fcFormControl (abstract) fcFormControl_HTML ← fcFormControl fcFormControl_HTML_TextArea ← fcFormControl_HTML fcFormControl_HTML_Hidden ← fcFormControl_HTML fcFormControl_HTML_DropDown ← fcFormControl_HTML fcFormControl_HTML_CheckBox ← fcFormControl_HTML clsDataRecord_admin

Significant Functions

• fcForm
  • ControlArray(<array of control objects (optional)>) - set/get all control objects
  • ControlObject(<name>,<control object (optional)>) - set/get control object for given name
  • AddField(<field object>, <control object>)
  • abstract LoadRecord()
  • abstract SaveRecord()
  • RecordValue(<name>,<value (optional)>) - set/get field value
  • RecordValues(<array of values (optional)>) - set/get all field values
  • NewValues(<array of values (optional)>) - set/get values for new records
  • ClearValues()
  • RenderControls(<edit?>)
• fcForm_keyed
  • Get_KeyString_loaded()
  • Set_KeyString_loaded(<key string>)
  • Get_KeyString_toSave()
  • Set_KeyString_toSave(<key string>)
  • HasKey()
• fcForm_DB
  • RecordsObject(<recordset object (optional)>) - set/get recordset object
  • RecordValues_SQL() - get array of SQL-ready record values
  • LoadRecord()
  • SaveRecord()
• fcFormField
  • FormObject(<form object (optional)>) - set/get form object
  • NameString(<name string (optional)>) - set/get field's name
  • ValueNative(<value string (optional)>) - set/get field's internal value
  • ValueDisplay(<value string (optional)>) - set/get field's display value
  • ValueSQL(<value string (optional)>) - set/get field's SQL value
  • static Convert_DisplayToNative(<value string>)
  • static Convert_NativeToDisplay(<value string>)
  • static Convert_SQLToNative(<value string>)
  • static Convert_NativeToSQL(<value string>)
• fcFormControl
  • FormObject(<form object (optional)>) - set/get form object
  • FieldObject(<field object (optional)>) - set/get field object
  • abstract Render(<edit?>)
• clsDataRecord_admin
  • callbacks:
    • AdminRows(array $arFields,array $arOptions=NULL)
    • AdminRows_none(array $arOptions=NULL) - called if there are no rows
    • AdminRows_start(array $arOptions=NULL) - called before first row; by default, opens an HTML table
    • AdminRows_finish(array $arOptions=NULL) - called after last row; by default, closes the HTML table
    • AdminRows_after(array $arOptions=NULL) - called just before AdminRows() exits, regardless of whether there were rows
    • AdminRows_head(array $arFields,array $arOptions=NULL) - called after AdminRows_start(); by default, displays row headers
    • AdminRows_rows(array $arFields,array $arOptions=NULL) - called before AdminRows_finish(); useful for displaying totals
    • AdminField($sField,array $arOptions=NULL) - called for each field to display in AdminRows()

Usage

creating an edit form

from Template:Vbzcart/code (function PageForm()): <php> $oForm = new fcForm_DB($this->Table()->ActionKey(),$this); $oField = new fcFormField_Num($oForm,'ID_BuyerCard'); $oCtrl = new fcFormControl_HTML($oForm,$oField,array('size'=>4)); </php> The first line creates a Form object, the next line creates a Field, and the third line assigns a Control to the Field. Adding additional fields and controls follows the format of the last 2 lines.

Certain field classes have additional options. For example: <php> $oField = new fcFormField_Time($frm,'WhenEnt'); $oCtrl = new fcFormControl_HTML($frm,$oField,array('size'=>10)); $oField->Format('m/Y'); </php> This sets the format of the Control for the "WhenEnt" field based on the parameter string used by the PHP date() function – in this case, just the month (2 digits) and year (4 digits) are displayed.

creating a form template

See Template:Vbzcart/code (function PageTemplate()) for a working example.

displaying a form

See Template:Vbzcart/code (inside function AdminPage_basic()) for a working example of a full-page form.

It can also be done without templates by retrieving the control and asking it to render itself:<php> $oForm = $this->EditForm(); $oForm->LoadRecord(); $ftTag = $oForm->ControlObject('Name')->Render($doEdit); $ftCust = $oForm->ControlObject('ID_Cust')->Render($doEdit); $ftAddr = $oForm->ControlObject('ID_Addr')->Render($doEdit); $ftName = $oForm->ControlObject('ID_Name')->Render($doEdit); </php> ...(and so on), then manually plugging the rendered controls into the desired output format:<php> $out .= <<<__END__

...

ID:	$id
Tag:	$ftTag
Status:	$ftStatus
Customer:	$ftCust
Address:	$ftAddr
Name:	$ftName

__END__; </php>