Ferreteria/v2/usage/forms: Difference between revisions

From Woozle Writes Code
< Ferreteria‎ | v2‎ | usage
Jump to navigation Jump to search
(rules)
m (23 revisions imported: moving this project here)
 
(17 intermediate revisions by one other user not shown)
Line 1: Line 1:
==About==
==About==
''This page may be slightly out of date, e.g. class names may have changed.''
'''Forms''' in Ferreteria consist of several sets of classes that work together:
'''Forms''' in Ferreteria consist of several sets of classes that work together:
* '''control''' classes render editable (and eventually non-editable) data fields
* '''control''' classes render editable (and eventually non-editable) data fields
* '''field''' classes handle translating values between internal storage and on-disk storage (database)
* '''field''' classes handle translating values between internal storage and on-disk storage (database)
==Rules==
==Status==
* Every '''control''' (clsCtrl) belongs to a '''control row''' (clsCtrls).
* This is version 0.2 (originally designated version 2, but renumbered in 2020) of the Forms classes.
* '''Control row'''s can be indexed in order to allow for multi-row editing.
* It was rewritten from scratch in 2015, superseding [[Ferreteria/v0.1]].
* '''clsCtrls''' should eventually be renamed '''clsCtrlRow'''.
* It is superseded by [[Ferreteria/v0.3]].
* I haven't decided if there needs to be a clsForm class for containing multiple control rows.
==Subpages==
** Indexing is optional if you're only editing one row at a time.
* [[/creating]]
==Pages==
* [[/displaying]]
* {{l/ferreteria/|changes/1}}: change to Save() parameters
{| width=100%
 
| valign=top bgcolor=#efe |
==Files==
==Files==
* {{ferreteria/code|util/forms.php}}
* {{ferreteria/code|forms/ctrl.php}}
* {{ferreteria/code|form-data.php}}
** '''fcFormControl''' (abstract)
*** '''fcFormControl_HTML''' &larr; fcFormControl
**** '''fcFormControl_HTML_TextArea''' &larr; fcFormControl_HTML
**** '''fcFormControl_HTML_Hidden''' &larr; fcFormControl_HTML
**** '''fcFormControl_HTML_DropDown''' &larr; fcFormControl_HTML
**** '''fcFormControl_HTML_CheckBox''' &larr; fcFormControl_HTML
* {{ferreteria/code|forms/field.php}}
** '''fcFormField'''
*** '''fcFormField_Num''' &larr; fcFormField
*** '''fcFormField_Time''' &larr; fcFormField
* {{ferreteria/code|forms/form.php}}
** '''fcForm''' (abstract)
*** '''fcForm_keyed''' &larr; fcForm
* {{ferreteria/code|forms/form-data.php}}
** '''fcForm_DB''' &larr; fcForm_keyed
* {{ferreteria/code|db/v1/menu-data.php}}
** '''clsDataRecord_admin''' &larr; clsDataSet
| valign=top bgcolor=#eef |
==Classes==
==Classes==
The way this is organized is a little messed up; the descendants of clsCtrls handle database interaction -- but shouldn't it be the descendants of clsFields? It works reasonably well as is, but some rethinking might be a good idea, once everything is all mapped out.
* '''fcForm''' (abstract)
 
** '''fcForm_keyed''' &larr; fcForm
===collections===
*** '''fcForm_DB''' &larr; fcForm_keyed
* '''clsCtrls''' (abstract): a collection of '''clsCtrl''' form controls -- often referred to in code as a "form object"
* '''fcFormField'''
** '''clsForm_recs''': form object that knows how to interact with a database table
** '''fcFormField_Num''' &larr; fcFormField
*** '''clsForm_recs_indexed''': form object that knows how to interact with a ''keyed'' database table (allowing for additional functionality)
** '''fcFormField_Time''' &larr; fcFormField
* '''clsFields''': a collection of '''clsField''' objects
* '''fcFormControl''' (abstract)
 
** '''fcFormControl_HTML''' &larr; fcFormControl
===unitary objects===
*** '''fcFormControl_HTML_TextArea''' &larr; fcFormControl_HTML
* '''clsField''': a generic (unspecialized) field, suitable for plain text
*** '''fcFormControl_HTML_Hidden''' &larr; fcFormControl_HTML
** '''clsFieldTime''': field for storing date/time
*** '''fcFormControl_HTML_DropDown''' &larr; fcFormControl_HTML
** '''clsFieldNum''': field for storing numeric (int or float) data
*** '''fcFormControl_HTML_CheckBox''' &larr; fcFormControl_HTML
** '''clsFieldBool''': field for storing a BIT-type boolean field (which, oddly, is returned as a single character instead of numeric)
* '''clsDataRecord_admin'''
*** should be renamed clsFieldBool_bit, or maybe this class should be abstract and clsFieldBool_bit should descend from it
|}
*** '''clsFieldBool_Int''': field for storing a boolean value stored as an integer
==Significant Functions==
* '''clsCtrl''' (abstract): a generic UI control
* '''fcForm'''
** '''clsCtrlHTML''': a control for an HTML form, suitable for single-line text entry
** ControlArray({{arg|array of control objects (optional)}}) - set/get all control objects
*** '''clsCtrlHTML_TextArea''': HTML multiline text entry control
** ControlObject({{arg|name}},{{arg|control object (optional)}}) - set/get control object for given name
*** '''clsCtrlHTML_CheckBox''': HTML checkbox control
** AddField({{arg|field object}}, {{arg|control object}})
*** '''clsCtrlHTML_DropDown''': HTML single-choice drop-down control
** abstract LoadRecord()
*** '''clsCtrlHTML_Hidden''': HTML invisible control, for returning calculated data
** abstract SaveRecord()
*** '''clsCtrlHTML_Fixed''': HTML control for displaying pre-set data; useful for creating new records
** RecordValue({{arg|name}},{{arg|value (optional)}}) - set/get field value
*** '''clsCtrlHTML_ReadOnly''': HTML control for non-editable data
** RecordValues({{arg|array of values (optional)}}) - set/get all field values
*** '''clsCtrlHTML_Rating''': HTML control for entering a rating (integer with fixed range and intervals)
** NewValues({{arg|array of values (optional)}}) - set/get values for new records
** ClearValues()
** RenderControls({{arg|edit?}})
* '''fcForm_keyed'''
** Get_KeyString_loaded()
** Set_KeyString_loaded({{arg|key string}})
** Get_KeyString_toSave()
** Set_KeyString_toSave({{arg|key string}})
** HasKey()
* '''fcForm_DB'''
** RecordsObject({{arg|recordset object (optional)}}) - set/get recordset object
** RecordValues_SQL() - get array of SQL-ready record values
** LoadRecord()
** SaveRecord()
* '''fcFormField'''
** FormObject({{arg|form object (optional)}}) - set/get form object
** NameString({{arg|name string (optional)}}) - set/get field's name
** ValueNative({{arg|value string (optional)}}) - set/get field's internal value
** ValueDisplay({{arg|value string (optional)}}) - set/get field's display value
** ValueSQL({{arg|value string (optional)}}) - set/get field's SQL value
** static Convert_DisplayToNative({{arg|value string}})
** static Convert_NativeToDisplay({{arg|value string}})
** static Convert_SQLToNative({{arg|value string}})
** static Convert_NativeToSQL({{arg|value string}})
* '''fcFormControl'''
** FormObject({{arg|form object (optional)}}) - set/get form object
** FieldObject({{arg|field object (optional)}}) - set/get field object
** abstract Render({{arg|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()

Latest revision as of 16:46, 22 May 2022

About

This page may be slightly out of date, e.g. class names may have changed.

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)

Status

  • This is version 0.2 (originally designated version 2, but renumbered in 2020) of the Forms classes.
  • It was rewritten from scratch in 2015, superseding Ferreteria/v0.1.
  • It is superseded by Ferreteria/v0.3.

Subpages

Files

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()
Retrieved from "https://wooz.dev/mw/index.php?title=Ferreteria/v2/usage/forms&oldid=2757"