mirror of
https://github.com/silverstripe/silverstripe-framework
synced 2024-09-04 08:47:59 +02:00
151 lines
4.8 KiB
Markdown
151 lines
4.8 KiB
Markdown
|
# Complex Table Field
|
|||
|
|
|||
|
## Introduction
|
|||
|
|
|||
|
Shows a group of DataObjects as a (readonly) tabular list (similiar to `[api:TableListField]`.)
|
|||
|
|
|||
|
You can specify limits and filters for the resultset by customizing query-settings (mostly the ID-field on the other
|
|||
|
side of a one-to-many-relationship).
|
|||
|
|
|||
|
See `[api:TableListField]` for more documentation on the base-class
|
|||
|
|
|||
|
## Source Input
|
|||
|
|
|||
|
See `[api:TableListField]`.
|
|||
|
|
|||
|
## Setting Parent/Child-Relations
|
|||
|
|
|||
|
ComplexTableField tries to determine the parent-relation automatically by looking at the $has_one property on the listed
|
|||
|
child, or the record loaded into the surrounding form (see getParentClass() and getParentIdName()). You can force a
|
|||
|
specific parent relation:
|
|||
|
|
|||
|
:::php
|
|||
|
$myCTF->setParentClass('ProductGroup');
|
|||
|
|
|||
|
|
|||
|
## Customizing Popup
|
|||
|
|
|||
|
By default, getCMSFields() is called on the listed DataObject.
|
|||
|
You can override this behaviour in various ways:
|
|||
|
|
|||
|
:::php
|
|||
|
// option 1: implicit (left out of the constructor), chooses based on Object::useCustomClass or specific instance
|
|||
|
$myCTF = new ComplexTableField(
|
|||
|
$this,
|
|||
|
'MyName',
|
|||
|
'Product',
|
|||
|
array('Price','Code')
|
|||
|
)
|
|||
|
|
|||
|
// option 2: constructor
|
|||
|
$myCTF = new ComplexTableField(
|
|||
|
$this,
|
|||
|
'MyName',
|
|||
|
'Product',
|
|||
|
array('Price','Code'),
|
|||
|
new FieldSet(
|
|||
|
new TextField('Price')
|
|||
|
)
|
|||
|
)
|
|||
|
|
|||
|
// option 3: constructor function
|
|||
|
$myCTF = new ComplexTableField(
|
|||
|
$this,
|
|||
|
'MyName',
|
|||
|
'Product',
|
|||
|
array('Price','Code'),
|
|||
|
'getCustomCMSFields'
|
|||
|
)
|
|||
|
|
|||
|
|
|||
|
## Customizing Display & Functionality
|
|||
|
|
|||
|
If you don't want several functions to appear (e.g. no add-link), there's several ways:
|
|||
|
|
|||
|
* Use ComplexTableField->setPermissions(array("show","edit")) to limit the functionality without touching the template
|
|||
|
(more secure). Possible values are "show","edit", "delete" and "add".
|
|||
|
|
|||
|
* Subclass ComplexTableField and override the rendering-mechanism
|
|||
|
* Use ComplexTableField->setTemplate() and ComplexTableField->setTemplatePopup() to provide custom templates
|
|||
|
|
|||
|
### Customising fields and Requirements in the popup
|
|||
|
|
|||
|
There are several ways to customise the fields in the popup. Often you would want to display more information in the
|
|||
|
popup as there is more real-estate for you to play with.
|
|||
|
|
|||
|
ComplexTableField gives you several options to do this. You can either
|
|||
|
|
|||
|
* Pass a FieldSet in the constructor.
|
|||
|
* Pass a String in the constructor.
|
|||
|
|
|||
|
The first will simply add the fieldset to the form, and populate it with the source class.
|
|||
|
The second will call the String as a method on the source class (Which should return a FieldSet) of fields for the
|
|||
|
Popup.
|
|||
|
|
|||
|
You can also customise Javascript which is loaded for the Lightbox. As Requirements::clear() is called when the popup is
|
|||
|
instantiated, ComplexTableField will look for a function to gather any specific requirements that you might need on your
|
|||
|
source class. (e.g. Inline Javascript or styling).
|
|||
|
|
|||
|
For this, create a function called "getRequirementsForPopup".
|
|||
|
|
|||
|
## Getting it working on the front end (not the CMS)
|
|||
|
|
|||
|
Sometimes you'll want to have a nice table on the front end, so you can move away from relying on the CMS for maintaing
|
|||
|
parts of your site.
|
|||
|
|
|||
|
You'll have to do something like this in your form:
|
|||
|
|
|||
|
:::php
|
|||
|
$tableField = new ComplexTableField(
|
|||
|
$controller,
|
|||
|
'Works',
|
|||
|
'Work',
|
|||
|
array(
|
|||
|
'MyField' => 'My awesome field name'
|
|||
|
),
|
|||
|
'getPopupFields'
|
|||
|
);
|
|||
|
|
|||
|
$tableField->setParentClass(false);
|
|||
|
|
|||
|
$fields = new FieldSet(
|
|||
|
new HiddenField('ID', ''),
|
|||
|
$tableField
|
|||
|
);
|
|||
|
|
|||
|
|
|||
|
You have to hack in an ID on the form, as the CMS forms have this, and front end forms usually do not.
|
|||
|
|
|||
|
It's not a perfect solution, but it works relatively well to get a simple ComplexTableField up and running on the front
|
|||
|
end.
|
|||
|
|
|||
|
To come: Make it a lot more flexible so tables can be easily used on the front end. It also needs to be flexible enough
|
|||
|
to use a popup as well, out of the box.
|
|||
|
|
|||
|
## Subclassing
|
|||
|
|
|||
|
Most of the time, you need to override the following methods:
|
|||
|
|
|||
|
* ComplexTableField->sourceItems() - querying
|
|||
|
* ComplexTableField->DetailForm() - form output
|
|||
|
* ComplexTableField_Popup->saveComplexTableField() - saving
|
|||
|
|
|||
|
### Examples
|
|||
|
|
|||
|
* `[api:AssetTableField]`
|
|||
|
* `[api:MemberTableField]`
|
|||
|
|
|||
|
## API Documentation
|
|||
|
|
|||
|
`[api:ComplexTableField]`
|
|||
|
|
|||
|
## Todo
|
|||
|
|
|||
|
* Find a less fragile solution for accessing this field through the main controller and ReferencedField, e.g. build a
|
|||
|
seperate CTF-instance (doesn't necessarly have to be connected to the original by ReferencedField)
|
|||
|
* Control width/height of popup by constructor (hardcoded at the moment)
|
|||
|
* Integrate search from MemberTableField.php directly on ComplexTableField
|
|||
|
* Less performance-hungry implementation of detail-view paging (don't return all items on a single view)
|
|||
|
* Use automatic has-many and many-many functions to return a ComponentSet rather than building the join manually
|
|||
|
* Javascript/Ajax-Sorting (see http://www.activewidgets.com/grid/ and http://openrico.org/rico/livegrid.page)
|