From 4921173209b9d78686a4f91c1530801c284d82c9 Mon Sep 17 00:00:00 2001 From: Will Rossiter Date: Thu, 30 May 2013 21:06:54 +1200 Subject: [PATCH] Code formatting --- forms/Form.php | 191 ++++++++++++++++++++++++++++++++++++------------- 1 file changed, 141 insertions(+), 50 deletions(-) diff --git a/forms/Form.php b/forms/Form.php index 519980d61..aca3bad49 100644 --- a/forms/Form.php +++ b/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 - * 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; } @@ -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(){ - 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; } @@ -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. - * 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 @@ -1271,11 +1301,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 */ @@ -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
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 - * You can pass either an SSViewer or a template name + * Render this form using the given template, and return the result as a + * 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. - * @param funcName The name of the action method that will be called. + * Sets the button that was clicked. This should only be called by the + * {@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 - * against CSRF attacks, but you should disable this if you don't want to tie - * a form to a session - eg a search form. + * Disable the requirement of a security token on this form instance. This + * security protects against CSRF attacks, but you should disable this if + * 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;