Version: current

# Class TableListField

Form field that embeds a list into a form, such as a member list or a file list.

All get variables are namespaced in the format ctf[MyFieldName][MyParameter] to avoid collisions when multiple TableListFields are present in a form.

  Object
  ViewableData implements IteratorAggregate
  RequestHandler
  FormField
  TableListField

### Direct known subclasses

`CartTableListField`, `ComplexTableField`, `FileList`, `SubpageListField`, `SubsiteAgnosticTableListField`, `TableField`

### Indirect known subclasses

`AssetManager`, `AssetTableField`, `HasOneComplexTableField`, `HasOneDataObjectManager`, `HasOneFileDataObjectManager`, `ImageAssetManager`, `ImageDataObjectManager`, `ManyManyComplexTableField`, `ManyManyDataObjectManager`, `ManyManyFileDataObjectManager`, `Mediaweb3DPageFiles_Manager`, `MediawebPageFiles_Manager`, `CommentTableField`, `MediawebPagePhoto_Manager`, `MediawebPageTexture_Manager`, `MemberTableField`, `PhotoAlbumManager`, `VideoManager`, `DataObjectManager`, `DocumentPageFiles_Manager`, `FileComplexTableField`, `FileDataObjectManager`, `HasManyComplexTableField`, `HasManyDataObjectManager`, `HasManyFileDataObjectManager`

Package: forms\fields-relational
Param: $name string The fieldname
Param: $sourceClass string The source class of this field
Param: $fieldList array An array of field headings of Fieldname => Heading Text (eg. heading1)
Param: $sourceFilter string The filter field you wish to limit the objects by (eg. parentID)
Param: $sourceSort string
Param: $sourceJoin string
Located at sapphire/forms/TableListField.php

## Methods summary

