zDataBase

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
(C) Nick B. Cassos - All Rights Reserved
powered by zoglair
page generated in 84ms (11 queries, 6ms)