Comments: on this page. Click to read or post your own.

Class TableListField

Description

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.

Located in /sapphire/forms/TableListField.php (line 23)

Object
   |
   --ViewableData
      |
      --RequestHandlingData
         |
         --FormField
            |
            --TableListField
Direct descendents
Class Description
ComplexTableField Provides a tabuar list in your form with view, edit and add links to edit records with a "has-one"-relationship. Detail-views are shown in a greybox-iframe.
TableField TableField behaves in the same manner as TableListField, however allows the addition of fields and editing of attributes specified, and filtering results.
FileList Form field that embeds a list into a form, such as a member list or a file list.
Variable Summary
static mixed $url_handlers
$actions $actions
$cachedSourceItems $cachedSourceItems
$clickAction $clickAction
$customCsvQuery $customCsvQuery
$customQuery $customQuery
$customSourceItems $customSourceItems
$defaultAction $defaultAction
mixed $fieldList
$fieldListCsv $fieldListCsv
string $groupByField
bool $Markable
mixed $methodName
int $pageSize
$permissions $permissions
$readOnly $readOnly
boolean $showPagination
mixed $sourceClass
mixed $sourceJoin
mixed $sourceSort
$summaryFieldList $summaryFieldList
$summaryTitle $summaryTitle
$template $template
Method Summary
static array permissions_for_object (string $class, [numeric $id = null])
TableListField __construct ( $name,  $sourceClass, [ $fieldList = null], [ $sourceFilter = null], [ $sourceSort = null], [ $sourceJoin = null])
void addSummary ($summaryTitle $summaryTitle, $summaryFields $summaryFieldList)
void ajax_refresh ()
void BaseLink ()
void Can ( $mode)
void colFunction_avg ( $values)
void colFunction_sum ( $values)
void CurrentLink ()
String delete ()
void export ()
void ExportLink ()
void FieldHolder ()
void FieldList ()
String filterString ()
void FirstItem ()
void FirstLink ()
void getCastedValue ($value $value,  $castingDefinition)
void getCsvQuery ()
void getCsvSeparator ()
array getPermissions ()
string getQuery ()
void GroupedItems ()
void handleItem ( $request)
void HasGroupedItems ()
void HasSummary ()
void Headings ()
void index ()
bool isFieldSortable (string $fieldName)
void Items ()
void LastItem ()
void LastLink ()
void ListStart ()
String Name ()
void NamePlural ()
void NameSingular ()
void NextLink ()
void PageSize ()
void PrevLink ()
void printall ()
void PrintLink ()
void removeCsvHeader ()
void removeSummary ()
void setClick_AjaxLoad ( $urlBase,  $formID)
void setClick_PopupLoad ( $urlBase)
void setCSVFieldFormatting ( $formatting)
void setCsvSeparator ( $csvSeparator)
void setCustomCsvQuery ( $query)
void setCustomQuery ($query $query)
void setCustomSourceItems ( $items)
void setExtraLinkParams (array $params)
void setFieldCasting ( $casting)
void setFieldFormatting ( $formatting)
void setFieldListCsv ( $fields)
void setHighlightConditions ( $conditions)
void setPageSize ( $pageSize)
void setPermissions ( $arr)
void setShowPagination ( $bool)
void setTemplate ( $template)
boolean ShowPagination ()
void sourceClass ()
void sourceFilter ()
void sourceItems ()
void SummaryFields ([DataObjectSet $items = null])
void SummaryTitle ()
void Title ()
void TotalCount ()
void Utility ()
Variables
static mixed $url_handlers = array(
'item/$ID' => 'handleItem',
'$Action' => '$Action',
)
(line 266)

Redefinition of:
RequestHandlingData::$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.

Redefined in descendants as:
$actions $actions = array(
'delete' => array(
'label' => 'Delete',
'icon' => 'cms/images/delete.gif',
'class' => 'deletelink'
))
(line 108)
  • var: 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') )
  • access: public

Redefined in descendants as:
$cachedSourceItems $cachedSourceItems (line 28)
  • var: DataObjectSet Prevent {@sourceItems()} from being called multiple times.
  • access: protected
$clickAction $clickAction (line 48)
  • access: protected