`public` | # `__construct( `FormField::$name` $name, `FormField::$title` $sourceClass, `FormField::$value` $fieldList = null, `FormField::$form` $sourceFilter = null, maxLength $sourceSort = null, mixed $sourceJoin = null )` Create a new field. Create a new field. #### Parameters $name name The internal field name, passed to forms. $sourceClass title The field label. $fieldList value The value of the field. $sourceFilter form Reference to the container form $sourceSort maxLength The Maximum length of the attribute $sourceJoin #### Overrides `FormField::__construct`
`public` | # `sourceFilter( )` Get the filter Get the filter
`public` | # `index( )`
`public` | # `sourceClass( )`
`public` | # `handleItem( mixed $request )`
`public` | # `FieldHolder( )` Returns a "Field Holder" for this field - used by templates. Forms are constructed from by concatenating a number of these field holders. The default field holder is a label and form field inside a paragraph tag. Returns a "Field Holder" for this field - used by templates. Forms are constructed from by concatenating a number of these field holders. The default field holder is a label and form field inside a paragraph tag. Composite fields can override FieldHolder to create whatever visual effects you like. It's a good idea to put the actual HTML for field holders into templates. The default field holder is the DefaultFieldHolder template. This lets you override the HTML for specific sites, if it's necessary. #### Overrides `FormField::FieldHolder`
`public` | # `Headings( )`
`public` | # `disableSorting( mixed $to = true )`
`public boolean` | # `isFieldSortable( string $fieldName )` Determines if a field is "sortable". If the field is generated by a custom getter, we can't sort on it without generating all objects first (which would be a huge performance impact). Determines if a field is "sortable". If the field is generated by a custom getter, we can't sort on it without generating all objects first (which would be a huge performance impact). #### Parameters $fieldName string $fieldName #### Returns `boolean` bool
`public `DataObjectSet`` | # `Actions( )` Dummy function to get number of actions originally generated in TableListField_Item. Dummy function to get number of actions originally generated in TableListField_Item. #### Returns ``DataObjectSet`` DataObjectSet
`public` | # `setCustomQuery( `SQLQuery` $query )` Provide a custom query to compute sourceItems. This is the preferred way to using {@setSourceItems}, because we can still paginate. Caution: Other parameters such as {@sourceFilter} will be ignored. Please use this only as a fallback for really complex queries (e.g. involving HAVING and GROUPBY). Provide a custom query to compute sourceItems. This is the preferred way to using {@setSourceItems}, because we can still paginate. Caution: Other parameters such as {@sourceFilter} will be ignored. Please use this only as a fallback for really complex queries (e.g. involving HAVING and GROUPBY). #### Parameters $query $query SS_Query
`public` | # `setCustomCsvQuery( `SQLQuery` $query )`
`public` | # `setCustomSourceItems( `DataObjectSet` $items )`
`public` | # `sourceItems( )`
`public` | # `Items( )`
`public string` | # `getQuery( )` Generates the query for sourceitems (without pagination/limit-clause) Generates the query for sourceitems (without pagination/limit-clause) #### Returns `string` string
`public` | # `getCsvQuery( )`
`public` | # `FieldList( )`
`public` | # `setClick_AjaxLoad( mixed $urlBase, mixed $formID )` Configure this table to load content into a subform via ajax Configure this table to load content into a subform via ajax
`public` | # `setClick_PopupLoad( mixed $urlBase )` Configure this table to open a popup window Configure this table to open a popup window
`public` | # `performReadonlyTransformation( )` Returns a readonly version of this field Returns a readonly version of this field #### Overrides `FormField::performReadonlyTransformation`
`public String` | # `delete( )` #### Returns `String` String
`public` | # `addSummary( mixed $summaryTitle, mixed $summaryFieldList )` Can utilize some built-in summary-functions, with optional casting. Currently supported: sum avg Can utilize some built-in summary-functions, with optional casting. Currently supported: sum avg #### Parameters $summaryTitle $summaryTitle string $summaryFieldList $summaryFields array Simple Format: array("MyFieldName"=>"sum") With Casting: array("MyFieldname"=>array("sum","Currency->Nice"))
`public` | # `removeSummary( )`
`public` | # `HasSummary( )`
`public` | # `SummaryTitle( )`
`public` | # `SummaryFields( `DataObjectSet` $items = null )` #### Parameters $items DataObjectSet $items Only used to pass grouped sourceItems for creating partial summaries.
`public` | # `HasGroupedItems( )`
`public` | # `GroupedItems( )`
`public` | # `colFunction_sum( mixed $values )`
`public` | # `colFunction_avg( mixed $values )`
`public boolean` | # `Can( mixed $mode )` Template accessor for Permissions. See TableListField_Item->Can() for object-specific permissions. Template accessor for Permissions. See TableListField_Item->Can() for object-specific permissions. #### Returns `boolean` boolean
`public` | # `setPermissions( mixed $arr )`
`public array` | # `getPermissions( )` #### Returns `array` array
`public` | # `setShowPagination( mixed $bool )` ################################# Pagination ################################# # ################################# Pagination
`public boolean` | # `ShowPagination( )` #### Returns `boolean` boolean
`public` | # `setPageSize( mixed $pageSize )`
`public` | # `PageSize( )`
`public` | # `ListStart( )`
`public` | # `setExtraLinkParams( array $params )` #### Deprecated Put the query string onto your form's link instead :-) #### Parameters $params array
`public array` | # `getExtraLinkParams( )` #### Returns `array` array
`public` | # `FirstLink( )`
`public` | # `PrevLink( )`
`public` | # `NextLink( )`
`public` | # `LastLink( )`
`public` | # `FirstItem( )`
`public` | # `LastItem( )`
`public` | # `TotalCount( )`
`public String` | # `filterString( )` Compile all request-parameters for search and pagination (except the actual list-positions) as a query-string. Compile all request-parameters for search and pagination (except the actual list-positions) as a query-string. #### Returns `String` URL-parameters
`public` | # `setFieldListCsv( mixed $fields )` ################################# CSV Export ################################# # ################################# CSV Export
`public` | # `setCsvSeparator( mixed $csvSeparator )` Set the CSV separator character. Defaults to , Set the CSV separator character. Defaults to ,
`public` | # `getCsvSeparator( )` Get the CSV separator character. Defaults to , Get the CSV separator character. Defaults to ,
`public` | # `removeCsvHeader( )` Remove the header row from the CSV export Remove the header row from the CSV export
`public` | # `export( )` Exports a given set of comma-separated IDs (from a previous search-query, stored in a HiddenField). Uses {$csv_columns} if present, and falls back to {$result_columns}. We move the most filedata generation code to the function `TableListField::generateExportFileData()` so that a child class could reuse the filedata generation code while overwrite export function. Exports a given set of comma-separated IDs (from a previous search-query, stored in a HiddenField). Uses {$csv_columns} if present, and falls back to {$result_columns}. We move the most filedata generation code to the function `TableListField::generateExportFileData()` so that a child class could reuse the filedata generation code while overwrite export function.
`public` | # `generateExportFileData( mixed & $numColumns, mixed & $numRows )`
`public` | # `ExportLink( )` We need to instanciate this button manually as a normal button has no means of adding inline onclick-behaviour. We need to instanciate this button manually as a normal button has no means of adding inline onclick-behaviour.
`public` | # `printall( )`
`public` | # `PrintLink( )`
`public` | # `Utility( )` ################################# Utilty ################################# # ################################# Utilty
`public` | # `ajax_refresh( )` Returns the content of the TableListField as a piece of FormResponse javascript Returns the content of the TableListField as a piece of FormResponse javascript #### Deprecated Please use the standard URL through Link() which gives you the FieldHolder as an HTML fragment.
`public` | # `setFieldCasting( mixed $casting )`
`public` | # `setFieldFormatting( mixed $formatting )`
`public` | # `setCSVFieldFormatting( mixed $formatting )`
`public` | # `setFieldList( mixed $fieldList )` Edit the field list Edit the field list
`public String` | # `Name( )` #### Returns `String` String #### Overrides `FormField::Name`
`public` | # `Title( )` Returns the field label - used by templates. Returns the field label - used by templates. #### Overrides `FormField::Title`
`public` | # `NameSingular( )`
`public` | # `NamePlural( )`
`public mixed` | # `setTemplate( string $template )` Set name of template (without path or extension). Set name of template (without path or extension). Caution: Not consistently implemented in all subclasses, please check the `FormField::Field()` method on the subclass for support. #### Parameters $template string $template #### Returns `mixed` $this #### Overrides `FormField::setTemplate`
`public` | # `CurrentLink( )`
`public` | # `BaseLink( )`
`public `Int`` | # `sourceID( )` #### Returns ``Int`` Int
`public static array` | # `permissions_for_object( string $class, numeric $id = null )` Helper method to determine permissions for a scaffolded TableListField (or subclasses) - currently used in `ModelAdmin` and DataObject->scaffoldFormFields(). Returns true for each permission that doesn't have an explicit getter. Helper method to determine permissions for a scaffolded TableListField (or subclasses) - currently used in `ModelAdmin` and DataObject->scaffoldFormFields(). Returns true for each permission that doesn't have an explicit getter. #### Parameters $class string $class $id numeric $id #### Returns `array` array
`public` | # `getCastedValue( mixed $value, mixed $castingDefinition )` #### Parameters $value $value $castingDefinition
`public` | # `setHighlightConditions( mixed $conditions )` ######################### Highlighting ######################### # ######################### Highlighting

