TableDescriptor
in package
Definition of a database table.
Examples for usage are provided in the documentation for CrudkitServiceProvider. Important: all methods marked with "@stackable" (like the constructor and all set methods) can be used like this
$page = new TableDesriptor(...)
->addColumn(...)
->setSoftDeleteColumn(...)
->...
...easy
Tags
Table of Contents
- $columns : array<string|int, SQLColumn>
- __construct() : mixed
- Constructor
- addColumn() : mixed
- Adds a sql column to this table.
- defineCustomColumnAjax() : TableDescriptor
- Defines a column where you can handle what is displayed, and what the user can enter via ajax select search. Be carefull - you have to take care of the data!
- defineManyToOneColumn() : TableDescriptor
- Example: book.author_id is a many to one column. Related table.field is author.id Example code: see CrudkitServiceProvider doc
- defineManyToOneColumnAjax() : TableDescriptor
- See defineManyToOneColumn() - same, but rendered as an ajax selectbox (search for values).
- deleteRecord() : mixed
- getAllColumns() : array<string|int, string>|array<string|int, mixed>
- Returns an array of this tables columns, including extended information from Doctrine DBAL.
- getColumns() : array<string|int, string>|array<string|int, SQLColumn>
- Returns an array of this tables columns
- getCustomAjaxValues() : mixed
- getEmptyRecord() : array<string|int, mixed>
- Creates an empty records from this table for the create-update View.
- getHasAutoincrementKey() : bool
- getManyToOneColumnValues() : array<string|int, mixed>
- Returns values for each many-to-one column of this table (values from related tables)
- getName() : string
- getPrimaryKeyColumns() : array<string|int, string>|array<string|int, SQLColumn>
- Returns an array of this tables primary key columns
- getSoftDeleteColumn() : string
- getSoftDeletedValue() : mixed
- getSoftNotDeletedValue() : mixed
- hasColumn() : bool
- Checks if a column with a specific name exists in this table.
- postProcess() : array<string|int, mixed>
- Shortcut for `(new DataProcessor($table))->postProcess(...);`
- readRecordRaw() : array<string|int, mixed>
- Reads a record from the DB.
- readRecordsRaw() : array<string|int, mixed>
- Reads multiple records from the DB.
- setColumnPosition() : mixed
- Sets the position of a column (display order)
- setOrderBy() : mixed
- setSoftDeleteColumn() : mixed
- Defines a column as an indicator if the record is deleted or not.
Properties
$columns
private
array<string|int, SQLColumn>
$columns
= []
Methods
__construct()
Constructor
public
__construct(string $name, array<string|int, string> $primaryKeyColumns[, bool $hasAutoincrementKey = false ]) : mixed
Parameters
- $name : string
-
Name of the table (as defined in the database)
- $primaryKeyColumns : array<string|int, string>
-
String array of column names, which define the primary key of this table, or at least identify a single record. Remember: if no column is a PK, every column is a PK!
- $hasAutoincrementKey : bool = false
-
(default = false) Set this to TRUE if you have a column like and integer ID, which will be generated (MySQL Auto increment, MSSQL identity)
Return values
mixed —addColumn()
Adds a sql column to this table.
public
addColumn(string $name, string $label, string $type[, array<string|int, mixed> $options = [] ]) : mixed
You dont need to add every column that exists in the table, only those you need.
Parameters
- $name : string
-
The name of the column like its defined in the Database
- $label : string
-
The label to display the column on UI.
- $type : string
-
The datatype - for details see SQLColumn Class doc
- $options : array<string|int, mixed> = []
-
(optional) - for details see SQLColumn Class doc
Tags
Return values
mixed —defineCustomColumnAjax()
Defines a column where you can handle what is displayed, and what the user can enter via ajax select search. Be carefull - you have to take care of the data!
public
defineCustomColumnAjax(string $name, callable $onLoadCallback, callable $onSearchCallback[, AjaxOptions $ajaxOptions = null ]) : TableDescriptor
//Example for $result object if success (Json encoded):
{type : "result", data : {results : [{'id' : '23', 'text' => 'Joe Smith', 'img' => 'base64imageData'}, {id : '...'}]}}
//Example for $result object if error (Json encoded):
{type : "error", message : "404 not found" data : "some error data which will be logged by the Javascript console..."}
//Helper methods in CHelper class:
CHelper::getAjaxErrorResult();
CHelper::getAjaxResult();
Parameters
- $name : string
-
Name of the existing column. Cannot be a many to one column.
- $onLoadCallback : callable
-
Callback function for preparing the data which is displayed in the field. Params are: &$value, &$text, $record, $table, $page, $column. You can change &$value and &$text as you wish. $value already holds the fields current value (after select). $text is an additionl info text
- $onSearchCallback : callable
-
Callback function for when the user begins to type for searching data. Params are: &$results, $input, $table, $page, $column. You have to populate $results (see example above);
- $ajaxOptions : AjaxOptions = null
Tags
Return values
TableDescriptor —defineManyToOneColumn()
Example: book.author_id is a many to one column. Related table.field is author.id Example code: see CrudkitServiceProvider doc
public
defineManyToOneColumn(string $name, string $toTableName, string $columnName[, array<string|int, mixed> $secondaryColumnNames = [] ][, string $page = '' ][, array<string|int, mixed> $filterDefinitions = [] ][, bool $manualInput = false ]) : TableDescriptor
Parameters
- $name : string
-
Name of the column to defines as many to one
- $toTableName : string
-
Related table name
- $columnName : string
-
A column from the related table
- $secondaryColumnNames : array<string|int, mixed> = []
-
Secondary clolumn names from the related table. These are shown to the user when selecting the value (more = slower)
- $page : string = ''
-
A drilldown page if you want to display this relation as a link
- $filterDefinitions : array<string|int, mixed> = []
-
Additional filters to limit the relation
- $manualInput : bool = false
-
Allows the user to input custom data manually (without checking)
Tags
Return values
TableDescriptor —defineManyToOneColumnAjax()
See defineManyToOneColumn() - same, but rendered as an ajax selectbox (search for values).
public
defineManyToOneColumnAjax(string $name, string $toTableName, string $columnName[, array<string|int, mixed> $secondaryColumnNames = [] ][, string $page = '' ][, array<string|int, mixed> $filterDefinitions = [] ][, bool $manualInput = false ][, AjaxOptions|null $ajaxOptions = null ]) : TableDescriptor
Parameters
- $name : string
-
Name of the column to defines as many to one
- $toTableName : string
-
Related table name
- $columnName : string
-
A column from the related table
- $secondaryColumnNames : array<string|int, mixed> = []
-
Secondary clolumn names from the related table. These are shown to the user when selecting the value (more = slower)
- $page : string = ''
-
A drilldown page if you want to display this relation as a link
- $filterDefinitions : array<string|int, mixed> = []
-
Additional filters to limit the relation
- $manualInput : bool = false
-
Allows the user to input custom data manually (without checking)
- $ajaxOptions : AjaxOptions|null = null
-
additional options to control the ajax behavior
Tags
Return values
TableDescriptor —deleteRecord()
public
deleteRecord(array<string|int, mixed> $primaryKeyValues) : mixed
Parameters
- $primaryKeyValues : array<string|int, mixed>
Return values
mixed —getAllColumns()
Returns an array of this tables columns, including extended information from Doctrine DBAL.
public
getAllColumns([bool $namesOnly = false ]) : array<string|int, string>|array<string|int, mixed>
Make sure to call fetchAllColumns() at least once before calling this method.
Parameters
- $namesOnly : bool = false
-
(default = FALSE) TRUE = retruns string[] array with the column names, FALSE = return and array of SQLColumn[] objects
Return values
array<string|int, string>|array<string|int, mixed> —getColumns()
Returns an array of this tables columns
public
getColumns([bool $namesOnly = false ]) : array<string|int, string>|array<string|int, SQLColumn>
Parameters
- $namesOnly : bool = false
-
(default = FALSE) TRUE = retruns string[] array with the column names, FALSE = return and array of SQLColumn[] objects
Return values
array<string|int, string>|array<string|int, SQLColumn> —getCustomAjaxValues()
public
getCustomAjaxValues(mixed $record, PageDescriptor $page) : mixed
Parameters
- $record : mixed
- $page : PageDescriptor
Return values
mixed —getEmptyRecord()
Creates an empty records from this table for the create-update View.
public
getEmptyRecord([bool $setDbDefaultValues = true ]) : array<string|int, mixed>
Parameters
- $setDbDefaultValues : bool = true
-
Set the default values which are definded in the Database
Return values
array<string|int, mixed> —getHasAutoincrementKey()
public
getHasAutoincrementKey() : bool
Return values
bool —getManyToOneColumnValues()
Returns values for each many-to-one column of this table (values from related tables)
public
getManyToOneColumnValues([mixed $record = [] ][, bool $onlyCurrentValue = false ]) : array<string|int, mixed>
['column-name-1' => ['value-1', 'value-2'], 'column-name-2' => [...]]
Parameters
- $record : mixed = []
- $onlyCurrentValue : bool = false
Return values
array<string|int, mixed> —getName()
public
getName() : string
Return values
string —Name of the table (as defined in the database)
getPrimaryKeyColumns()
Returns an array of this tables primary key columns
public
getPrimaryKeyColumns([bool $namesOnly = false ]) : array<string|int, string>|array<string|int, SQLColumn>
Parameters
- $namesOnly : bool = false
-
(default = FALSE) TRUE = retruns string[] array with the column names, FALSE = return and array of SQLColumn[] objects
Return values
array<string|int, string>|array<string|int, SQLColumn> —getSoftDeleteColumn()
public
getSoftDeleteColumn() : string
Return values
string —Name of the soft delte column (soft delete is a pseudo delete)
getSoftDeletedValue()
public
getSoftDeletedValue() : mixed
Return values
mixed —Value of the soft delete Column that indicates that the record IS deleted
getSoftNotDeletedValue()
public
getSoftNotDeletedValue() : mixed
Return values
mixed —Value of the soft delete Column that indicates that the record is NOT deleted.
hasColumn()
Checks if a column with a specific name exists in this table.
public
hasColumn(string $columnName) : bool
Parameters
- $columnName : string
-
The name of the column to check
Return values
bool —postProcess()
Shortcut for `(new DataProcessor($table))->postProcess(...);`
public
postProcess(mixed $records[, bool $singleRecord = false ][, bool $formaDateAndTime = true ][, mixed $formatBool = true ][, mixed $formatDec = true ][, mixed $formatBinary = true ]) : array<string|int, mixed>
Parameters
- $records : mixed
- $singleRecord : bool = false
- $formaDateAndTime : bool = true
- $formatBool : mixed = true
- $formatDec : mixed = true
- $formatBinary : mixed = true
Tags
Return values
array<string|int, mixed> —readRecordRaw()
Reads a record from the DB.
public
readRecordRaw(array<string|int, string> $primaryKeyValues[, array<string|int, Filter> $filters = [] ][, mixed $throwErrorIfNotFound = true ]) : array<string|int, mixed>
Parameters
- $primaryKeyValues : array<string|int, string>
- $filters : array<string|int, Filter> = []
- $throwErrorIfNotFound : mixed = true
Return values
array<string|int, mixed> —Raw unprocessed record as an assoc array: ['column1' => value, 'column2' => value, ...]
readRecordsRaw()
Reads multiple records from the DB.
public
readRecordsRaw([int $pageNumber = 1 ][, string $searchColumnName = '' ][, string $searchText = '' ][, array<string|int, Filter> $filters = [] ][, bool $trimText = true ][, int $itemsPerPage = -1 ]) : array<string|int, mixed>
Parameters
- $pageNumber : int = 1
-
Pagination offset
- $searchColumnName : string = ''
-
The column name to apply the $searchText (if existing)
- $searchText : string = ''
-
The search text (if existing)
- $filters : array<string|int, Filter> = []
- $trimText : bool = true
-
Trim text >50 chars
- $itemsPerPage : int = -1
Return values
array<string|int, mixed> —Raw unprocessed records as an array: [0 => ['column1' => value, 'column2' => value, ...], 1 => [], 2 => [], ...]
setColumnPosition()
Sets the position of a column (display order)
public
setColumnPosition( $columnName, $where, $referenceColumnName) : mixed
$table->setColumnPosition('name', 'after', 'id'); //easy
Parameters
- $columnName :
-
Defines the column to be set to a specific position.
- $where :
-
Is either 'before' or 'after'
- $referenceColumnName :
-
Before or after this Column the $columnName will be placed
Return values
mixed —setOrderBy()
public
setOrderBy(string $columnName[, string $direction = 'asc' ]) : mixed
Parameters
- $columnName : string
- $direction : string = 'asc'
Return values
mixed —setSoftDeleteColumn()
Defines a column as an indicator if the record is deleted or not.
public
setSoftDeleteColumn(string $name[, mixed $deleted = true ][, mixed $notDeleted = false ]) : mixed
Important: the soft delete column must not be added as normal column to the table, cause this will make things hard (espcially for users) When a soft delete column is defined, and a user deletes a record on the webpage, the record wont be deleted. Only thing happen is that the value of the soft delete column will be changed, and crudkit wont display this record anymore. - Cool, isnt it?
Parameters
- $name : string
-
The name of the column
- $deleted : mixed = true
-
(default = FALSE) The value of this column that indicates the record is NOT delteted
- $notDeleted : mixed = false