Class maintainer

Description

Class comprising functionality which allows a database table to be maintained through a user interface which allows the usual Add, Modify, Delete options, but which gets just about all the info it requires from the database schema itself. A dynamic maintainer.

Example of usage: consider a table 'foo' with an integer key field named 'bar', which comes from a sequence. It also has a field 'desc' of type 'text', and a foreign key field 'user_id' of type 'text' which refers to 'uuser.user_id'. For the sake of demonstration it also has a field 'auth_code' which we only ever want to view, a field called 'special' which we always want hidden, and a field called 'blurb' which is a memofield of specific sizing.

To maintain 'foo' you might then proceed as follows. Note that a lot of methods have been used here for illustration, but in fact you might easily use a lot less in real life.

$maint = new maintainer("Foo Maintenance", "foo"); $maint->set_title("Setup Users"); $maint->set_fieldsequence("bar", "seq_bar_id"); $maint->set_labelfields("uuser", "full_name"); $maint->set_nonblankfields("full_name,user_type,email"); $maint->set_hiddenfields("special"); $maint->set_viewonlyfields("auth_code"); $maint->set_fieldlabel("auth_code", "Authorization code"); $maint->set_fieldsize("blurb", 300, 250); $maint->set_datetimeformat("last_login", "M j H:i"); $maint->view_primary_keys(); $maint->view_record_filter(); ... $RESPONSE->plugin("MAIN_CONTENT", $maint->render());

Located in /maintainer-defs.php (line 108)

RenderableObject
   |
   --StylableObject
      |
      --HTMLObject
         |
         --maintainer
Variable Summary
Method Summary
 maintainer maintainer (string $title, string $tablename, [string $dbname = ""])
 void autosequence ()
 void detail_table (string $title, string $detail_tablename, [string $orderby = ""], integer $keywidth, [integer $keyrows = 6])
 void hide_statusbar ([boolean $mode = true])
 string html ()
 void joined_table (string $title, string $tablename, string $joinfields)
 void linked_table (string $title, string $linked_tablename, string $link_tablename, [string $uistyle = "combo"], [integer $uiperrow = 5])
 void set_allowed_groups (string $grouplist)
 void set_datetimeformat (string $fieldname, string $format)
 void set_disabledfields (string $fieldnames, [string $delim = ","])
 void set_fieldblurb (string $fieldname, string $blurb)
 void set_fieldcss (string $fieldname, string $css)
 void set_fielddisplayproc (string $fieldname, string $funcname)
 void set_fieldlabel (string $fieldname, string $label)
 void set_fieldpostproc (string $fieldname, string $funcname)
 void set_fieldsequence (string $fieldname, string $sequencename)
 void set_fieldsize (string $fieldname, string $pxwidth, string $pxheight)
 void set_fieldtexttype (string $fieldname, mixed $fieldtype, string $type)
 void set_fieldvalidationproc (string $fieldname, string $funcname, string $failmsg)
 void set_formenctype ([string $enctype = ""])
 void set_formfieldwidget (string $fieldname, object $element)
 void set_formname (string $formname)
 void set_hiddenbuttons (mixed $buttonnames, [string $delim = ","])
 void set_hiddenfields (string $fieldnames, [string $delim = ","])
 void set_labelfields (string $tablename, string $labelfields)
 void set_nonblankfields (string $fieldnames)
 void set_omittedfields (string $fieldnames, [string $delim = ","])
 void set_passwd_encryption ([boolean $mode = true])
 void set_title (string $title)
 void set_viewonlyfields (string $fieldnames, [string $delim = ","])
 void view_passwords ([boolean $mode = true])
 void view_primary_keys ([boolean $mode = true])
 void view_record_filter ([boolean $mode = true])
Variables
mixed $activated = false (line 171)

True if maintainer has been activated

mixed $current_row (line 138)

Current record/row

mixed $database = "" (line 111)

The name of the database containing the table

mixed $detail_tables = array() (line 160)

Array of detail tables. Master-detail relationship.

mixed $do_autosequence = true (line 148)