### Methods inherited from FormField

`Field()`, `LeftTitle()`, `Link()`, `Message()`, `MessageType()`, `Required()`, `RightTitle()`, `SmallFieldHolder()`, `Type()`, `Value()`, `addExtraAttribute()`, `addExtraClass()`, `allowHTML5()`, `allow_html5()`, `attrName()`, `attrTitle()`, `attrValue()`, `createTag()`, `dataValue()`, `debug()`, `describe()`, `extraClass()`, `fieldHolderTemplates()`, `fieldTemplates()`, `forTemplate()`, `getCustomValidationMessage()`, `getExtraClasses()`, `getForm()`, `getHTML5Attribute()`, `getTabIndex()`, `getTabIndexHTML()`, `hasClass()`, `hasData()`, `id()`, `isComposite()`, `isDisabled()`, `isReadonly()`, `jsValidation()`, `name_to_label()`, `performDisabledTransformation()`, `removeExtraAttribute()`, `removeExtraClass()`, `rootFieldSet()`, `saveInto()`, `securityTokenEnabled()`, `setAutocomplete()`, `setContainerFieldSet()`, `setCustomValidationMessage()`, `setDisabled()`, `setError()`, `setFieldHolderTemplate()`, `setForm()`, `setHTML5Attribute()`, `setLeftTitle()`, `setName()`, `setReadonly()`, `setRightTitle()`, `setSmallFieldHolderTemplate()`, `setTabIndex()`, `setTitle()`, `setValue()`, `smallFieldHolderTemplates()`, `transform()`, `useHTML5()`, `use_html5()`, `validate()`

