Code formatting

forms/Form.php

@@ -915,6 +915,10 @@ class Form extends RequestHandler {
 	 * 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;
@@ -953,14 +957,19 @@ class Form extends RequestHandler {
 	
 	/**
 	 * 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() {
@@ -969,16 +978,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() {
@@ -987,32 +999,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
+	 * The next functions store and modify the forms message attributes. 
-	 * message attributes. messages are stored in session under
+	 * messages are stored in session under $_SESSION[formname][message];
-	 * $_SESSION[formname][message];
 	 * 
 	 * @return string
 	 */
 	public function Message() {
 		$this->getMessageFromSession();
+
 		return $this->message;
 	}
 	
@@ -1021,16 +1038,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");
 	}
 
 	/**
@@ -1067,6 +1085,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");
@@ -1094,26 +1113,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(){
+	public function validate() {
-		if($this->validator){
+		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;
 	}
 
@@ -1123,6 +1148,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}),
@@ -1132,15 +1158,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.
+	 * Passed data should not be escaped, and is saved to the FormField 
-	 * Escaping happens automatically on saving the data through {@link saveInto()}.
+	 * 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
@@ -1271,11 +1301,11 @@ class Form extends RequestHandler {
 	
 	/**
 	 * Get the submitted data from this form through
-	 * {@link FieldList->dataFields()}, which filters out
+	 * {@link FieldList->dataFields()}, which filters out any form-specific data 
-	 * any form-specific data like form-actions.
+	 * like form-actions.
-	 * Calls {@link FormField->dataValue()} on each field,
+	 * 
-	 * which returns a value suitable for insertion into a DataObject
+	 * Calls {@link FormField->dataValue()} on each field, which returns a value 
-	 * property.
+	 * suitable for insertion into a DataObject property.
 	 * 
 	 * @return array
 	 */
@@ -1283,20 +1313,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]
 	 */
