$Id: tableview.html 4824 2023-11-30 15:29:56Z honzam $
This document describes the configuration array for the TableEdit class, called Table View. Many of the parameters have sensefull defaults, so that you may start by defining only the necessary ones and changing the other parameters later.
The basic Table View grammar may be enhanced by other attributes, used in the script calling TableEdit. In AA admin/tabledit.php, there are already some special attributes used, which are listed at the end of this file.
Each table in this document describes attributes of a PHP array. The basic Table View with the two required parameters and one field (see table "Table View grammar") may be:
array ( "table" => "mytable", "type" => "browse", "fields" => array ( "id" => array ()));
A somewhat more useful one may be:
array (
"table" => "alerts_collection",
"type" => "browse",
"readonly" => false,
"addrecord" => false,
"buttons" => array ("update"=>1,"delete"=>1,"edit"=>1),
"button_add"=>1,
"gotoview" => "ac_edit",
"cond" => CheckPerms( $auth->getUid(), "slice", $slice_id, PS_FULLTEXT),
"orderby" => "description",
"messages" => array (
"no_item" => _m("No collection uses any filter defined in any slice you have Admin permissions to.")),
"fields" => array (
"id" => array (
"view" => array ("readonly" => true)),
"description" => array (
"caption" => _m("description"),
"view" => array ("type"=>"text","size"=>array("cols"=>30)),
"required" => true),
"showme" => array ( "caption" => _m("standard"),
"view" => array (
"type"=>"select",
"source"=>array("0"=>_m("no"),"1"=>_m("yes")),
"readonly" => true)),
"editorial" => array ( "view"=>array("type"=>"text","size"=>array("cols"=>35))),
"mail_from" => array (
"caption"=>"From:","hint"=>"mail header",
"view" => array ("type"=>"text","size"=>array("cols"=>15))),
"mail_reply_to" => array ("caption"=>"Reply-To:","view" => array ("type"=>"text","size"=>array("cols"=>15))), "mail_errors_to" => array ("caption"=>"Errors-To:","view" => array ("type"=>"text","size"=>array("cols"=>15))), "mail_sender" => array ("caption"=>"Sender:","view" => array ("type"=>"text","size"=>array("cols"=>15)))), "attrs" => array ( "table"=>"border=1", "table_search" =>"border=0"));
Contents:
| Attribute | Values | Description | Default |
| table | required: table name | ||
| type | edit | browse |
required: browse / edit view type | |
| attrs | table => |
additional attributes for data TABLE | |
table_search => |
additional attributes for search TABLE | ||
| addrecord | true | false |
show an empty record, applies only with readonly views | true |
| gotoview | view ID | which view to show after clicking on Edit or Insert (Browse
view) or after clicking on Cancel (Edit view) |
stay in the same view |
| listlen | number of records to be shown at once | 15 | |
| orderby | field to sort by | unsorted | |
| oderdir | a | d |
sort direction ascending / descending | a |
| messages | no_item => |
message to be shown when no items pass the WHERE SQL clause | |
error_insert => |
when insert fails | ||
error_update => |
when update fails | ||
error_delete => |
when delete fails | ||
| readonly | true | false |
default for all fields | true |
| where | SQL WHERE condition | ||
| search | true | false |
view the search form | true for browse, false for edit |
| primary | array (field1, field2, ...) |
If a table has more than 1 primary key, you must set it here. If there is just 1 primary key, it will be found automatically. If there is no primary key ... the table can't be edited by TableEdit. |
|
| triggers | array ("BeforeDelete"=>"fn1", "AfterInsert"=>"fn2", "BeforeUpdate"=>"fn3", ...) |
calls the function fn1($varset) etc. before or after the operation.
The parameter $varset is a CVarset instance used in the operation.
The Before- triggers must return true if the operation
is allowed, otherwise it isn't fired |
|
| fields | array (field_alias1 => field1_params,
...) |
field_alias may be the real database field name or an alias, field_params is an array of parameters for each field, see below | |
| join | array (table_name1 => join1_params, ...) |
allows to view joined records from several tables as it were one record. table_name must be the real database table name, join_params defines the join conditions, see below | |
| children | array (child_view_id1 => table1_params,
...) |
shows records from tables with relationship n:1, child_view_id is view ID of a view showing a child table, params are described below |
You usually don't need to set buttons. The defaults are set depending on other
settings. For information about how defaults are set, you best see the source
include/tabledit.php, function SetDefaultButtons().
Only if you are not satisfied with the defaults, set your own.
| Attribute | Values | Description | Default |
| buttons_down | delete => 1 |
show delete button (Edit view only) | |
edit => 1 |
show edit button (Edit view only) | ||
update => 1 |
show insert / update button (Edit view only) | ||
cancel => 1 |
show cancel (exit) button (Edit view only) | ||
delete_all => 1 |
show delete all button (Browse view only) | ||
update_all => 1 |
show update all button (Browse view only) | ||
| buttons_left | delete_checkbox => 1 |
show delete checkbox (Browse view only) | |
edit => 1 |
show edit button (Browse view only) |
| Attribute | Values | Description | Default |
| table | table owning this field | table of the Table View | |
| field | database field name | field alias | |
| caption | column caption, in Edit view linked to sort items by this column | field alias | |
| hint | hint to be shown under the caption | ||
| colspan_hint | hint to be shown on a new row under both the caption and the value | ||
| validate | number | email | filename |
validation type, number means a positive integer |
|
| validate_min | used with validate=number, bounds the value entered | ||
| validate_max | -"- | ||
| default | default value (for new records) | ||
| required | true | false |
required fields must be filled | false |
| view | array with field view definition, see below | ||
| view_new_record | array with field view definition, applied on new records, see below | the same parameters as for all other records |
| Attribute | Values | Description | Default |
| type | hide | select | checkbox | text | area | date |
userdef |
hidden | select box | text edit box | text area | date special | user defined function Date works on a timestamp stored in a numeric field in database. It is printed formatted with "format" and users may change it by typing another value in the same format. When using "default" in Field Parameters, give the numerical timestamp value. Checkbox is currently implemented as a select box with options Yes and No. User defined function is always used only to print the field value, always shown readonly. |
depends on database field type |
| size | array ("cols" => c, "rows"
=> r) |
used with "text edit box" (only "cols") and "text area" (both "cols" and "rows") types, replace "c" with number of columns, "r" with number of rows | c = 40, r = 4 |
| maxlen | number | applied on readonly fields: if the length of the field value exceeds this number, only the first maxlen characters are printed followed by dots ... | |
| function | required for "userdef" type, name of function
which takes field value as the only parameter |
||
| source | required for "select" type, array of ("value"=>"option") | ||
| format | required for "date", PHP date() format | ||
| readonly | true | false |
if false, shows only the field value instead of form controls | global table view "readonly", for "userdef"
type always true |
| href_view | readonly fields: links the text to another table view, allowing to edit the record identified by this field read-write fields: shows a linked Edit icon with the same meaning |
||
| html | true | false |
applied only on readonly fields, show as HTML or as plain text | false |
| unpacked | true | false |
useful for packed IDs: show the value unpacked, store it packed. When using "default" in Field Parameters, give the packed unquoted value. | false |
If you want to view fields from several tables in one record, the tables must have some relationship 1:1 (one-to-one) or 1:n (one-to-many). Use the child table as the main table of the Table View.
| Attribute | Values | Description |
| joinfields | array (child_field1 => master_field1, ...) |
field names defining the JOIN part of the underlying SELECT statement, i.e. SELECT TableView_table INNER JOIN join_table ON TableView_table.child_field1 = join_table.master_field1 ... |
| jointype | "1 to 1" or "n to 1" | join type (one-to-one or many-to-one) |
| Attribute | Values | Description |
| join | array (master_field1 => child_field1, ...) |
master fields must form the primary key in the master table |
| header | header to be shown above the child table |
| Attribute | Description |
| title | required: HTML page title |
| mainmenu | required: top navigation bar menu |
| submenu | required: left menu |
| caption | required: caption to be shown above the table |
| help | text to be shown under the caption |
| cond | required: permissions needed to access this table view |