API CHANGE Deprecated TableListField and ComplexTableField, use GridField instead

docs/en/changelogs/3.0.0.md

@@ -13,6 +13,45 @@
 
 ## Upgrading ##
 
+### GridField: Replacement for TableListField and ComplexTableField ###
+
+We have a new component for managing lists of objects: The `[GridField](/topics/grid-field)`.
+It's a substantial rewrite of the features previously captured by `TableListField`,
+`ComplexTableField`, `HasManyComplexTableField` and `ManyManyComplexTableField`.
+
+The legacy fields remain operational for now, although a switch to `GridField` is strongly encouraged,
+for stability, interface and performance reasons. The `HasManyComplexTableField` and `ManyManyComplexTableField`
+are no longer maintained, for those you do have to make the switch.
+
+Upgrade example: Record listing
+
+	:::php
+	// before
+	$field = new TableListField('Companies', 'Company');
+	$field->setPageSize(20);
+	// after
+	$field = new GridField('Companies', null, DataList::create('Company'));
+	$field->getConfig()->getComponentByType('GridFieldPaginator')->setItemsPerPage(20);
+
+Upgrade example: Record listing with view/edit interface
+
+	:::php
+	// before
+	$field = new ComplexTableField($myController, 'Companies', 'Company');
+	// after
+	$field = new GridField('Companies', null, DataList::create('Company'), GridFieldConfig_RecordEditor::create());
+
+
+Upgrade example: Relationship editing
+
+	:::php
+	// before
+	$field = new HasManyComplexTableField($myController, 'MyRelation', 'MyRelationObject');
+	// after
+	$field = new GridField('MyRelation', null, $myRecord->MyRelation(), GridFieldConfig_RelationEditor::create());
+
+More information is available in the [GridField documentation](/topics/grid-field).
+
 ### New template engine ###
 
 The template engine has been completely rewritten, and although it is generally backward compatible, there are new features

forms/ComplexTableField.php

@@ -19,12 +19,9 @@
  *  - methodName				Method on the formfield (e.g. "ComplexTableField")
  *  - childID				Identifier of the database-record (the targeted table is determined by the $sourceClass parameter)
  *  
- * @todo Find a less fragile solution for accessing this field through the main controller and ReferencedField, e.g.
+ * @deprecated 3.0 Use GridField with GridFieldConfig_RecordEditor
- *      build a seperate CTF-instance (doesn't necessarly have to be connected to the original by ReferencedField)
+ *
  * @todo Control width/height of popup by constructor (hardcoded at the moment)
- * @todo Integrate search from MemberTableField.php
- * @todo Less performance-hungry implementation of detail-view paging (don't return all items on a single view)
- * @todo Use automatic has-many and many-many functions to return a ComponentSet rather than building the join manually
  * @package forms
  * @subpackage fields-relational
  */

forms/TableField.php

@@ -10,16 +10,6 @@
  * A TableField-instance should never be saved twice without reloading, because otherwise it 
  * can't determine if a field is new (=create) or existing (=update), and will produce duplicates.
  * 
- * @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 $fieldTypes array An array of field types of fieldname => fieldType (eg. formfield). Do not use for extra data/hiddenfields.
- * @param $filterField string The field to filter by.  Give the filter value in $sourceFilter.  The value will automatically be set on new records.
- * @param $sourceFilter string If $filterField has a value, then this is the value to filter by.  Otherwise, it is a SQL filter expression.
- * @param $editExisting boolean (Note: Has to stay on this position for legacy reasons)
- * @param $sourceSort string
- * @param $sourceJoin string
- * 
  * @todo We should refactor this to support a single FieldList instead of evaluated Strings for building FormFields
  * 
  * @package forms
@@ -92,10 +82,15 @@ class TableField extends TableListField {
 	public $showAddRow = true;
 	
 	/**
-	 * Automatically detect a has-one relationship
+	 * @param $name string The fieldname
-	 * in the popup (=child-class) and save the relation ID.
+	 * @param $sourceClass string The source class of this field
-	 *
+	 * @param $fieldList array An array of field headings of Fieldname => Heading Text (eg. heading1)
-	 * @var boolean
+	 * @param $fieldTypes array An array of field types of fieldname => fieldType (eg. formfield). Do not use for extra data/hiddenfields.
+	 * @param $filterField string The field to filter by.  Give the filter value in $sourceFilter.  The value will automatically be set on new records.
+	 * @param $sourceFilter string If $filterField has a value, then this is the value to filter by.  Otherwise, it is a SQL filter expression.
+	 * @param $editExisting boolean (Note: Has to stay on this position for legacy reasons)
+	 * @param $sourceSort string
+	 * @param $sourceJoin string
 	 */
 	function __construct($name, $sourceClass, $fieldList = null, $fieldTypes, $filterField = null, 
 						$sourceFilter = null, $editExisting = true, $sourceSort = null, $sourceJoin = null) {

forms/TableListField.php

@@ -11,12 +11,8 @@
  * All get variables are namespaced in the format ctf[MyFieldName][MyParameter] to avoid collisions
  * when multiple TableListFields are present in a form.
  * 
- * @param $name string The fieldname
+ * @deprecated 3.0 Use GridField with GridFieldConfig_RecordEditor
- * @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
  * @package forms
  * @subpackage fields-relational
  */
@@ -231,6 +227,14 @@ class TableListField extends FormField {
 	 */
 	private $getDataListFromForm;
 	
+	/**
+	 * @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
+	 */
 	function __construct($name, $sourceClass = null, $fieldList = null, $sourceFilter = null, 
 		$sourceSort = null, $sourceJoin = null) {