If true we auto-detect sequences for integer fields,

mixed $enctype = "" (line 174)

Maintainers form encoding type

mixed $formname = "" (line 115)

Name of form we will be using

mixed $hidden_buttons = array() (line 168)
mixed $joined_tables = array() (line 154)

Array of joined tables. Tables with a 1-to-1 link.

mixed $linked_tables = array() (line 157)

Array of linked tables. Tables forming many-to-many link.

mixed $msgs = array() (line 167)

Array of messages to display at the top of the maintainer.

mixed $passwd_encryption = false (line 126)

If true, password field content is encrypted

mixed $recvalid = false (line 135)

True if record is valid

mixed $rowcount = 0 (line 141)

Row count - total records in table

mixed $schema (line 120)

Database schema

mixed $show_recfilter = false (line 151)

If true we include a built-in record filter

mixed $show_statusbar = true (line 132)

If true, status bar is displayed

mixed $table (line 113)

Table requiring maintenance (object)

mixed $title = "" (line 144)

Title of this maintenance page


Redefinition of:
HTMLObject::$title
Title of the object
mixed $valid = false (line 177)

True if this maintainer is good to go

mixed $view_passwords = false (line 123)

If true, password field content is displayed

mixed $view_pks = false (line 129)

If true, primary keys are displayed

Inherited Variables

Inherited from HTMLObject

HTMLObject::$accesskey
HTMLObject::$align
HTMLObject::$alt
HTMLObject::$bgcolor
HTMLObject::$bgurl
HTMLObject::$border
HTMLObject::$color
HTMLObject::$height
HTMLObject::$hspace
HTMLObject::$lang
HTMLObject::$langdir
HTMLObject::$linkover_text
HTMLObject::$name
HTMLObject::$onblur
HTMLObject::$onchange
HTMLObject::$onclick
HTMLObject::$ondblclick
HTMLObject::$onfocus
HTMLObject::$onkeydown
HTMLObject::$onkeypress
HTMLObject::$onkeyup
HTMLObject::$onload
HTMLObject::$onmousedown
HTMLObject::$onmousemove
HTMLObject::$onmouseout
HTMLObject::$onmouseover
HTMLObject::$onmouseup
HTMLObject::$onselect
HTMLObject::$size
HTMLObject::$src
HTMLObject::$tabindex
HTMLObject::$target
HTMLObject::$user_attributes
HTMLObject::$valign
HTMLObject::$vspace
HTMLObject::$width

Inherited from StylableObject

StylableObject::$class
StylableObject::$id
StylableObject::$style
Methods
Constructor maintainer (line 186)

Create a new maintainer.

maintainer maintainer (string $title, string $tablename, [string $dbname = ""])
  • string $title: Title to display at top of this maintainer
  • string $tablename: Name of main table to maintain
  • string $dbname: Name of database table is to be found in
autosequence (line 927)

Auto-detect sequences for integer fields. The technique is to assume sequences are named after the field in the form: 'seq_{fieldname}' and if so then this sequence is associated with the given field named {fieldname}.

void autosequence ()
detail_table (line 1018)

Associates a detail table with the maintained table. This defines

the standard Master->Detail relationship where there are many detail records for each master record. This results in a special multi-record widget in which the detail records for the current master record can be maintained.

void detail_table (string $title, string $detail_tablename, [string $orderby = ""], integer $keywidth, [integer $keyrows = 6])
  • string $title: Title of this relationship, can be used as a heading
  • string $detail_tablename: Name of detail table
  • string $orderby: Comma-separated detail fields to order by
  • integer $keywidth: Optional width of key listbox in px
  • integer $keyrows: Optional number of key listbox rows
disable_autosequence (line 917)

Specify that the maintainer should not auto-detect sequences which

pertain to fields on the table. The default action is to look for sequences for all integer fields. This method allows you to turn this feature off, in case it is getting in the way. You can then use the set_fieldsequence() method

void disable_autosequence ()
hide_statusbar (line 943)

Specify whether the maintainer should show its status bar or not.