### Methods inherited from RequestHandler

`allowedActions()`, `checkAccessAction()`, `getRequest()`, `handleRequest()`, `hasAction()`, `httpError()`

### Methods inherited from ViewableData

`ATT_val()`, `BaseHref()`, `CSSClasses()`, `ColumnBreak()`, `ColumnCalc()`, `ColumnNumber()`, `ColumnPad()`, `ColumnPos()`, `CurrentMember()`, `CurrentPage()`, `Debug()`, `Even()`, `EvenOdd()`, `First()`, `FirstLast()`, `HasPerm()`, `IsAjax()`, `JS_val()`, `Last()`, `Me()`, `Middle()`, `MiddleString()`, `Modulus()`, `MultipleOf()`, `Odd()`, `Pos()`, `RAW_val()`, `SQL_val()`, `ThemeDir()`, `ThemeName()`, `Top()`, `TotalItems()`, `XML_val()`, `__get()`, `__isset()`, `__set()`, `buildCastingCache()`, `cachedCall()`, `castingClass()`, `castingHelper()`, `castingHelperPair()`, `castingObjectCreator()`, `castingObjectCreatorPair()`, `customise()`, `defineMethods()`, `escapeTypeForField()`, `getField()`, `getIterator()`, `getSecurityID()`, `getXMLValues()`, `hasField()`, `hasValue()`, `i18nLocale()`, `iteratorProperties()`, `obj()`, `renderWith()`, `setCustomisedObj()`, `setField()`

### Methods inherited from Object

`__call()`, `__toString()`, `__wakeup()`, `addMethodsFrom()`, `addStaticVars()`, `addWrapperMethod()`, `add_extension()`, `add_static_var()`, `allMethodNames()`, `cacheToFile()`, `cacheToFileWithArgs()`, `clearCache()`, `combined_static()`, `create()`, `createMethod()`, `create_from_string()`, `exists()`, `extInstance()`, `extend()`, `getCustomClass()`, `getExtensionInstance()`, `getExtensionInstances()`, `get_extensions()`, `get_static()`, `hasExtension()`, `hasMethod()`, `has_extension()`, `invokeWithExtensions()`, `is_a()`, `loadCache()`, `parentClass()`, `parse_class_spec()`, `remove_extension()`, `sanitiseCachename()`, `saveCache()`, `set_stat()`, `set_static()`, `set_uninherited()`, `stat()`, `strong_create()`, `uninherited()`, `uninherited_static()`, `useCustomClass()`

### Magic methods summary

## Properties summary