array $csvFieldEscape = array(
"\""=>"\"\"",
"\r\n"=>"",
"\r"=>"",
"\n"=>"",
)
(line 160)
  • var:

    Specify custom escape for the fields.

    1.  array("\""=>"\"\"","\r"=>"""\r\n"=>"""\n"=>"")

  • access: public
mixed $csvFieldFormatting = array() (line 214)
  • access: public
mixed $csvHasHeader = true (line 151)
  • access: protected
mixed $csvSeparator = "," (line 146)

Character to seperate exported columns in the CSV file

  • access: protected
$customCsvQuery $customCsvQuery (line 133)
  • var: Query for CSV-export (might need different fields or further filtering)
  • access: protected
$customQuery $customQuery (line 128)
  • var: 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"
  • access: protected
$customSourceItems $customSourceItems (line 141)
  • var: 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.
  • access: protected
$defaultAction $defaultAction = '' (line 120)
  • var: String Action being executed when clicking on table-row (defaults to "show"). Mostly needed in ComplexTableField-subclass.
  • access: public

Redefined in descendants as:
string $exportButtonLabel = 'Export as CSV' (line 219)
  • access: public
array $extraLinkParams (line 230)
  • access: protected
array $fieldCasting = array() (line 205)
  • var: Specify castings with fieldname as the key, and the desired casting as value. Example: array("MyCustomDate"=>"Date","MyShortText"=>"Text->FirstSentence")
  • access: public
array $fieldFormatting = array() (line 212)
  • var: 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" => '<a href=\"custom-admin/$ID\">$ID</a>'
  • access: public
mixed $fieldList (line 38)
  • access: protected

Redefined in descendants as:
$fieldListCsv $fieldListCsv (line 43)
  • var: array
  • access: protected
string $groupByField = null (line 225)
  • var: Used to group by a specific column in the DataObject and create partial summaries.
  • access: public
array $highlightConditions = array() (line 199)
  • var:

    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" ) )

  • access: public
bool $IsReadOnly (line 53)
  • access: public
bool $Markable (line 80)
  • var: Do we use checkboxes to mark records, or delete them one by one?
  • access: public
mixed $MarkableTitle = null (line 82)
  • access: public
mixed $methodName (line 58)

Called method (needs to be retained for AddMode())

  • access: protected
int $pageSize = 10 (line 181)
  • var: Number of items to show on a single page (needed for pagination)
  • access: protected

Redefined in descendants as:
$permissions $permissions = array(
//"print",
//"export",
"delete"
)
(line 93)
  • var: array Influence output without having to subclass the template. See $actions for adding your custom actions/permissions.
  • access: protected

Redefined in descendants as:
$readOnly $readOnly (line 87)
  • var: boolean Deprecated, please use $permssions instead
  • access: protected
boolean $showPagination = false (line 176)
  • var: Trigger pagination
  • access: protected

Redefined in descendants as:
mixed $sourceClass (line 30)
  • access: protected

Redefined in descendants as:
mixed $sourceFilter = "" (line 32)
  • access: protected

Redefined in descendants as:
mixed $sourceJoin = array() (line 36)
  • access: protected

Redefined in descendants as:
mixed $sourceSort = "" (line 34)
  • access: protected

Redefined in descendants as:
$summaryFieldList $summaryFieldList (line 64)
  • var: array Shows a row which summarizes the contents of a column by a predefined Javascript-function
  • access: protected
$summaryTitle $summaryTitle (line 70)
  • var: 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.
  • access: protected
$template $template = "TableListField" (line 75)
  • var: string Template-Overrides
  • access: protected

Redefined in descendants as:
int $totalCount (line 171)
  • var: Shows total count regardless or pagination
  • access: protected
mixed $__cachedQuery (line 232)
  • access: protected

Inherited Variables

Inherited from FormField

FormField::$containerFieldSet
FormField::$description
FormField::$disabled
FormField::$dontEscape
FormField::$extraClass
FormField::$extraClasses
FormField::$form
FormField::$leftTitle
FormField::$message
FormField::$messageType
FormField::$name
FormField::$readonly
FormField::$rightTitle
FormField::$tabIndex
FormField::$title
FormField::$value

Inherited from RequestHandlingData

RequestHandlingData::$allowed_actions
RequestHandlingData::$request

Inherited from ViewableData

ViewableData::$casting
ViewableData::$castingHelperPair_cache
ViewableData::$customisedObj
ViewableData::$failover
ViewableData::$iteratorPos
ViewableData::$iteratorTotalItems
ViewableData::$namedAs
ViewableData::$parent
ViewableData::$_natural_cache
ViewableData::$_object_cache
ViewableData::$_xml_cache

Inherited from Object

Object::$builtInMethods
Object::$class
Object::$classConstructed
Object::$extensions
Object::$extension_instances
Object::$extraMethods
Object::$extraStatics
Object::$statics
Object::$static_cached
Methods
static method permissions_for_object (line 1123)

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.

  • todo: Temporary method, implement directly in FormField subclasses with object-level permissions.
  • access: public
static array permissions_for_object (string $class, [numeric $id = null])
  • string $class
  • numeric $id
Constructor __construct (line 234)
TableListField __construct ( $name,  $sourceClass, [ $fieldList = null], [ $sourceFilter = null], [ $sourceSort = null], [ $sourceJoin = null])
  • $name
  • $sourceClass
  • $fieldList
  • $sourceFilter
  • $sourceSort
  • $sourceJoin

Redefinition of:
FormField::__construct()
Create a new field.

Redefined in descendants as:
Actions (line 356)

Dummy function to get number of actions originally generated in TableListField_Item.

DataObjectSet Actions ()
addSummary (line 565)

Can utilize some built-in summary-functions, with optional casting.

Currently supported:

  • sum
  • avg

void addSummary ($summaryTitle $summaryTitle, $summaryFields $summaryFieldList)
  • $summaryTitle $summaryTitle: string
  • $summaryFields $summaryFieldList: array Simple Format: array("MyFieldName"=>"sum") With Casting: array("MyFieldname"=>array("sum","Currency->Nice"))
ajax_refresh (line 1027)

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.
void ajax_refresh ()
BaseLink (line 1096)
void BaseLink ()
Can (line 679)

Template accessor for Permissions

void Can ( $mode)
  • $mode
colFunction_avg (line 665)
void colFunction_avg ( $values)
  • $values
colFunction_sum (line 661)
void colFunction_sum ( $values)
  • $values
CurrentLink (line 1083)
void CurrentLink ()
delete (line 529)
String delete ()

Redefined in descendants as:
export (line 897)

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}.

  • todo: Make relation-syntax available (at the moment you'll have to use custom sql)
void export ()
ExportLink (line 964)

We need to instanciate this button manually as a normal button has no means of adding inline onclick-behaviour.

void ExportLink ()
FieldHolder (line 279)
void FieldHolder ()

Redefinition of:
FormField::FieldHolder()
Returns a "Field Holder" for this field - used by templates.

Redefined in descendants as:
FieldList (line 494)
void FieldList ()

Redefined in descendants as:
filterString (line 855)

Compile all request-parameters for search and pagination (except the actual list-positions) as a query-string.

  • return: URL-parameters
String filterString ()
FirstItem (line 800)
void FirstItem ()
FirstLink (line 750)
void FirstLink ()
getCastedValue (line 1139)
void getCastedValue ($value $value,  $castingDefinition)
  • $value $value
  • $castingDefinition
getCsvQuery (line 470)
void getCsvQuery ()
getCsvSeparator (line 880)

Get the CSV separator character. Defaults to ,

void getCsvSeparator ()
getExtraLinkParams (line 746)
array getExtraLinkParams ()
getPermissions (line 699)
array getPermissions ()
getQuery (line 440)

Generates the query for sourceitems (without pagination/limit-clause)

string getQuery ()

Redefined in descendants as:
GroupedItems (line 635)
void GroupedItems ()
handleItem (line 275)
void handleItem ( $request)
  • $request

Redefined in descendants as:
HasGroupedItems (line 631)
void HasGroupedItems ()
HasSummary (line 575)
void HasSummary ()
Headings (line 296)
void Headings ()

Redefined in descendants as:
index (line 262)
void index ()
isFieldSortable (line 335)

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).