The initial default is that it is shown.

void hide_statusbar ([boolean $mode = true])
  • boolean $mode: If true then hide statusbar, else show it
html (line 1991)

Render the maintainer as HTML. Use the render() method rather than directly calling this method.

  • return: The HTML for this maintainer
string html ()

Redefinition of:
RenderableObject::html()
Return output suitable for normal HTML-capable device. This method must be over-ridden by a method of the same name in the descendant class which renders output to web browsers.
joined_table (line 963)

Associates a table with the maintained table. This is a table with a 1-to-1 or 1-to-many relationship with the table being maintained.

We currently support the '1-to-1' link where the joined table data is merged into the main table. This method will therefore cause that joined table's data to be maintained alongside the main data, as accessed via the join fields provided. The $joinfields should be a comma-delimited string of the following form: 'fieldA=fieldB,fieldX=fieldY' Where the first field is the one in the table being maintained, and the second the equivalent in the joined table. If only one field is supplied, it is assumed to be identically named in both.

void joined_table (string $title, string $tablename, string $joinfields)
  • string $title: Title of this linkage, will be used as a heading
  • string $tablename: Name of foreign key table
  • string $joinfields: Pairs of fields joining the tables
linked_table (line 990)

Associates a table with the maintained table via a link-table.

This defines the standard threesome which makes up a many-to-many link, and where the middle link-table consists only of the key fields common to both main tables. This method will cause the link table to be maintained via either a group of checkboxes, or a multiple select dropdown menu (combo box). NB: This mechanism assumes that the field-naming follows the convention whereby the link-table key is composed of keyfields which are named identically to the keyfields in each of the linked tables (the maintained one and the linked one).

void linked_table (string $title, string $linked_tablename, string $link_tablename, [string $uistyle = "combo"], [integer $uiperrow = 5])
  • string $title: Title of this linkage, will be used as a heading
  • string $linked_tablename: Name of linked table
  • string $link_tablename: Name of table linking the two tables
  • string $uistyle: User interface style to use: "combo" or "checkbox"
  • integer $uiperrow: Maximum number of UI entities per row
set_allowed_groups (line 890)

Restrict access. Use this method to restrict maintainer access to the specified group membership. This will cause the RESPONSE to be sent without any content.

void set_allowed_groups (string $grouplist)
  • string $grouplist: Comma-delimited list of user groups to allow
set_datetimeformat (line 864)

Sets a datetime format string for a specified field. This influences the formatting of displayed dates and/or times in that field.

void set_datetimeformat (string $fieldname, string $format)
  • string $fieldname: Name of field to link sequence to.
  • string $format: Datetime format string eg: "d/m/Y H:i:s"
set_disabledfields (line 489)

Specify that the given fields should be disabled, not editable. Field is seen on screen, but is not modifiable.

void set_disabledfields (string $fieldnames, [string $delim = ","])
  • string $fieldnames: Comma-delimited list of field names to disable
  • string $delim: Delimiter - defaulted to ','
set_fieldblurb (line 802)

Associates a string of text 'blurb' with the field. This will be presented just sitting below the field as explanatory text.

void set_fieldblurb (string $fieldname, string $blurb)
  • string $fieldname: Name of field to link sequence to.
  • string $blurb: Text string of info/blurb for this field
set_fieldcss (line 603)

Sets the CSS style/class for a field.

void set_fieldcss (string $fieldname, string $css)
  • string $fieldname: Name of field to apply style/class to.
  • string $css: Style setting, or CSS classname
set_fielddisplayproc (line 743)

Associates a function with the field which will be called when data is displayed to format the content. Only really useful for text/memo/numeric fields. The function should accept a string content parameter, and return the re-formatted string content.

void set_fielddisplayproc (string $fieldname, string $funcname)
  • string $fieldname: Name of field to link sequence to.
  • string $funcname: Name of function to re-format content
set_fieldlabel (line 657)

Sets the label of the field, which then takes the place of the default naming which uses a proper-cased version of the field name, with underscores replaced by spaces.

