Update and fix PHP docblocks, document spelling mistakes and strip trailing whitespace on Form.php

This commit is contained in:
Stig Lindqvist 2015-06-12 10:28:32 +12:00
parent 04b803dfc6
commit 95860e9229

View File

@ -35,7 +35,7 @@
* "admin/EditForm". This URL will render the form without its surrounding
* template when called through GET instead of POST.
*
* By appending to this URL, you can render invidual form elements
* By appending to this URL, you can render individual form elements
* through the {@link FormField->FieldHolder()} method.
* For example, the "URLSegment" field in a standard CMS form would be
* accessible through "admin/EditForm/field/URLSegment/FieldHolder".
@ -54,8 +54,14 @@ class Form extends RequestHandler {
*/
public $IncludeFormTag = true;
/**
* @var FieldList
*/
protected $fields;
/**
* @var FieldList
*/
protected $actions;
/**
@ -63,10 +69,19 @@ class Form extends RequestHandler {
*/
protected $controller;
/**
* @var string
*/
protected $name;
/**
* @var Validator
*/
protected $validator;
/**
* @var string
*/
protected $formMethod = "post";
/**
@ -74,16 +89,21 @@ class Form extends RequestHandler {
*/
protected $strictFormMethodCheck = false;
/**
* @var string
*/
protected static $current_action;
/**
* @var Dataobject $record Populated by {@link loadDataFrom()}.
* @var DataObject $record Populated by {@link loadDataFrom()}.
*/
protected $record;
/**
* Keeps track of whether this form has a default action or not.
* Set to false by $this->disableDefaultAction();
*
* @var boolean
*/
protected $hasDefaultAction = true;
@ -115,10 +135,19 @@ class Form extends RequestHandler {
*/
protected $template;
/**
* @var callable
*/
protected $buttonClickedFunc;
/**
* @var string
*/
protected $message;
/**
* @var string
*/
protected $messageType;
/**
@ -129,6 +158,9 @@ class Form extends RequestHandler {
*/
protected $redirectToFormOnValidationError = false;
/**
* @var bool
*/
protected $security = true;
/**
@ -152,17 +184,25 @@ class Form extends RequestHandler {
*/
protected $attributes = array();
/**
* @var array
*/
private static $allowed_actions = array(
'handleField',
'httpSubmission',
'forTemplate',
);
/**
* @var bool
*/
protected $securityTokenAdded;
/**
* Create a new form, with the given fields an action buttons.
*
* @param Controller $controller The parent controller, necessary to create the appropriate form action tag.
* @param String $name The method on the controller that will return this form object.
* @param string $name The method on the controller that will return this form object.
* @param FieldList $fields All of the fields in the form - a {@link FieldList} of {@link FormField} objects.
* @param FieldList $actions All of the action buttons in the form - a {@link FieldLis} of
* {@link FormAction} objects
@ -211,6 +251,9 @@ class Form extends RequestHandler {
$this->securityToken = ($securityEnabled) ? new SecurityToken() : new NullSecurityToken();
}
/**
* @var array
*/
private static $url_handlers = array(
'field/$FieldName!' => 'handleField',
'POST ' => 'httpSubmission',
@ -221,6 +264,8 @@ class Form extends RequestHandler {
/**
* Set up current form errors in session to
* the current form if appropriate.
*
* @return $this
*/
public function setupFormErrors() {
$errorInfo = Session::get("FormInfo.{$this->FormName()}");
@ -253,6 +298,9 @@ class Form extends RequestHandler {
* Populates the form with {@link loadDataFrom()}, calls {@link validate()},
* and only triggers the requested form action/method
* if the form is valid.
*
* @param SS_HTTPRequest $request
* @throws SS_HTTPResponse_Exception
*/
public function httpSubmission($request) {
// Strict method check
@ -265,7 +313,7 @@ class Form extends RequestHandler {
$this->httpError(405, _t("Form.BAD_METHOD", "This form requires a ".$this->formMethod." submission"));
}
// ...and only uses the vairables corresponding to that method type
// ...and only uses the variables corresponding to that method type
$vars = $this->formMethod == 'get' ? $request->getVars() : $request->postVars();
} else {
$vars = $request->requestVars();
@ -315,7 +363,7 @@ class Form extends RequestHandler {
}
}
// If the action wasnt' set, choose the default on the form.
// If the action wasn't set, choose the default on the form.
if(!isset($funcName) && $defaultAction = $this->defaultAction()){
$funcName = $defaultAction->actionName();
}
@ -386,6 +434,10 @@ class Form extends RequestHandler {
return $this->httpError(404);
}
/**
* @param string $action
* @return bool
*/
public function checkAccessAction($action) {
return (
parent::checkAccessAction($action)
@ -403,7 +455,7 @@ class Form extends RequestHandler {
* Returns the appropriate response up the controller chain
* if {@link validate()} fails (which is checked prior to executing any form actions).
* By default, returns different views for ajax/non-ajax request, and
* handles 'appliction/json' requests with a JSON object containing the error messages.
* handles 'application/json' requests with a JSON object containing the error messages.
* Behaviour can be influenced by setting {@link $redirectToFormOnValidationError}.
*
* @return SS_HTTPResponse|string
@ -444,6 +496,8 @@ class Form extends RequestHandler {
/**
* Fields can have action to, let's check if anyone of the responds to $funcname them
*
* @param SS_List|array $fields
* @param callable $funcName
* @return FormField
*/
protected function checkFieldsForAction($fields, $funcName) {
@ -492,7 +546,9 @@ class Form extends RequestHandler {
* form on the page upon validation errors in the form or if
* they just need to redirect back to the page
*
* @param bool Redirect to the form
* @param bool $bool
* @return $this
* @internal param Redirect $bool to the form
*/
public function setRedirectToFormOnValidationError($bool) {
$this->redirectToFormOnValidationError = $bool;
@ -512,6 +568,10 @@ class Form extends RequestHandler {
/**
* Add a plain text error message to a field on this form. It will be saved into the session
* and used the next time this form is displayed.
* @param string $fieldName
* @param string $message
* @param string $messageType
* @param bool $escapeHtml
*/
public function addErrorMessage($fieldName, $message, $messageType, $escapeHtml = true) {
Session::add_to_array("FormInfo.{$this->FormName()}.errors", array(
@ -521,6 +581,9 @@ class Form extends RequestHandler {
));
}
/**
* @param FormTransformation $trans
*/
public function transform(FormTransformation $trans) {
$newFields = new FieldList();
foreach($this->fields as $field) {
@ -550,6 +613,8 @@ class Form extends RequestHandler {
/**
* Set the {@link Validator} on this form.
* @param Validator $validator
* @return $this
*/
public function setValidator(Validator $validator ) {
if($validator) {
@ -569,6 +634,7 @@ class Form extends RequestHandler {
/**
* Convert this form to another format.
* @param FormTransformation $format
*/
public function transformTo(FormTransformation $format) {
$newFields = new FieldList();
@ -642,6 +708,7 @@ class Form extends RequestHandler {
* Setter for the form fields.
*
* @param FieldList $fields
* @return $this
*/
public function setFields($fields) {
$this->fields = $fields;
@ -661,6 +728,7 @@ class Form extends RequestHandler {
* Setter for the form actions.
*
* @param FieldList $actions
* @return $this
*/
public function setActions($actions) {
$this->actions = $actions;
@ -676,8 +744,9 @@ class Form extends RequestHandler {
}
/**
* @param String
* @param String
* @param string $name
* @param string $value
* @return $this
*/
public function setAttribute($name, $value) {
$this->attributes[$name] = $value;
@ -685,12 +754,15 @@ class Form extends RequestHandler {
}
/**
* @return String
* @return string $name
*/
public function getAttribute($name) {
if(isset($this->attributes[$name])) return $this->attributes[$name];
}
/**
* @return array
*/
public function getAttributes() {
$attrs = array(
'id' => $this->FormName(),
@ -713,9 +785,10 @@ class Form extends RequestHandler {
/**
* Return the attributes of the form tag - used by the templates.
*
* @param Array Custom attributes to process. Falls back to {@link getAttributes()}.
* @param array Custom attributes to process. Falls back to {@link getAttributes()}.
* If at least one argument is passed as a string, all arguments act as excludes by name.
* @return String HTML attributes, ready for insertion into an HTML tag
*
* @return string HTML attributes, ready for insertion into an HTML tag
*/
public function getAttributesHTML($attrs = null) {
$exclude = (is_string($attrs)) ? func_get_args() : null;
@ -743,7 +816,7 @@ class Form extends RequestHandler {
// Remove excluded
if($exclude) $attrs = array_diff_key($attrs, array_flip($exclude));
// Create markkup
// Create markup
$parts = array();
foreach($attrs as $name => $value) {
$parts[] = ($value === true) ? "{$name}=\"{$name}\"" : "{$name}=\"" . Convert::raw2att($value) . "\"";
@ -760,7 +833,8 @@ 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
* @param string $target The value of the target
* @return $this
*/
public function setTarget($target) {
$this->target = $target;
@ -770,6 +844,8 @@ class Form extends RequestHandler {
/**
* Set the legend value to be inserted into
* the <legend> element in the Form.ss template.
* @param $legend
* @return $this
*/
public function setLegend($legend) {
$this->legend = $legend;
@ -781,6 +857,7 @@ class Form extends RequestHandler {
* to render with. The default is "Form".
*
* @param string $template The name of the template (without the .ss extension)
* @return $this
*/
public function setTemplate($template) {
$this->template = $template;
@ -824,7 +901,8 @@ class Form extends RequestHandler {
* Sets the form encoding type. The most common encoding types are defined
* in {@link ENC_TYPE_URLENCODED} and {@link ENC_TYPE_MULTIPART}.
*
* @param string $enctype
* @param $encType
* @return $this
*/
public function setEncType($encType) {
$this->encType = $encType;
@ -851,7 +929,7 @@ class Form extends RequestHandler {
* Returns the form method to be used in the <form> tag.
* See {@link FormHttpMethod()} to get the "real" method.
*
* @return string Form tag compatbile HTTP method: 'get' or 'post'
* @return string Form tag compatible HTTP method: 'get' or 'post'
*/
public function FormMethod() {
if(in_array($this->formMethod,array('get','post'))) {
@ -864,8 +942,9 @@ class Form extends RequestHandler {
/**
* Set the form method: GET, POST, PUT, DELETE.
*
* @param $method string
* @param $strict If non-null, pass value to {@link setStrictFormMethodCheck()}.
* @param string $method
* @param bool $strict If non-null, pass value to {@link setStrictFormMethodCheck()}.
* @return $this
*/
public function setFormMethod($method, $strict = null) {
$this->formMethod = strtolower($method);
@ -884,6 +963,7 @@ class Form extends RequestHandler {
* form.
*
* @param $bool boolean
* @return $this
*/
public function setStrictFormMethodCheck($bool) {
$this->strictFormMethodCheck = (bool)$bool;
@ -921,6 +1001,9 @@ 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 $path
* @return $this
*/
public function setFormAction($path) {
$this->formActionPath = $path;
@ -942,6 +1025,9 @@ class Form extends RequestHandler {
/**
* Set the HTML ID attribute of the form
*
* @param string $id
* @return $this
*/
public function setHTMLID($id) {
$this->htmlID = $id;
@ -1038,11 +1124,12 @@ class Form extends RequestHandler {
/**
* Set a status message for the form.
*
* @param message the text of the message
* @param type Should be set to good, bad, or warning.
* @param string $message the text of the message
* @param string $type Should be set to good, bad, or warning.
* @param boolean $escapeHtml Automatically sanitize the message. Set to FALSE if the message contains HTML.
* In that case, you might want to use {@link Convert::raw2xml()} to escape any
* user supplied data in the message.
* @return $this
*/
public function setMessage($message, $type, $escapeHtml = true) {
$this->message = ($escapeHtml) ? Convert::raw2xml($message) : $message;
@ -1053,8 +1140,8 @@ class Form extends RequestHandler {
/**
* Set a message to the session, for display next time this form is shown.
*
* @param message the text of the message
* @param type Should be set to good, bad, or warning.
* @param string $message the text of the message
* @param string $type Should be set to good, bad, or warning.
* @param boolean $escapeHtml Automatically sanitize the message. Set to FALSE if the message contains HTML.
* In that case, you might want to use {@link Convert::raw2xml()} to escape any
* user supplied data in the message.
@ -1154,7 +1241,7 @@ class Form extends RequestHandler {
*
* @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 interrogated 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
@ -1172,7 +1259,7 @@ class Form extends RequestHandler {
* For backwards compatibility reasons, this parameter can also be set to === true, which is the same as passing
* CLEAR_MISSING
*
* @param $fieldList An optional list of fields to process. This can be useful when you have a
* @param FieldList $fieldList An optional list of fields to process. This can be useful when you have a
* form that has some fields that save to one object, and some that save to another.
* @return Form
*/
@ -1198,7 +1285,7 @@ class Form extends RequestHandler {
if($dataFields) foreach($dataFields as $field) {
$name = $field->getName();
// Skip fields that have been exlcuded
// Skip fields that have been excluded
if($fieldList && !in_array($name, $fieldList)) continue;
// First check looks for (fieldname)_unchanged, an indicator that we shouldn't overwrite the field value
@ -1258,8 +1345,8 @@ class Form extends RequestHandler {
* Save the contents of this form into the given data object.
* It will make use of setCastedField() to do this.
*
* @param $dataObject The object to save data into
* @param $fieldList An optional list of fields to process. This can be useful when you have a
* @param DataObjectInterface $dataObject The object to save data into
* @param FieldList $fieldList An optional list of fields to process. This can be useful when you have a
* form that has some fields that save to one object, and some that save to another.
*/
public function saveInto(DataObjectInterface $dataObject, $fieldList = null) {
@ -1311,8 +1398,9 @@ class Form extends RequestHandler {
* 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.
* @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]
*
* @param array $data
* @return mixed
*/
public function callfieldmethod($data) {
$fieldName = $data['fieldName'];
@ -1335,7 +1423,6 @@ class Form extends RequestHandler {
} else {
user_error("Form::callfieldmethod() Field '$fieldName' not found", E_USER_ERROR);
}
}
/**
@ -1391,6 +1478,8 @@ 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
* @param string|array $template
* @return HTMLText
*/
public function renderWithoutActionButton($template) {
$custom = $this->customise(array(
@ -1404,13 +1493,18 @@ class Form extends RequestHandler {
/**
* 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.
*
* @param callable $funcName The name of the action method that will be called.
* @return $this
*/
public function setButtonClicked($funcName) {
$this->buttonClickedFunc = $funcName;
return $this;
}
/**
* @return mixed
*/
public function buttonClicked() {
foreach($this->actions->dataFields() as $action) {
if($action->hasMethod('actionname') && $this->buttonClickedFunc == $action->actionName()) {
@ -1421,6 +1515,8 @@ class Form extends RequestHandler {
/**
* Return the default button that should be clicked when another one isn't available
*
* @return mixed|void
*/
public function defaultAction() {
if($this->hasDefaultAction && $this->actions)
@ -1491,6 +1587,8 @@ class Form extends RequestHandler {
/**
* Set the current form action. Should only be called by Controller.
*
* @param $action
*/
public static function set_current_action($action) {
self::$current_action = $action;
@ -1511,6 +1609,7 @@ class Form extends RequestHandler {
*
* @param string $class A string containing a classname or several class
* names delimited by a single space.
* @return $this
*/
public function addExtraClass($class) {
//split at white space
@ -1527,6 +1626,7 @@ class Form extends RequestHandler {
* be passed through as a space delimited string
*
* @param string $class
* @return $this
*/
public function removeExtraClass($class) {
//split at white space
@ -1558,8 +1658,11 @@ class Form extends RequestHandler {
/**
* Test a submission of this form.
* @param string $action
* @param array $data
* @return SS_HTTPResponse the response object that the handling controller produces. You can interrogate this in
* your unit test.
* @throws SS_HTTPResponse_Exception
*/
public function testSubmission($action, $data) {
$data['action_' . $action] = true;
@ -1572,6 +1675,9 @@ class Form extends RequestHandler {
/**
* Test an ajax submission of this form.
*
* @param string $action
* @param array $data
* @return SS_HTTPResponse the response object that the handling controller produces. You can interrogate this in
* your unit test.
*/
@ -1595,6 +1701,8 @@ class Form_FieldMap extends ViewableData {
/**
* Ensure that all potential method calls get passed to __call(), therefore to dataFieldByName
* @param string $method
* @return bool
*/
public function hasMethod($method) {
return true;