@@ -1329,6 +1362,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(
@@ -1344,7 +1379,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(
@@ -1357,8 +1396,12 @@ class Form extends RequestHandler {
 
 	/**
 	 * Returns an HTML rendition of this form, without the <form> tag itself.
-	 * Attaches 3 extra hidden files, _form_action, _form_name, _form_method, and _form_enctype.  These are
+	 *
-	 * the attributes of the form.  These fields can be used to send the form to Ajax.
+	 * Attaches 3 extra hidden files, _form_action, _form_name, _form_method, 
+	 * and _form_enctype.  These are the attributes of the form.  These fields 
+	 * can be used to send the form to Ajax.
+	 *
+	 * @return HTML
 	 */
 	public function formHtmlContent() {
 		$this->IncludeFormTag = false;
@@ -1375,77 +1418,115 @@ class Form extends RequestHandler {
 	}
 
 	/**
-	 * Render this form using the given template, and return the result as a string
+	 * Render this form using the given template, and return the result as a 
-	 * You can pass either an SSViewer or a template name
+	 * string.
+	 *
+	 * You can pass either an SSViewer or a template name.
+	 *
+	 * @param SSViewer|string $template
+	 *
+	 * @return HTML
 	 */
 	public function renderWithoutActionButton($template) {
 		$custom = $this->customise(array(
 			"Actions" => "",
 		));
 
-		if(is_string($template)) $template = new SSViewer($template);
+		if(is_string($template)) {
+			$template = new SSViewer($template);
+		}
+
 		return $template->process($custom);
 	}
 
 
 	/**
-	 * Sets the button that was clicked.  This should only be called by the Controller.
+	 * Sets the button that was clicked.  This should only be called by the 
-	 * @param funcName The name of the action method that will be called.
+	 * {@link Controller}
+	 *
+	 * @param string $funcName The name of the action method that will be called
+	 *
+	 * @return Form
 	 */
 	public function setButtonClicked($funcName) {
 		$this->buttonClickedFunc = $funcName;
+
 		return $this;
 	}
 
+	/**
+	 * @return FormAction
+	 */
 	public function buttonClicked() {
 		foreach($this->actions as $action) {
-			if($this->buttonClickedFunc == $action->actionName()) return $action;
+			if($this->buttonClickedFunc == $action->actionName()) {
+				return $action;
+			}
 		}
 	}
 
 	/**
-	 * Return the default button that should be clicked when another one isn't available
+	 * Return the default button that should be clicked when another one isn't 
+	 * available.
+	 *
+	 * @return FormAction
 	 */
 	public function defaultAction() {
-		if($this->hasDefaultAction && $this->actions)
+		if($this->hasDefaultAction && $this->actions) {
 			return $this->actions->First();
+		}
 	}
 
 	/**
 	 * Disable the default button.
-	 * Ordinarily, when a form is processed and no action_XXX button is available, then the first button in the
+	 *
-	 * actions list will be pressed.  However, if this is "delete", for example, this isn't such a good idea.
+	 * Ordinarily, when a form is processed and no action_XXX button is 
+	 * available, then the first button in the actions list will be pressed. 
+	 * However, if this is "delete", for example, this isn't such a good idea.
+	 *
+	 * @return Form
 	 */
 	public function disableDefaultAction() {
 		$this->hasDefaultAction = false;
+
 		return $this;
 	}
 	
 	/**
-	 * Disable the requirement of a security token on this form instance. This security protects
+	 * Disable the requirement of a security token on this form instance. This 
-	 * against CSRF attacks, but you should disable this if you don't want to tie 
+	 * security protects against CSRF attacks, but you should disable this if 
-	 * a form to a session - eg a search form.
+	 * you don't want to tie a form to a session - eg a search form.
 	 * 
-	 * Check for token state with {@link getSecurityToken()} and {@link SecurityToken->isEnabled()}.
+	 * Check for token state with {@link getSecurityToken()} and 
+	 * {@link SecurityToken->isEnabled()}.
+	 *
+	 * @return Form
 	 */
 	public function disableSecurityToken() {
 		$this->securityToken = new NullSecurityToken();
+
 		return $this;
 	}
 	
 	/**
 	 * Enable {@link SecurityToken} protection for this form instance.
 	 * 
-	 * Check for token state with {@link getSecurityToken()} and {@link SecurityToken->isEnabled()}.
+	 * Check for token state with {@link getSecurityToken()} and 
+	 * {@link SecurityToken->isEnabled()}.
+	 *
+	 * @return Form
 	 */
 	public function enableSecurityToken() {
 		$this->securityToken = new SecurityToken();
+
 		return $this;
 	}
 	
 	/**
 	 * Returns the security token for this form (if any exists).
+	 *
 	 * Doesn't check for {@link securityTokenEnabled()}.
+	 *
 	 * Use {@link SecurityToken::inst()} to get a global token.
 	 * 
 	 * @return SecurityToken|null
@@ -1455,26 +1536,32 @@ class Form extends RequestHandler {
 	}
 		
 	/**
-	 * Returns the name of a field, if that's the only field that the current controller is interested in.
+	 * Returns the name of a field, if that's the only field that the current 
+	 * controller is interested in.
+	 *
 	 * It checks for a call to the callfieldmethod action.
-	 * This is useful for optimising your forms
 	 * 
 	 * @return string
 	 */
 	public static function single_field_required() {
-		if(self::current_action() == 'callfieldmethod') return $_REQUEST['fieldName'];
+		if(self::current_action() == 'callfieldmethod') {
+			return $_REQUEST['fieldName'];
+		}
 	}
 
 	/**
 	 * Return the current form action being called, if available.
-	 * This is useful for optimising your forms
+	 *
+	 * @return string
 	 */
 	public static function current_action() {
 		return self::$current_action;
 	}
 
 	/**
-	 * Set the current form action.  Should only be called by Controller.
+	 * Set the current form action. Should only be called by {@link Controller}.
+	 *
+	 * @param string $action
 	 */
 	public static function set_current_action($action) {
 		self::$current_action = $action;
@@ -1495,6 +1582,8 @@ class Form extends RequestHandler {
 	 *
 	 * @param string $class A string containing a classname or several class
 	 *				names delimited by a single space.
+	 *
+	 * @return Form
 	 */
 	public function addExtraClass($class) {
 		$classes = explode(' ', $class);
@@ -1517,6 +1606,7 @@ class Form extends RequestHandler {
 	public function removeExtraClass($class) {
 		$classes = explode(' ', $class);
 		$this->extraClasses = array_diff($this->extraClasses, $classes);
+
 		return $this;
 	}
 	
@@ -1547,9 +1637,6 @@ class Form extends RequestHandler {
 		$data['action_' . $action] = true;
 
 		return Director::test($this->FormAction(), $data, Controller::curr()->getSession());
-		
-		//$response = $this->controller->run($data);
-		//return $response;
 	}
 	
 	/**
@@ -1568,6 +1655,7 @@ class Form extends RequestHandler {
  * @subpackage core
  */
 class Form_FieldMap extends ViewableData {
+
 	protected $form;
 	
 	public function __construct($form) {
@@ -1576,7 +1664,10 @@ class Form_FieldMap extends ViewableData {
 	}
 	
 	/**
-	 * Ensure that all potential method calls get passed to __call(), therefore to dataFieldByName
+	 * Ensure that all potential method calls get passed to __call(), therefore 
+	 * to dataFieldByName.
+	 *
+	 * @param string
 	 */
 	public function hasMethod($method) {
 		return true;