void set_fieldlabel (string $fieldname, string $label)
  • string $fieldname: Name of field to set size of.
  • string $label: Field label string to use.
set_fieldpostproc (line 713)

Associates a function with the field which will be called when data is POSTed to format the content. Only really useful for text/memo/numeric fields. The function should accept a string content parameter, and return the re-formatted string content.

void set_fieldpostproc (string $fieldname, string $funcname)
  • string $fieldname: Name of field to link sequence to.
  • string $funcname: Name of function to re-format content
set_fieldsequence (line 685)

Associates a named sequence with a field. This is so we can create new records using that sequence to populate the record field.

Notes: the maintainer will, as default, try to detect sequences for integer fields. @see disable_autosequence method.

void set_fieldsequence (string $fieldname, string $sequencename)
  • string $fieldname: Name of field to link sequence to.
  • string $sequencename: Name of sequence to link to this field.
set_fieldsize (line 629)

Sets the size of the field in pixels, width x height

void set_fieldsize (string $fieldname, string $pxwidth, string $pxheight)
  • string $fieldname: Name of field to set size of.
  • string $pxwidth: Width of field in pixels
  • string $pxheight: Height of field in pixels
set_fieldtexttype (line 578)

Sets the type of a text field. This is a generic type and the

possibilities are: 'text' Standard text field 'password' Rendered as a password field, and a confirm field 'memo' Standard textarea widget 'image' Text field which contains an image which is displayed

void set_fieldtexttype (string $fieldname, mixed $fieldtype, string $type)
  • string $fieldname: Name of field to set size of.
  • string $type: Generic display type of the text field
set_fieldvalidationproc (line 773)

Associates a function with the field which will be called when data is POSTed to validate the content. The function should accept a string content parameter, and return true (if valid) or false.

void set_fieldvalidationproc (string $fieldname, string $funcname, string $failmsg)
  • string $fieldname: Name of field to link sequence to.
  • string $funcname: Name of function to re-format content
  • string $failmsg: Message to display if validation fails
set_formenctype (line 415)

Specify the maintainers form encoding type. This will enable us to use file upload fields within the maintainer.

void set_formenctype ([string $enctype = ""])
  • string $enctype: the encoding type the form is to use. leave blank for stand form encoding.
set_formfieldwidget (line 548)

Use given user interface element for maintaining specified table field.

void set_formfieldwidget (string $fieldname, object $element)
  • string $fieldname: Name of field to use form field for
  • object $element: Form user interface element to use
set_formname (line 403)

Set the name of the form we should use. Sometimes this is useful when other entities are using the same form.

void set_formname (string $formname)
  • string $formname: The name of the maintainer form to use
set_hiddenbuttons (line 460)

Specify that the given buttons should be hidden. BY default all the usual buttons are available. This method allows you to list those which should NOT be shown. Possible button names are: 'save', 'reset', 'add', 'remove', 'cancel', 'refresh'.

void set_hiddenbuttons (mixed $buttonnames, [string $delim = ","])
  • mixed $buttonnames: Array or delimited list of button names to hide
  • string $delim: Delimiter - defaulted to ','
set_hiddenfields (line 479)

Specify that the given fields should be hidden, not editable. Value will be submitted on POST (save) via hidden field in form.

void set_hiddenfields (string $fieldnames, [string $delim = ","])
  • string $fieldnames: Comma-delimited list of field names to hide
  • string $delim: Delimiter - defaulted to ','
set_labelfields (line 833)

Associates a list of fieldnames on a table to use as the label for a drop-down select reference. This is mainly so you can specify meaningful label strings for drop-down selects on foreign keyed fields, although it will work on any table, not just FKs.

Note: The list of field names should be comma-delimited.

void set_labelfields (string $tablename, string $labelfields)
  • string $tablename: Name of foreign key table
  • string $labelfields: Names of fields on this table for label
set_nonblankfields (line 427)

Specify that the given field should be non-blank. This causes a check to be made on form submit and if any field is empty (nullstring) then a warning message is displayed and submit is prevented.

