This is the base class of zoglair database tables. It is actually a data modeler which provides free CRUD operations, through a design known as scaffolding. Descendants provide column definitions (~schema) in their constructor and optionally override one or more of the following methods.
Descendants of this class are instantiated as needed, via load_table().
- Parent Class
- zObject
- Public Methods (24)
- b4delete, delupin, extract_mual_text, fix_row, fix_set, get_by, get_col, get_col_cat, get_col_csv, get_col_null_value, get_col_options, get_default_set, get_empty_row, get_form, get_grid, get_list, get_path_level, get_table_row, is_form_action, is_path, is_tree, perform, validate_col, validate_row
- Protected Methods
- create
void b4delete(string $where) ⇧
A callback used in $zDbms
, before a DELETE operation. This is a stub that should be implemented by descedants.
- Parameters
- The
where
clause expression used for deletion
- Returns
- void
void delupin(string $action, mixed $mixed) ⇧
A callback used in $zDbms
, after a successfull CRUD operation. This is a stub that should be implemented by descedants.
- Parameters
- • The action which was just performed ('delete', 'update' or 'insert')
- • A map, row, id or null
- Returns
- void
mixed extract_mual_text(string $text, boolean $all=FALSE)static ⇧
Given a multilingual text, it extracts the part which is suitable for the active language.
- Parameters
- • A multilingual text
- • An optional flag for making the function return all extracts in a map of lang,text pairs
- Returns
- If
$all
is FALSE, a string containing the language specific part, otherwise a map of all parts
array fix_row(array &$ROW, integer $reason) ⇧
Fixes a table row before a CRUD operation. Depending on the operation (specified in $reason
), it may append/delete/change columns and/or values. This and fix_set(), are called by the database manager as needed, so there is usually no reason for calling them explicitly.
- Parameters
- • The row to be fixed (map of name,value pairs)
- • One of the following constants:
zDataBase::Z_FIX_FOR_UPDATE
zDataBase::Z_FIX_FOR_INSERT
zDataBase::Z_FIX_FOR_SELECT
(can be combined with zDataBase::Z_FIX_FOR_OUTPUT
, in which case multilingual strings are extracted according to active locale)
- Returns
- A vector of validation errors that may be produced (applicable in
*_UPDATE
and *_INSERT
fixes)
array fix_set(array &$SET, integer $reason) ⇧
This is a simple wrapper of fix_row(). Instead of accepting a single row (map of columns), it accepts a set (vector of rows).
- Parameters
- • The set to be fixed (by reference)
- • A bitmap of
Z_FIX_*
constants (see fix_row())
- Returns
- A vector of validation errors that may be produced (applicable in
*_UPDATE
and *_INSERT
fixes)
integer get_by()static ⇧
A small utility function to return the active user's id, used for setting the 'CreatedBy' and 'UpdatedBy' columns.
- Parameters
- none
- Returns
- The active user's id
mixed get_col(string $which='') ⇧
Retreives column definitions, single or all, for forms or grids, depending on its argument.
- Parameters
- The column definition to retreive, as following:
empty string
all defined master table columns
'<column_name>'
the specified master column
'form/<layout>'
all columns for the specified form layout
'grid/<layout>'
all columns for the specified grid layout
- Returns
- A map if a single column is requested, a tree for multiple columns, or NULL if the requested columns do not exist
integer get_col_cat(array $COL)static ⇧
Returns the broader category of a column type.
- Parameters
- The column to be queried
- Returns
zDataBase::Z_COL_CAT_NUMERIC
, zDataBase::Z_COL_CAT_STRING
or zDataBase::Z_COL_CAT_OTHER
string get_col_csv(string $which='', boolean $xauto=TRUE) ⇧
A get_col() wrapper to return a list of column names, in CSV format.
- Parameters
- • The column definition to retreive, as in get_col()
- • Exclude auto columns from the list?
- Returns
- A list of comma delimited column names
void get_col_null_value()static ⇧
made public for zClipFormX::parse()
- Parameters
- none
- Returns
- void
void get_col_options()static ⇧
made public for zClipFormHtmlField()
- Parameters
- none
- Returns
- void
mixed get_default_set() ⇧
It provides default rows for populating new tables. It is currently used by $zDbms
. Default sets are stored in the data/base
directory and can be created by either extensions or plain sql dumps.
- Parameters
- none
- Returns
- A vector of rows (set) or string with either sql statements or the name of an import file
array get_empty_row(string $which='') ⇧
Used for initializing a row (map of name,value pairs) with all columns and their default values, as specified in their null
property.
- Parameters
- The column definitions to be used for initializing the returned row (see get_col() for details)
- Returns
- A map of column names as keys and their default values
array get_form(string $form, array $ROW) ⇧
Returns column definitions and other information useful for updating a table row. Such information is currently used by zClipForm
.
- Parameters
- • The particular form layout requested (all tables support at least one
“default”
layout) - • A map of name,value pairs (such as a posted html form) to be used as column values
- Returns
- A map with the following keys:
- -
'cols'
a tree of pages (~fieldsets), columns and their properties
array get_grid(string $grid='') ⇧
Returns column definitions and other information useful for displaying a table in a grid. Such information is currently used by zClipGrid
.
- Parameters
- The particular grid layout requested (all tables support at least one
“default”
layout)
- Returns
- A map with the following keys:
'cols'
a vector of standard column properties plus “class”
, “width”
, “format”
and “alias”
'order'
the name of the column(s) to be used in the ORDER BY
clause
'menu'
additional popup menu options, if any
void get_list() ⇧
Returns column definitions and other information useful for displaying a table in a list. Such information is currently used by zClipNodeList
. This method simply calls get_grid() with a special argument so that a list is returned instead.
- Parameters
- none
- Returns
- void
integer get_path_level()static ⇧
Calculates a path's level.
- Parameters
- none
- Returns
- The path's level
array get_table_row(mixed $table, mixed $row=NULL)static ⇧
Loads a row (~record) from the specified table and returns it as a map.
- Parameters
- • A table name or object
- • NULL (to get an empty row), integer (used as id), string (used as name) or map (used as the row itself)
- Returns
- The requested row (if found), or
zDbmsBase::Z_ERROR
boolean is_form_action(string $action, boolean &$isnew) ⇧
Checks whether a specific form action is supported and if supported, whether it leads to the creation of a new row when performed. Examples of “new”
actions are 'insert' and 'duplicate'.
- Parameters
- • The particular action to be checked
- • A reference to receive the action's 'new' status
- Returns
- TRUE if action is supported, FALSE if not
boolean is_path() ⇧
Checks the table's model to find out if it is of a (materialized) path type. Such tables require special handling in CRUD operations.
- Parameters
- none
- Returns
- TRUE if the table is tree, FALSE if not
boolean is_tree() ⇧
Checks the table's model to find out if it is of a tree (nested set) type. Such tables require special handling in CRUD operations.
- Parameters
- none
- Returns
- TRUE if the table is tree, FALSE if not
mixed perform(string $action, array $ROW, mixed &$ERR) ⇧
Performs an action, most usually a CRUD operation. CRUD actions are executed by calling the corresponding DBMS methods. Custom actions are executed by user defined class methods named after the action and prefixed by 'perform_', eg: 'perform_login'.
- Parameters
- • The action to perform, eg: 'insert', 'update', etc
- • A map (such as a posted form) for setting column values
- • A reference that will be filled with error(s), if any
- Returns
- A boolean or scalar, depending on the operation, that can be evaluated to TRUE for successful results, or FALSE in case of errors
boolean validate_col(array $COL, mixed &$value, mixed &$mixed, object $Table=NULL)static ⇧
System-wide column validator.
- Parameters
- • A column map, as used in table models
- • A reference of the value to be validated
- • A string on array to receive the validation error message, if any
- • An optional table to be used when custom regx's are are encountered
- Returns
- TRUE if the input value is valid, FALSE if not
See also XSS Cheat Sheet.
boolean validate_row(array $SET, mixed &$VALUE, mixed &$mixed, object $Table=NULL)static ⇧
A wrapper of validate_col(), for looping through a tree of columns.
- Parameters
- • A column tree, as returned by get_col()
- • A reference of the values to be validated
- • A string on array to receive the validation error message, if any (an array makes better sense)
- • An optional table to be used when custom regx's are are encountered
- Returns
- TRUE if all input values are valid, FALSE if not
void create(array $MODEL, integer $type=self::Z_TBL_TYPE_FLAT)protected ⇧
Used in a table constructor to create its schema (~model).
- Parameters
- • The table's model
- • The table's type, as following:
zDataBase::Z_TBL_TYPE_SELF
(no additional columns are added)
zDataBase::Z_TBL_TYPE_FLAT
(standard zoglair system columns are added)
zDataBase::Z_TBL_TYPE_TREE
(additional nested set columns are added)
zDataBase::Z_TBL_TYPE_LOOP
(a progress bar is added)
- Returns
- void