diff --git a/forms/FormField.php b/forms/FormField.php index 757add144..0496e7d92 100644 --- a/forms/FormField.php +++ b/forms/FormField.php @@ -1,18 +1,21 @@ Subclassing * - * Define a {@link dataValue()} method that returns a value suitable for inserting into a single database field. - * For example, you might tidy up the format of a date or currency field. - * Define {@link saveInto()} to totally customise saving. - * For example, data might be saved to the filesystem instead of the data record, - * or saved to a component of the data record instead of the data record itself. + * Define a {@link dataValue()} method that returns a value suitable for + * inserting into a single database field. For example, you might tidy up the + * format of a date or currency field. Define {@link saveInto()} to totally + * customise saving. For example, data might be saved to the filesystem instead + * of the data record, or saved to a component of the data record instead of + * the data record itself. * * @package forms * @subpackage core @@ -119,9 +122,16 @@ class FormField extends RequestHandler { /** * Construct and return HTML tag. + * + * @param string $tag + * @param array $attributes + * @param mixed $content + * + * @return string */ public static function create_tag($tag, $attributes, $content = null) { $preparedAttributes = ''; + foreach($attributes as $k => $v) { // Note: as indicated by the $k == value item here; the decisions over what to include in the attributes // can sometimes get finicky @@ -130,15 +140,20 @@ class FormField extends RequestHandler { } } - if($content || $tag != 'input') return "<$tag$preparedAttributes>$content"; - else return "<$tag$preparedAttributes />"; + if($content || $tag != 'input') { + return "<$tag$preparedAttributes>$content"; + } + else { + return "<$tag$preparedAttributes />"; + } } /** * Create a new field. - * @param name The internal field name, passed to forms. - * @param title The field label. - * @param value The value of the field. + * + * @param string $name The internal field name, passed to forms. + * @param string $title The field label. + * @param mixed $value The value of the field. */ public function __construct($name, $title = null, $value = null) { $this->name = $name; @@ -150,7 +165,11 @@ class FormField extends RequestHandler { } /** - * Return a Link to this field + * Return a link to this field. + * + * @param string $action + * + * @return string */ public function Link($action = null) { return Controller::join_links($this->form->FormAction(), 'field/' . $this->name, $action); @@ -178,6 +197,7 @@ class FormField extends RequestHandler { /** * Returns the field message, used by form validation. + * * Use {@link setError()} to set this property. * * @return string @@ -188,9 +208,9 @@ class FormField extends RequestHandler { /** * Returns the field message type, used by form validation. - * Arbitrary value which is mostly used for CSS classes - * in the rendered HTML, e.g. "required". - * Use {@link setError()} to set this property. + * + * Arbitrary value which is mostly used for CSS classes in the rendered HTML, + * e.g. "required". Use {@link setError()} to set this property. * * @return string */ @@ -206,8 +226,11 @@ class FormField extends RequestHandler { } /** - * Method to save this form field into the given data object. + * Method to save this form field into the given {@link DataObject}. + * * By default, makes use of $this->dataValue() + * + * @param DataObjectInterface */ public function saveInto(DataObjectInterface $record) { if($this->name) { @@ -216,7 +239,10 @@ class FormField extends RequestHandler { } /** - * Returns the field value suitable for insertion into the data object + * Returns the field value suitable for insertion into the + * {@link DataObject}. + * + * @return mixed */ public function dataValue() { return $this->value; @@ -224,11 +250,18 @@ class FormField extends RequestHandler { /** * Returns the field label - used by templates. + * + * @return string */ public function Title() { return $this->title; } + /** + * @param string $val + * + * @return FormField + */ public function setTitle($val) { $this->title = $val; return $this; @@ -322,7 +355,7 @@ class FormField extends RequestHandler { * - 'name': {@link setName} * * CAUTION Doesn't work on most fields which are composed of more than one HTML form field: - * AjaxUniqueTextField, CheckboxSetField, ComplexTableField, CompositeField, ConfirmedPasswordField, + * AjaxUniqueTextField, CheckboxSetField, CompositeField, ConfirmedPasswordField, * CountryDropdownField, CreditCardField, CurrencyField, DateField, DatetimeField, FieldGroup, GridField, * HtmlEditorField, ImageField, ImageFormAction, InlineFormAction, ListBoxField, etc. * @@ -342,6 +375,7 @@ class FormField extends RequestHandler { */ public function getAttribute($name) { $attrs = $this->getAttributes(); + return @$attrs[$name]; } @@ -364,12 +398,15 @@ class FormField extends RequestHandler { /** * @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 */ public function getAttributesHTML($attrs = null) { $exclude = (is_string($attrs)) ? func_get_args() : null; - if(!$attrs || is_string($attrs)) $attrs = $this->getAttributes(); + if(!$attrs || is_string($attrs)) { + $attrs = $this->getAttributes(); + } // Remove empty $attrs = array_filter((array)$attrs, function($v) { @@ -377,10 +414,13 @@ class FormField extends RequestHandler { }); // Remove excluded - if($exclude) $attrs = array_diff_key($attrs, array_flip($exclude)); + 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) . "\""; } @@ -389,13 +429,20 @@ class FormField extends RequestHandler { } /** - * Returns a version of a title suitable for insertion into an HTML attribute + * Returns a version of a title suitable for insertion into an HTML + * attribute. + * + * @return string */ public function attrTitle() { return Convert::raw2att($this->title); } + /** - * Returns a version of a title suitable for insertion into an HTML attribute + * Returns a version of a title suitable for insertion into an HTML + * attribute. + * + * @return string */ public function attrValue() { return Convert::raw2att($this->value); @@ -403,28 +450,43 @@ class FormField extends RequestHandler { /** * Set the field value. - * Returns $this. + * + * @param mixed $value + * + * @return FormField. */ public function setValue($value) { $this->value = $value; + return $this; } /** * Set the field name + * + * @param string $name + * + * @return FormField */ public function setName($name) { $this->name = $name; + return $this; } /** * Set the container form. - * This is called whenever you create a new form and put fields inside it, so that you don't - * have to worry about linking the two. + * + * This is called whenever you create a new form and put fields inside it, + * so that you don't have to worry about linking the two. + * + * @param Form + * + * @return FormField */ public function setForm($form) { $this->form = $form; + return $this; } @@ -438,20 +500,30 @@ class FormField extends RequestHandler { } /** - * Return TRUE if security token protection is enabled on the parent {@link Form}. + * Return TRUE if security token protection is enabled on the parent + * {@link Form}. * * @return bool */ public function securityTokenEnabled() { $form = $this->getForm(); - if(!$form) return false; + + if(!$form) { + return false; + } return $form->getSecurityToken()->isEnabled(); } /** - * Sets the error message to be displayed on the form field - * Set by php validation of the form + * Sets the error message to be displayed on the {@link FormField}. + * + * Set by php validation of the form. + * + * @param string $message + * @param string $messageType + * + * @return FormField */ public function setError($message, $messageType) { $this->message = $message; @@ -463,9 +535,11 @@ class FormField extends RequestHandler { /** * Set the custom error message to show instead of the default * format of Please Fill In XXX. Different from setError() as - * that appends it to the standard error messaging + * that appends it to the standard error messaging. * - * @param string Message for the error + * @param string $msg Message for the error + * + * @return FormField */ public function setCustomValidationMessage($msg) { $this->customValidationMessage = $msg; @@ -487,10 +561,13 @@ class FormField extends RequestHandler { /** * Set name of template (without path or extension). - * Caution: Not consistently implemented in all subclasses, - * please check the {@link Field()} method on the subclass for support. + * + * Caution: Not consistently implemented in all subclasses, please check + * the {@link Field()} method on the subclass for support. * - * @param string + * @param string $template + * + * @return FormField */ public function setTemplate($template) { $this->template = $template; @@ -519,7 +596,9 @@ class FormField extends RequestHandler { * Caution: Not consistently implemented in all subclasses, * please check the {@link Field()} method on the subclass for support. * - * @param string + * @param string $template + * + * @return FormField */ public function setFieldHolderTemplate($template) { $this->fieldHolderTemplate = $template;