bool isFieldSortable (string $fieldName)
  • string $fieldName
Items (line 426)
void Items ()

Redefined in descendants as:
LastItem (line 804)
void LastItem ()
LastLink (line 787)
void LastLink ()
ListStart (line 730)
void ListStart ()
Name (line 1053)
String Name ()

Redefinition of:
FormField::Name()
Returns the field name - used by templates.
NamePlural (line 1073)
void NamePlural ()
NameSingular (line 1067)
void NameSingular ()
NextLink (line 776)
void NextLink ()
PageSize (line 726)
void PageSize ()
performReadonlyTransformation (line 512)
void performReadonlyTransformation ()

Redefinition of:
FormField::performReadonlyTransformation()
Returns a readonly version of this field

Redefined in descendants as:
PrevLink (line 761)
void PrevLink ()
printall (line 971)
void printall ()
PrintLink (line 992)
void PrintLink ()
removeCsvHeader (line 887)

Remove the header row from the CSV export

void removeCsvHeader ()
removeSummary (line 570)
void removeSummary ()
setClick_AjaxLoad (line 501)

Configure this table to load content into a subform via ajax

void setClick_AjaxLoad ( $urlBase,  $formID)
  • $urlBase
  • $formID
setClick_PopupLoad (line 508)

Configure this table to open a popup window

