Back

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 ⁽²⁴⁾: 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