`protected mixed` | $cachedSourceItems | # DataObjectSet Prevent {@sourceItems()} from being called multiple times. DataObjectSet Prevent {@sourceItems()} from being called multiple times.
`protected mixed` | $sourceClass | #
`protected string` | $sourceFilter | #
`protected string` | $sourceSort | #
`protected array` | $sourceJoin | #
`protected mixed` | $fieldList | #
`protected boolean` | $disableSorting | #
`protected mixed` | $fieldListCsv | # array array
`protected mixed` | $clickAction | #
`public boolean` | $IsReadOnly | #
`protected mixed` | $methodName | # Called method (needs to be retained for AddMode()) Called method (needs to be retained for AddMode())
`protected mixed` | $summaryFieldList | # array Shows a row which summarizes the contents of a column by a predefined Javascript-function array Shows a row which summarizes the contents of a column by a predefined Javascript-function
`protected mixed` | $summaryTitle | # string The title which will be shown in the first column of the summary-row. Accordingly, the first column can't be used for summarizing. string The title which will be shown in the first column of the summary-row. Accordingly, the first column can't be used for summarizing.
`protected string` | $template | # string Template-Overrides string Template-Overrides
`public string` | $itemClass | # string Class name for each item/row string Class name for each item/row
`public boolean` | $Markable | # Do we use checkboxes to mark records, or delete them one by one? Do we use checkboxes to mark records, or delete them one by one?
`public mixed` | $MarkableTitle | #
`protected mixed` | $readOnly | # boolean Deprecated, please use $permssions instead boolean Deprecated, please use $permssions instead
`protected array` | $permissions | # array Influence output without having to subclass the template. See $actions for adding your custom actions/permissions. array Influence output without having to subclass the template. See $actions for adding your custom actions/permissions.
`public array` | $actions | # array Action that can be performed on a single row-entry. Has to correspond to a method in a TableListField-class (or subclass). Actions can be disabled through $permissions. Format (key is used for the methodname and CSS-class): array( 'delete' => array( 'label' => 'Delete', 'icon' => 'cms/images/delete.gif', 'icon_disabled' => 'cms/images/delete_disabled.gif', 'class' => 'deletelink', ) ) array Action that can be performed on a single row-entry. Has to correspond to a method in a TableListField-class (or subclass). Actions can be disabled through $permissions. Format (key is used for the methodname and CSS-class): array( 'delete' => array( 'label' => 'Delete', 'icon' => 'cms/images/delete.gif', 'icon_disabled' => 'cms/images/delete_disabled.gif', 'class' => 'deletelink', ) )
`public string` | $defaultAction | # String Action being executed when clicking on table-row (defaults to "show"). Mostly needed in ComplexTableField-subclass. String Action being executed when clicking on table-row (defaults to "show"). Mostly needed in ComplexTableField-subclass.
`protected mixed` | $customQuery | # Specify custom query, e.g. for complicated having/groupby-constructs. Caution: TableListField automatically selects the ID from the {@sourceClass}, because it relies on this information e.g. in saving a TableField. Please use a custom select if you want to filter for other IDs in joined tables: $query->select[] = "MyJoinedTable.ID AS MyJoinedTableID" Specify custom query, e.g. for complicated having/groupby-constructs. Caution: TableListField automatically selects the ID from the {@sourceClass}, because it relies on this information e.g. in saving a TableField. Please use a custom select if you want to filter for other IDs in joined tables: $query->select[] = "MyJoinedTable.ID AS MyJoinedTableID"
`protected mixed` | $customCsvQuery | # Query for CSV-export (might need different fields or further filtering) Query for CSV-export (might need different fields or further filtering)
`protected mixed` | $customSourceItems | # DataObjectSet Use the manual setting of a result-set only as a last-resort for sets which can't be resolved in a single query. DataObjectSet Use the manual setting of a result-set only as a last-resort for sets which can't be resolved in a single query.
`protected string` | $csvSeparator | # Character to seperate exported columns in the CSV file Character to seperate exported columns in the CSV file
`protected boolean` | $csvHasHeader | #
`public array` | $csvFieldEscape | # Specify custom escape for the fields.
    array("\""=>"\"\"","\r"=>"", "\r\n"=>"", "\n"=>"")