void setClick_PopupLoad ( $urlBase)
  • $urlBase
setCSVFieldFormatting (line 1046)
void setCSVFieldFormatting ( $formatting)
  • $formatting
setCsvSeparator (line 873)

Set the CSV separator character. Defaults to ,

void setCsvSeparator ( $csvSeparator)
  • $csvSeparator
setCustomCsvQuery (line 379)
void setCustomCsvQuery ( $query)
  • $query
setCustomQuery (line 375)

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).

void setCustomQuery ($query $query)
  • $query $query: Query
setCustomSourceItems (line 383)
void setCustomSourceItems ( $items)
  • $items
setExtraLinkParams (line 738)
  • deprecated: Put the query string onto your form's link instead :-)
void setExtraLinkParams (array $params)
  • array $params
setFieldCasting (line 1038)
void setFieldCasting ( $casting)
  • $casting
setFieldFormatting (line 1042)
void setFieldFormatting ( $formatting)
  • $formatting
setFieldListCsv (line 866)

#################################

CSV Export #################################

void setFieldListCsv ( $fields)
  • $fields
setHighlightConditions (line 1167)

#########################

Highlighting #########################

void setHighlightConditions ( $conditions)
  • $conditions
setPageSize (line 722)
void setPageSize ( $pageSize)
  • $pageSize
setPermissions (line 692)
void setPermissions ( $arr)
  • $arr
setShowPagination (line 708)

#################################

Pagination #################################

void setShowPagination ( $bool)
  • $bool
setTemplate (line 1079)
void setTemplate ( $template)
  • $template
ShowPagination (line 715)
boolean ShowPagination ()
sourceClass (line 271)
void sourceClass ()

Redefined in descendants as:
sourceFilter (line 258)

Get the filter

void sourceFilter ()

Redefined in descendants as:
sourceID (line 1104)
Int sourceID ()

Redefined in descendants as:
sourceItems (line 387)
void sourceItems ()

Redefined in descendants as:
SummaryFields (line 587)
void SummaryFields ([DataObjectSet $items = null])
  • DataObjectSet $items: Only used to pass grouped sourceItems for creating partial summaries.
SummaryTitle (line 579)
void SummaryTitle ()
Title (line 1057)
void Title ()

Redefinition of:
FormField::Title()
Returns the field label - used by templates.

Redefined in descendants as:
TotalCount (line 812)
void TotalCount ()
Utility (line 1005)

#################################

Utilty #################################

void Utility ()

Inherited Methods

Inherited From FormField

FormField::__construct()
FormField::addExtraClass()
FormField::attrName()
FormField::attrTitle()
FormField::attrValue()
FormField::createTag()
FormField::dataValue()
FormField::debug()
FormField::describe()
FormField::extraClass()
FormField::Field()
FormField::FieldHolder()
FormField::forTemplate()
FormField::getForm()
FormField::getTabIndex()
FormField::getTabIndexHTML()
FormField::hasClass()
FormField::hasData()
FormField::id()
FormField::isComposite()
FormField::isDisabled()
FormField::isReadonly()
FormField::jsValidation()
FormField::LeftTitle()
FormField::Link()
FormField::Message()
FormField::MessageType()
FormField::Name()
FormField::name_to_label()
FormField::performDisabledTransformation()
FormField::performReadonlyTransformation()
FormField::removeExtraClass()
FormField::Required()
FormField::RightTitle()
FormField::rootFieldSet()
FormField::saveInto()
FormField::setContainerFieldSet()
FormField::setDisabled()
FormField::setError()
FormField::setForm()
FormField::setLeftTitle()
FormField::setName()
FormField::setReadonly()
FormField::setRightTitle()
FormField::setTabIndex()
FormField::setTitle()
FormField::setValue()
FormField::SmallFieldHolder()
FormField::Title()
FormField::transform()
FormField::Type()
FormField::validate()
FormField::Value()

Inherited From RequestHandlingData

RequestHandlingData::checkAccessAction()
RequestHandlingData::getRequest()
RequestHandlingData::handleRequest()
RequestHandlingData::httpError()

Inherited From ViewableData

ViewableData::ATT_val()