mirror of
https://github.com/silverstripe/silverstripe-framework
synced 2024-10-22 14:05:37 +02:00
289 lines
7.3 KiB
Markdown
289 lines
7.3 KiB
Markdown
# TableListField
|
|
|
|
## Introduction
|
|
|
|
Form field that embeds a list of `[api:DataObject]`s into a form, such as a member list or a file list.
|
|
Provides customizeable columns, record-deletion by ajax, paging, sorting, CSV-export, printing, input by
|
|
`[api:DataObject]` or raw SQL.
|
|
|
|
## Example
|
|
|
|
Here's an example of a full featured TableListField implementation. It features editing members in the database directly
|
|
as a button on each record, as well as filtering, and sorting. It also makes use of the 'export' permission, allowing
|
|
export of data as a CSV.
|
|
|
|
:::php
|
|
function getReportField() {
|
|
$resultSet = new DataObjectSet();
|
|
$filter = `;
|
|
$sort = "Member.ID ASC";
|
|
$join = `;
|
|
$instance = singleton('Member');
|
|
$query = $instance->buildSQL($filter, $sort, null, $join);
|
|
$query->groupby[] = 'Member.ID';
|
|
|
|
$report = new TableListField(
|
|
'CorporateReport',
|
|
'Member',
|
|
array(
|
|
'ID' => 'ID',
|
|
'FirstName' => 'First Name',
|
|
'Surname' => 'Surname',
|
|
'Email' => 'Email',
|
|
'MembershipType' => 'Membership Type',
|
|
'MembershipStatus' => 'Membership Status',
|
|
'DateJoined' => 'Date Joined',
|
|
'PaidUntil' => 'Paid Until',
|
|
'Edit' => ''
|
|
)
|
|
);
|
|
|
|
$report->setCustomQuery($query);
|
|
|
|
$report->setFieldFormatting(array(
|
|
'Email' => '<a href=\"mailto: $Email\" title=\"Email $FirstName\">$Email</a>',
|
|
'Edit' => '<a href=\"admin/security/index/1?executeForm=EditForm&ID=1&ajax=1&action_callfieldmethod&fieldName=Members&ctf[childID]=$ID&ctf[ID]=1&ctf[start]=0&methodName=edit\"><img src=\"cms/images/edit.gif\" alt=\"Edit this member\" /></a>'
|
|
));
|
|
|
|
$report->setFieldCasting(array(
|
|
'DateJoined' => 'Date->Nice',
|
|
'PaidUntil' => 'Date->Nice'
|
|
));
|
|
|
|
$report->setShowPagination(true);
|
|
if(isset($_REQUEST['printable'])) {
|
|
$report->setPageSize(false);
|
|
} else {
|
|
$report->setPageSize(20);
|
|
}
|
|
|
|
$report->setPermissions(array(
|
|
'export',
|
|
'delete',
|
|
'print'
|
|
));
|
|
|
|
return $report;
|
|
}
|
|
|
|
|
|
For more information on each of the features used in the example, you can read below.
|
|
|
|
## Usage
|
|
|
|
### Source Input
|
|
|
|
:::php
|
|
// default: DataObject selection (e.g. all 'Product's)
|
|
$myTableListField = new TableListField(
|
|
'MyName',
|
|
'Product',
|
|
array('Price', 'Code')
|
|
);
|
|
|
|
// custom DataObjectSet
|
|
$myProducts = DataObject::get('Product','Code = "MyCode"');
|
|
$myTableListField->setCustomSourceItems($myProducts);
|
|
|
|
// custom SQL
|
|
$customCsvQuery = singleton('Product')->buildSQL();
|
|
$customCsvQuery->select[] = "CONCAT(col1,col2) AS MyCustomSQLColumn";
|
|
$myTableListField->setCustomCsvQuery($customQuery);
|
|
|
|
TableListField also tries to resolve Component-relations(has_one, has_many) and custom getters automatically:
|
|
|
|
:::php
|
|
$myTableListField = new TableListField(
|
|
'MyName',
|
|
'Product',
|
|
array(
|
|
'Buyer.LastName',
|
|
'PriceWithShipping'
|
|
)
|
|
);
|
|
// Product.php Example
|
|
class Product extends DataObject {
|
|
$has_one = array('Buyer'=>'Member');
|
|
function getPriceWithShipping() {
|
|
return $this->Price + $this->Shipping;
|
|
}
|
|
}
|
|
|
|
|
|
### Pagination
|
|
|
|
Paging works by AJAX, but also works without javascript on link-basis.
|
|
|
|
:::php
|
|
$myTableListField->setPageSize(100); // defaults to 20
|
|
|
|
|
|
### Sorting
|
|
|
|
The easiest method is to add the sorting criteria as a constructor parameter. Sorting should be applied manually, where
|
|
appropriate. Only direct columns from the produced SQL-query are supported.
|
|
|
|
Example (sorting by "FirstName" column):
|
|
|
|
:::php
|
|
$report = new TableListField(
|
|
'CorporateReport', // name
|
|
'Member', // sourceClass
|
|
array(
|
|
'ID' => 'ID',
|
|
'FirstName' => 'First Name',
|
|
'LastName' => 'Last Name',
|
|
), // fieldList
|
|
null, // sourceFilter
|
|
'FirstName' // sourceSort
|
|
);
|
|
|
|
|
|
If you want to sort by custom getters in your DataObject, please reformulate them to a custom SQL column. This
|
|
restriction is needed to avoid performance-hits by caching and sorting potentially large datasets on PHP-level.
|
|
|
|
### Casting
|
|
|
|
Column-values can be casted, based on the casting-types available through DBObject (sapphire/core/model/fieldtypes).
|
|
|
|
:::php
|
|
$myTableListField->setFieldCasting(array(
|
|
"MyCustomDate"=>"Date",
|
|
"MyShortText"=>"Text->FirstSentence"
|
|
));
|
|
|
|
|
|
### Permissions
|
|
|
|
Permissions vary in different TableListField-implementations, and are evaluated in the template.
|
|
By default, all listed permissions are enabled.
|
|
|
|
:::php
|
|
$myTableListField->setPermissions(array(
|
|
'delete',
|
|
'export',
|
|
'print'
|
|
));
|
|
|
|
|
|
### Formatting
|
|
|
|
Specify custom formatting for fields, e.g. to render a link instead of pure text.
|
|
Caution: Make sure to escape special php-characters like in a normal php-statement.
|
|
|
|
:::php
|
|
$myTableListField->setFieldFormatting(array(
|
|
"myFieldName" => '<a href=\"custom-admin/$ID\">$ID</a>'
|
|
));
|
|
|
|
|
|
### Highlighting
|
|
|
|
"Highlighting" is similiar to "Formatting", but applies to the whole row rather than a column.
|
|
Definitions for highlighting table-rows with a specific CSS-class. You can use all column-names
|
|
in the result of a query. Use in combination with {@setCustomQuery} to select custom properties and joined objects.
|
|
|
|
:::php
|
|
$myTableListField->setHighlightConditions(array(
|
|
array(
|
|
"rule" => '$Flag == "red"',
|
|
"class" => "red"
|
|
),
|
|
array(
|
|
"rule" => '$Flag == "orange"',
|
|
"class" => "orange"
|
|
)
|
|
));
|
|
|
|
|
|
### Export
|
|
|
|
Export works only to CSV currently, with following specs:
|
|
|
|
* Line delimiter: "\n"
|
|
* Separator: ";"
|
|
* Column-quotes: none
|
|
|
|
:::php
|
|
$myTableListField->setPermissions(array('export'));
|
|
$myTableListField->setFieldListCsv(array(
|
|
'Price' => 'Price',
|
|
'ItemCount' => 'Item Count',
|
|
'ModelNumber' => 'Model Number'
|
|
));
|
|
|
|
You can influence the exported values by adjusting the generated SQL.
|
|
|
|
:::php
|
|
$customCsvQuery = singleton('Product')->buildSQL();
|
|
$customCsvQuery->select[] = "CONCAT(col1,col2) AS MyCustomSQLColumn";
|
|
$myTableListField->setCustomCsvQuery($customQuery);
|
|
$myTableListField->setFieldListCsv(array(
|
|
'MyCustomSQLColumn'
|
|
));
|
|
|
|
|
|
### Row-Summaries
|
|
|
|
You can summarize specific columns in your result-set. The term "summary" is used in a broad sense, you can also
|
|
implement averages etc.
|
|
|
|
:::php
|
|
$myTableListField->addSummary(
|
|
'Total Revenue and Sales Count',
|
|
array(
|
|
"Price" => array("sum","Currency->Nice"),
|
|
"ItemCount" => "sum"
|
|
)
|
|
);
|
|
|
|
In TableField-implementation, these summaries also react to changes in input-fields by javascript.
|
|
Available methods:
|
|
|
|
* sum
|
|
* avg
|
|
|
|
### Grouping
|
|
|
|
Used to group by a specific column in the DataObject and create partial summaries.
|
|
Please use only together with addSummary().
|
|
(Automatically disables sorting).
|
|
|
|
:::php
|
|
$myTableListField->groupByField = 'MyColumnName';
|
|
|
|
|
|
## Best Practices
|
|
|
|
### Custom Sorting
|
|
|
|
Please subclass TableListField to implement custom sorting, following the naming-convention
|
|
"`colFunction_<yourFunctionName>`".
|
|
|
|
:::php
|
|
class CustomTableListField extends TableListField {
|
|
// referenced through "dateAverage"
|
|
function colFunction_dateAverage($values) {
|
|
// custom date summaries
|
|
}
|
|
}
|
|
|
|
|
|
### Adding Utility-functions
|
|
|
|
In case you want to perform utility-functions like "export" or "print" through action-buttons,
|
|
make sure to subclass Utility() which collates all possible actions.
|
|
|
|
### Customizing Look&Feel
|
|
|
|
You can exchange the used template, e.g. to change applied CSS-classes or the HTML-markup:
|
|
|
|
:::php
|
|
$myTableListField->setTemplate("MyPrettyTableListField");
|
|
|
|
|
|
|
|
## API Documentation
|
|
|
|
[api:TableListField]
|