Specify custom escape for the fields.
    array("\""=>"\"\"","\r"=>"", "\r\n"=>"", "\n"=>"")
`protected integer` | $totalCount | # Shows total count regardless or pagination Shows total count regardless or pagination
`protected boolean` | $showPagination | # Trigger pagination Trigger pagination
`public string` | $paginationBaseLink | # Override the `FormField::Link()` method for all pagination. Useful to force rendering of the field in a different context. Override the `FormField::Link()` method for all pagination. Useful to force rendering of the field in a different context.
`protected integer` | $pageSize | # Number of items to show on a single page (needed for pagination) Number of items to show on a single page (needed for pagination)
`public array` | $highlightConditions | # Definitions for highlighting table-rows with a specific 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. Example: array( array( "rule" => '$Flag == "red"', "class" => "red" ), array( "rule" => '$Flag == "orange"', "class" => "orange" ) ) Definitions for highlighting table-rows with a specific 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. Example: array( array( "rule" => '$Flag == "red"', "class" => "red" ), array( "rule" => '$Flag == "orange"', "class" => "orange" ) )
`public array` | $fieldCasting | # Specify castings with fieldname as the key, and the desired casting as value. Example: array("MyCustomDate"=>"Date","MyShortText"=>"Text->FirstSentence") Specify castings with fieldname as the key, and the desired casting as value. Example: array("MyCustomDate"=>"Date","MyShortText"=>"Text->FirstSentence")
`public array` | $fieldFormatting | # 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. Example: "myFieldName" => '$ID' 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. Example: "myFieldName" => '$ID'
`public array` | $csvFieldFormatting | #
`public string` | $exportButtonLabel | #
`public string` | $groupByField | # $groupByField Used to group by a specific column in the DataObject and create partial summaries. $groupByField Used to group by a specific column in the DataObject and create partial summaries.
`protected array` | $extraLinkParams | #
`protected mixed` | $__cachedQuery | #
`public static array` | $url_handlers | # The default URL handling rules. This specifies that the next component of the URL corresponds to a method to be called on this RequestHandlingData object. The default URL handling rules. This specifies that the next component of the URL corresponds to a method to be called on this RequestHandlingData object. The keys of this array are parse rules. See `SS_HTTPRequest::match()` for a description of the rules available. The values of the array are the method to be called if the rule matches. If this value starts with a '$', then the named parameter of the parsed URL wil be used to determine the method name.

### Properties inherited from FormField

`$autocomplete`, `$containerFieldSet`, `$customValidationMessage`, `$description`, `$disabled`, `$dontEscape`, `$extraAttributes`, `$extraClass`, `$extraClasses`, `$fieldHTML5`, `$fieldHolderTemplate`, `$form`, `$html5Attributes`, `$leftTitle`, `$message`, `$messageType`, `$name`, `$possible_autocomplete_values`, `$readonly`, `$rightTitle`, `$smallFieldHolderTemplate`, `$tabIndex`, `$title`, `$use_html5`, `$value`

### Properties inherited from RequestHandler

`$allowed_actions`, `$brokenOnConstruct`, `$request`

### Properties inherited from ViewableData

`$casting`, `$customisedObject`, `$default_cast`, `$failover`, `$iteratorPos`, `$iteratorTotalItems`

### Properties inherited from Object

`$class`, `$extension_instances`, `$extensions`

[Raise a SilverStripe Framework issue/bug](https://github.com/silverstripe/silverstripe-framework/issues/new)
- [Raise a SilverStripe CMS issue/bug](https://github.com/silverstripe/silverstripe-cms/issues/new)
- Please use the Silverstripe Forums to ask development related questions. -