void set_nonblankfields (string $fieldnames)
  • string $fieldnames: Comma-delimited list of non-blank field names
set_omittedfields (line 498)

Specify that the given field should be omitted from the form

void set_omittedfields (string $fieldnames, [string $delim = ","])
  • string $fieldnames: Comma-delimited list of field names to omit
  • string $delim: Delimiter - defaulted to ','
set_passwd_encryption (line 1058)

Whether passwords are encrypted or not. If true then we just apply the standard MD5 algorithm to the content.

void set_passwd_encryption ([boolean $mode = true])
  • boolean $mode: Whether to enrypt passwords or not
set_title (line 904)

Set the title of this maintainer. The default is derived from the name of the maintained table, with 'Maintenance' appended. Otherwise set your own title using this method.

void set_title (string $title)
  • string $title: Title of this maintainer widget
set_viewonlyfields (line 508)

Specify that the given field should be displayed on the form as text (view-only) but will not be submitted with the form.

void set_viewonlyfields (string $fieldnames, [string $delim = ","])
  • string $fieldnames: Comma-delimited list of field names to view-only
  • string $delim: Delimiter - defaulted to ','
view_passwords (line 1049)

Allows content of any password fields to be shown for reference. This is useful to reference screens where someone might need to be able to read passwords from the maintenance screen. Defaults to false.

void view_passwords ([boolean $mode = true])
  • boolean $mode: If true then passwords are shown, else not
view_primary_keys (line 1039)

Allows primary key values to be viewed along with other data. It is sometimes useful to see this info in view-only mode.

void view_primary_keys ([boolean $mode = true])
  • boolean $mode: If true then primary keys are shown, else not
view_record_filter (line 1068)

Causes the filtering widgets to be viewed or not viewed. The filter widgets allow users to input rudimentary filtering criteria on a single field which they can select, in order to filter the recordset.

void view_record_filter ([boolean $mode = true])
  • boolean $mode: Whether to show a record filter or not

Inherited Methods

Inherited From HTMLObject

 HTMLObject::HTMLObject()
 HTMLObject::inherit_attributes()
 HTMLObject::setaccesskey()
 HTMLObject::setalign()
 HTMLObject::setalt()
 HTMLObject::setbackground()
 HTMLObject::setbgcolor()
 HTMLObject::setborder()
 HTMLObject::setcolor()
 HTMLObject::setheight()
 HTMLObject::sethspace()
 HTMLObject::setlang()
 HTMLObject::setlangdir()
 HTMLObject::setname()
 HTMLObject::setsize()
 HTMLObject::setsrc()
 HTMLObject::settabindex()
 HTMLObject::settarget()
 HTMLObject::settitle()
 HTMLObject::setvalign()
 HTMLObject::setvspace()
 HTMLObject::setwidth()
 HTMLObject::set_attribute()
 HTMLObject::set_linkover_text()
 HTMLObject::set_onblur()
 HTMLObject::set_onchange()
 HTMLObject::set_onclick()
 HTMLObject::set_ondblclick()
 HTMLObject::set_onfocus()
 HTMLObject::set_onkeydown()
 HTMLObject::set_onkeypress()
 HTMLObject::set_onkeyup()
 HTMLObject::set_onload()
 HTMLObject::set_onmousedown()
 HTMLObject::set_onmousemove()
 HTMLObject::set_onmouseout()
 HTMLObject::set_onmouseover()
 HTMLObject::set_onmouseup()
 HTMLObject::set_onselect()
 HTMLObject::set_tabindex()
 HTMLObject::taghtml()

Inherited From StylableObject

 StylableObject::StylableObject()
 StylableObject::clearstyle()
 StylableObject::setclass()
 StylableObject::setcss()
 StylableObject::setid()
 StylableObject::setstyle()

Inherited From RenderableObject

 RenderableObject::RenderableObject()
 RenderableObject::html()
 RenderableObject::render()
 RenderableObject::wml()
 RenderableObject::wmlup()
 RenderableObject::xml()

Documentation generated by phpDocumentor 1.3.0RC3