+
+#### FormField wrapper containers suffixed with `_Holder`
+
+Previously both the container div and FormField tag shared the same ID in
+certain cases. Now, the wrapper div in the default `FormField` template will be
+suffixed with `_Holder`.
+
+ Before:
+
+
+
+ After:
+
+
+#### Reverting to the old specification
+
+If upgrading existing forms is not feasible, developers can opt out of the new
+specifications by using the `FormTemplateHelper_Pre32` class rules instead of
+the default ones.
+
+ :::yaml
+ # mysite/config/_config.yml
+
+ Injector:
+ FormTemplateHelper:
+ class: FormTemplateHelper_Pre32
diff --git a/docs/en/reference/complextablefield.md b/docs/en/reference/complextablefield.md
deleted file mode 100644
index e9def0cfc..000000000
--- a/docs/en/reference/complextablefield.md
+++ /dev/null
@@ -1,135 +0,0 @@
-# Complex Table Field
-
-## Introduction
-
-
- This field is deprecated in favour of the new [GridField](/reference/grid-field) API.
-
-
-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
-
-`[api: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 FieldList(
- 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 `[api: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.
-
-`[api:ComplexTableField]` gives you several options to do this. You can either
-
-* Pass a FieldList in the constructor.
-* Pass a String in the constructor.
-
-The first will simply add the fieldlist 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 FieldList) 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, `[api: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 FieldList(
- 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 `[api: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
\ No newline at end of file
diff --git a/docs/en/reference/index.md b/docs/en/reference/index.md
index f9fa9d162..002241d7d 100644
--- a/docs/en/reference/index.md
+++ b/docs/en/reference/index.md
@@ -3,8 +3,7 @@
Reference articles complement our auto-generated [API docs](http://api.silverstripe.org) in providing deeper introduction into a specific API.
* [BBCode](bbcode): Extensible shortcode syntax
-* [CMS Architecture](cms-architecture): A quick run down to get you started with creating your own data management interface
-* [ComplexTableField](complextablefield): Manage records and their relations inside the CMS
+* [CMS Architecture](cms-architecture): A quick run down to get you started with creating your own data management interface.
* [GridField](grid-field): The GridField is a flexible form field for creating tables of data.
* [Database Structure](database-structure): Conventions and best practices for database tables and fields
* [DataExtension](dataextension): A "mixin" system allowing to extend core classes
diff --git a/docs/en/reference/tablefield.md b/docs/en/reference/tablefield.md
index c71580984..8069e321c 100644
--- a/docs/en/reference/tablefield.md
+++ b/docs/en/reference/tablefield.md
@@ -63,12 +63,6 @@ Due to the nested nature of this fields dataset, you can't set any required colu
Note: You still have to attach some form of `[api:Validator]` to the form to trigger any validation on this field.
-### Nested Table Fields
-
-When you have `[api:TableField]` inside a `[api:ComplexTableField]`, the parent ID may not be known in your
-getCMSFields() method. In these cases, you can set a value to '$RecordID' in your `[api:TableField]` extra data, and this
-will be populated with the newly created record id upon save.
-
## Known Issues
* A `[api:TableField]` doesn't reload any submitted form-data if the saving is interrupted by a failed validation. After
diff --git a/docs/en/topics/javascript.md b/docs/en/topics/javascript.md
index ff1a3cd25..054c57f81 100644
--- a/docs/en/topics/javascript.md
+++ b/docs/en/topics/javascript.md
@@ -289,14 +289,12 @@ request](http://docs.jquery.com/Frequently_Asked_Questions#Why_do_my_events_stop
### Assume Element Collections
jQuery is based around collections of DOM elements, the library functions typically handle multiple elements (where it
-makes sense). Encapsulate your code by nesting your jQuery commands inside a `jQuery().each()` call.
-
-Example: ComplexTableField implements a paginated table with a pop-up for displaying
+makes sense). Encapsulate your code by nesting your jQuery commands inside a `jQuery().each()` call. Example:
:::js
- $('div.ComplexTableField').each(function() {
- // This is the over code for the tr elements inside a ComplexTableField.
- $(this).find('tr').hover(
+ $('.MyCustomField').each(function() {
+ // This is the over code for the elements inside a MyCustomField.
+ $(this).hover(
// ...
);
});
diff --git a/forms/Form.php b/forms/Form.php
index b42e31797..0a702f138 100644
--- a/forms/Form.php
+++ b/forms/Form.php
@@ -149,6 +149,21 @@ class Form extends RequestHandler {
*/
protected $attributes = array();
+ /**
+ * @var FormTemplateHelper
+ */
+ private $templateHelper = null;
+
+ /**
+ * @ignore
+ */
+ private $htmlID = null;
+
+ /**
+ * @ignore
+ */
+ private $formActionPath = false;
+
/**
* Create a new form, with the given fields an action buttons.
*
@@ -639,13 +654,14 @@ class Form extends RequestHandler {
public function getAttributes() {
$attrs = array(
- 'id' => $this->FormName(),
+ 'id' => $this->getTemplateHelper()->generateFormID($this),
'action' => $this->FormAction(),
'method' => $this->FormMethod(),
'enctype' => $this->getEncType(),
'target' => $this->target,
'class' => $this->extraClass(),
);
+
if($this->validator && $this->validator->getErrors()) {
if(!isset($attrs['class'])) $attrs['class'] = '';
$attrs['class'] .= ' validationerror';
@@ -668,6 +684,7 @@ class Form extends RequestHandler {
if(!$attrs || is_string($attrs)) $attrs = $this->getAttributes();
+
// Figure out if we can cache this form
// - forms with validation shouldn't be cached, cos their error messages won't be shown
// - forms with security tokens shouldn't be cached because security tokens expire
@@ -708,13 +725,43 @@ class Form extends RequestHandler {
}
/**
- * Set the target of this form to any value - useful for opening the form contents in a new window or refreshing
- * another frame
- *
- * @param target The value of the target
- */
+ * Set the {@link FormTemplateHelper}
+ *
+ * @param string|FormTemplateHelper
+ */
+ public function setTemplateHelper($helper) {
+ $this->templateHelper = $helper;
+ }
+
+ /**
+ * Return a {@link FormTemplateHelper} for this form. If one has not been
+ * set, return the default helper.
+ *
+ * @return FormTemplateHelper
+ */
+ public function getTemplateHelper() {
+ if($this->templateHelper) {
+ if(is_string($this->templateHelper)) {
+ return Injector::inst()->get($this->templateHelper);
+ }
+
+ return $this->templateHelper;
+ }
+
+ return Injector::inst()->get('FormTemplateHelper');
+ }
+
+ /**
+ * Set the target of this form to any value - useful for opening the form
+ * contents in a new window or refreshing another frame.
+ *
+ * @param target $target The value of the target
+ *
+ * @return FormField
+ */
public function setTarget($target) {
$this->target = $target;
+
return $this;
}
@@ -864,50 +911,67 @@ class Form extends RequestHandler {
}
}
- /** @ignore */
- private $formActionPath = false;
-
/**
* Set the form action attribute to a custom URL.
*
- * Note: For "normal" forms, you shouldn't need to use this method. It is recommended only for situations where
- * you have two relatively distinct parts of the system trying to communicate via a form post.
+ * Note: For "normal" forms, you shouldn't need to use this method. It is
+ * recommended only for situations where you have two relatively distinct
+ * parts of the system trying to communicate via a form post.
+ *
+ * @param string
+ *
+ * @return Form
*/
public function setFormAction($path) {
$this->formActionPath = $path;
+
return $this;
}
/**
- * @ignore
- */
- private $htmlID = null;
-
- /**
- * Returns the name of the form
+ * Returns the name of the form.
+ *
+ * @return string
*/
public function FormName() {
- if($this->htmlID) return $this->htmlID;
- else return $this->class . '_' . str_replace(array('.', '/'), '', $this->name);
+ return $this->getTemplateHelper()->generateFormID($this);
}
/**
- * Set the HTML ID attribute of the form
+ * Set the HTML ID attribute of the form.
+ *
+ * @param string $id
+ *
+ * @return FormField
*/
public function setHTMLID($id) {
$this->htmlID = $id;
+
+ return $this;
+ }
+
+ /**
+ * @return string
+ */
+ public function getHTMLID() {
+ return $this->htmlID;
}
/**
* Returns this form's controller.
- * This is used in the templates.
+ *
+ * @return Controller
+ * @deprecated 4.0
*/
public function Controller() {
+ Deprecation::notice('4.0', 'Use getController() rather than Controller() to access controller');
+
return $this->getController();
}
/**
* Get the controller.
+ *
* @return Controller
*/
public function getController() {
@@ -916,16 +980,19 @@ class Form extends RequestHandler {
/**
* Set the controller.
+ *
* @param Controller $controller
* @return Form
*/
public function setController($controller) {
$this->controller = $controller;
+
return $this;
}
/**
* Get the name of the form.
+ *
* @return string
*/
public function getName() {
@@ -934,32 +1001,37 @@ class Form extends RequestHandler {
/**
* Set the name of the form.
+ *
* @param string $name
* @return Form
*/
public function setName($name) {
$this->name = $name;
+
return $this;
}
/**
- * Returns an object where there is a method with the same name as each data field on the form.
+ * Returns an object where there is a method with the same name as each data
+ * field on the form.
+ *
* That method will return the field itself.
- * It means that you can execute $firstNameField = $form->FieldMap()->FirstName(), which can be handy
+ *
+ * It means that you can execute $firstName = $form->FieldMap()->FirstName()
*/
public function FieldMap() {
return new Form_FieldMap($this);
}
/**
- * The next functions store and modify the forms
- * message attributes. messages are stored in session under
- * $_SESSION[formname][message];
+ * The next functions store and modify the forms message attributes.
+ * messages are stored in session under $_SESSION[formname][message];
*
* @return string
*/
public function Message() {
$this->getMessageFromSession();
+
return $this->message;
}
@@ -968,16 +1040,17 @@ class Form extends RequestHandler {
*/
public function MessageType() {
$this->getMessageFromSession();
+
return $this->messageType;
}
protected function getMessageFromSession() {
if($this->message || $this->messageType) {
return $this->message;
- }else{
- $this->message = Session::get("FormInfo.{$this->FormName()}.formError.message");
- $this->messageType = Session::get("FormInfo.{$this->FormName()}.formError.type");
}
+
+ $this->message = Session::get("FormInfo.{$this->FormName()}.formError.message");
+ $this->messageType = Session::get("FormInfo.{$this->FormName()}.formError.type");
}
/**
@@ -1014,6 +1087,7 @@ class Form extends RequestHandler {
Session::clear("FormInfo.{$this->FormName()}.formError");
Session::clear("FormInfo.{$this->FormName()}.data");
}
+
public function resetValidation() {
Session::clear("FormInfo.{$this->FormName()}.errors");
Session::clear("FormInfo.{$this->FormName()}.data");
@@ -1041,26 +1115,32 @@ class Form extends RequestHandler {
/**
* Processing that occurs before a form is executed.
+ *
* This includes form validation, if it fails, we redirect back
* to the form with appropriate error messages.
+ *
* Triggered through {@link httpSubmission()}.
+ *
* Note that CSRF protection takes place in {@link httpSubmission()},
* if it fails the form data will never reach this method.
*
* @return boolean
*/
- public function validate(){
- if($this->validator){
+ public function validate() {
+ if($this->validator) {
$errors = $this->validator->validate();
- if($errors){
+ if($errors) {
// Load errors into session and post back
$data = $this->getData();
+
Session::set("FormInfo.{$this->FormName()}.errors", $errors);
Session::set("FormInfo.{$this->FormName()}.data", $data);
+
return false;
}
}
+
return true;
}
@@ -1070,6 +1150,7 @@ class Form extends RequestHandler {
/**
* Load data from the given DataObject or array.
+ *
* It will call $object->MyField to get the value of MyField.
* If you passed an array, it will call $object[MyField].
* Doesn't save into dataless FormFields ({@link DatalessField}),
@@ -1079,15 +1160,19 @@ class Form extends RequestHandler {
* its value will not be saved to the field, retaining
* potential existing values.
*
- * Passed data should not be escaped, and is saved to the FormField instances unescaped.
- * Escaping happens automatically on saving the data through {@link saveInto()}.
+ * Passed data should not be escaped, and is saved to the FormField
+ * instances unescaped.
+ *
+ * Escaping happens automatically on saving the data through
+ * {@link saveInto()}.
*
* @uses FieldList->dataFields()
* @uses FormField->setValue()
*
* @param array|DataObject $data
* @param int $mergeStrategy
- * For every field, {@link $data} is interogated whether it contains a relevant property/key, and
+ * For every field, {@link $data} is interogated whether it contains a
+ * relevant property/key, and
* what that property/key's value is.
*
* By default, if {@link $data} does contain a property/key, the fields value is always replaced by {@link $data}'s
@@ -1218,11 +1303,11 @@ class Form extends RequestHandler {
/**
* Get the submitted data from this form through
- * {@link FieldList->dataFields()}, which filters out
- * any form-specific data like form-actions.
- * Calls {@link FormField->dataValue()} on each field,
- * which returns a value suitable for insertion into a DataObject
- * property.
+ * {@link FieldList->dataFields()}, which filters out any form-specific data
+ * like form-actions.
+ *
+ * Calls {@link FormField->dataValue()} on each field, which returns a value
+ * suitable for insertion into a DataObject property.
*
* @return array
*/
@@ -1230,20 +1315,23 @@ class Form extends RequestHandler {
$dataFields = $this->fields->dataFields();
$data = array();
- if($dataFields){
+ if($dataFields) {
foreach($dataFields as $field) {
if($field->getName()) {
$data[$field->getName()] = $field->dataValue();
}
}
}
+
return $data;
}
/**
* Call the given method on the given field.
- * This is used by Ajax-savvy form fields. By putting '&action=callfieldmethod' to the end
- * of the form action, they can access server-side data.
+ *
+ * This is used by Ajax-savvy form fields. By putting '&action=callfieldmethod'
+ * to the end of the form action, they can access server-side data.
+ *
* @param fieldName The name of the field. Can be overridden by $_REQUEST[fieldName]
* @param methodName The name of the field. Can be overridden by $_REQUEST[methodName]
*/
@@ -1276,6 +1364,8 @@ class Form extends RequestHandler {
*
* This is returned when you access a form as $FormObject rather
* than <% with FormObject %>
+ *
+ * @return HTML
*/
public function forTemplate() {
$return = $this->renderWith(array_merge(
@@ -1291,7 +1381,11 @@ class Form extends RequestHandler {
/**
* Return a rendered version of this form, suitable for ajax post-back.
- * It triggers slightly different behaviour, such as disabling the rewriting of # links
+ *
+ * It triggers slightly different behaviour, such as disabling the rewriting
+ * of # links.
+ *
+ * @return HTML
*/
public function forAjaxTemplate() {
$view = new SSViewer(array(
@@ -1304,8 +1398,12 @@ class Form extends RequestHandler {
/**
* Returns an HTML rendition of this form, without the