tonyair/silverstripe-framework
1
0
Fork 0
mirror of https://github.com/silverstripe/silverstripe-framework synced 2024-10-22 14:05:37 +02:00
Code Issues Projects Releases Wiki Activity

PHPDoc

Browse Source
This commit is contained in:
Will Rossiter 2013-05-26 11:06:39 +12:00
parent e1ce3e15d8
commit 32559554fa
1 changed files with 117 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

155
forms/FormField.php
View File

@ -1,18 +1,21 @@
<?php <?php
/** /**
* Represents a field in a form. * Represents a field in a form.
* *
* A FieldList contains a number of FormField objects which make up the whole of a form. * A FieldList contains a number of FormField objects which make up the whole
* In addition to single fields, FormField objects can be "composite", for example, the {@link TabSet} * of a form. In addition to single fields, FormField objects can be
* field. Composite fields let us define complex forms without having to resort to custom HTML. * "composite", for example, the {@link TabSet} field. Composite fields let us
* define complex forms without having to resort to custom HTML.
* *
* <b>Subclassing</b> * <b>Subclassing</b>
* *
* Define a {@link dataValue()} method that returns a value suitable for inserting into a single database field. * Define a {@link dataValue()} method that returns a value suitable for
* For example, you might tidy up the format of a date or currency field. * inserting into a single database field. For example, you might tidy up the
* Define {@link saveInto()} to totally customise saving. * format of a date or currency field. Define {@link saveInto()} to totally
* For example, data might be saved to the filesystem instead of the data record, * customise saving. For example, data might be saved to the filesystem instead
* or saved to a component of the data record instead of the data record itself. * of the data record, or saved to a component of the data record instead of
* the data record itself.
* *
* @package forms * @package forms
* @subpackage core * @subpackage core
@ -119,9 +122,16 @@ class FormField extends RequestHandler {
/** /**
* Construct and return HTML tag. * 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) { public static function create_tag($tag, $attributes, $content = null) {
$preparedAttributes = ''; $preparedAttributes = '';
foreach($attributes as $k => $v) { foreach($attributes as $k => $v) {
// Note: as indicated by the $k == value item here; the decisions over what to include in the attributes // Note: as indicated by the $k == value item here; the decisions over what to include in the attributes
// can sometimes get finicky // can sometimes get finicky
@ -130,15 +140,20 @@ class FormField extends RequestHandler {
} }
} }
if($content || $tag != 'input') return "<$tag$preparedAttributes>$content</$tag>"; if($content || $tag != 'input') {
else return "<$tag$preparedAttributes />"; return "<$tag$preparedAttributes>$content</$tag>";
}
else {
return "<$tag$preparedAttributes />";
}
} }
/** /**
* Create a new field. * Create a new field.
* @param name The internal field name, passed to forms. *
* @param title The field label. * @param string $name The internal field name, passed to forms.
* @param value The value of the field. * @param string $title The field label.
* @param mixed $value The value of the field.
*/ */
public function __construct($name, $title = null, $value = null) { public function __construct($name, $title = null, $value = null) {
$this->name = $name; $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) { public function Link($action = null) {
return Controller::join_links($this->form->FormAction(), 'field/' . $this->name, $action); 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. * Returns the field message, used by form validation.
*
* Use {@link setError()} to set this property. * Use {@link setError()} to set this property.
* *
* @return string * @return string
@ -188,9 +208,9 @@ class FormField extends RequestHandler {
/** /**
* Returns the field message type, used by form validation. * 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". * Arbitrary value which is mostly used for CSS classes in the rendered HTML,
* Use {@link setError()} to set this property. * e.g. "required". Use {@link setError()} to set this property.
* *
* @return string * @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() * By default, makes use of $this->dataValue()
*
* @param DataObjectInterface
*/ */
public function saveInto(DataObjectInterface $record) { public function saveInto(DataObjectInterface $record) {
if($this->name) { 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() { public function dataValue() {
return $this->value; return $this->value;
@ -224,11 +250,18 @@ class FormField extends RequestHandler {
/** /**
* Returns the field label - used by templates. * Returns the field label - used by templates.
*
* @return string
*/ */
public function Title() { public function Title() {
return $this->title; return $this->title;
} }
/**
* @param string $val
*
* @return FormField
*/
public function setTitle($val) { public function setTitle($val) {
$this->title = $val; $this->title = $val;
return $this; return $this;
@ -322,7 +355,7 @@ class FormField extends RequestHandler {
* - 'name': {@link setName} * - 'name': {@link setName}
* *
* CAUTION Doesn't work on most fields which are composed of more than one HTML form field: * 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, * CountryDropdownField, CreditCardField, CurrencyField, DateField, DatetimeField, FieldGroup, GridField,
* HtmlEditorField, ImageField, ImageFormAction, InlineFormAction, ListBoxField, etc. * HtmlEditorField, ImageField, ImageFormAction, InlineFormAction, ListBoxField, etc.
* *
@ -342,6 +375,7 @@ class FormField extends RequestHandler {
*/ */
public function getAttribute($name) { public function getAttribute($name) {
$attrs = $this->getAttributes(); $attrs = $this->getAttributes();
return @$attrs[$name]; return @$attrs[$name];
} }
@ -364,12 +398,15 @@ class FormField extends RequestHandler {
/** /**
* @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. * 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) { public function getAttributesHTML($attrs = null) {
$exclude = (is_string($attrs)) ? func_get_args() : 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 // Remove empty
$attrs = array_filter((array)$attrs, function($v) { $attrs = array_filter((array)$attrs, function($v) {
@ -377,10 +414,13 @@ class FormField extends RequestHandler {
}); });
// Remove excluded // 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(); $parts = array();
foreach($attrs as $name => $value) { foreach($attrs as $name => $value) {
$parts[] = ($value === true) ? "{$name}=\"{$name}\"" : "{$name}=\"" . Convert::raw2att($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() { public function attrTitle() {
return Convert::raw2att($this->title); 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() { public function attrValue() {
return Convert::raw2att($this->value); return Convert::raw2att($this->value);
@ -403,28 +450,43 @@ class FormField extends RequestHandler {
/** /**
* Set the field value. * Set the field value.
* Returns $this. *
* @param mixed $value
*
* @return FormField.
*/ */
public function setValue($value) { public function setValue($value) {
$this->value = $value; $this->value = $value;
return $this; return $this;
} }
/** /**
* Set the field name * Set the field name
*
* @param string $name
*
* @return FormField
*/ */
public function setName($name) { public function setName($name) {
$this->name = $name; $this->name = $name;
return $this; return $this;
} }
/** /**
* Set the container form. * 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) { public function setForm($form) {
$this->form = $form; $this->form = $form;
return $this; 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 * @return bool
*/ */
public function securityTokenEnabled() { public function securityTokenEnabled() {
$form = $this->getForm(); $form = $this->getForm();
if(!$form) return false;
if(!$form) {
return false;
}
return $form->getSecurityToken()->isEnabled(); return $form->getSecurityToken()->isEnabled();
} }
/** /**
* Sets the error message to be displayed on the form field * Sets the error message to be displayed on the {@link FormField}.
* Set by php validation of the form *
* Set by php validation of the form.
*
* @param string $message
* @param string $messageType
*
* @return FormField
*/ */
public function setError($message, $messageType) { public function setError($message, $messageType) {
$this->message = $message; $this->message = $message;
@ -463,9 +535,11 @@ class FormField extends RequestHandler {
/** /**
* Set the custom error message to show instead of the default * Set the custom error message to show instead of the default
* format of Please Fill In XXX. Different from setError() as * 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) { public function setCustomValidationMessage($msg) {
$this->customValidationMessage = $msg; $this->customValidationMessage = $msg;
@ -487,10 +561,13 @@ class FormField extends RequestHandler {
/** /**
* Set name of template (without path or extension). * 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.
* *
* @param string * Caution: Not consistently implemented in all subclasses, please check
* the {@link Field()} method on the subclass for support.
*
* @param string $template
*
* @return FormField
*/ */
public function setTemplate($template) { public function setTemplate($template) {
$this->template = $template; $this->template = $template;
@ -519,7 +596,9 @@ class FormField extends RequestHandler {
* Caution: Not consistently implemented in all subclasses, * Caution: Not consistently implemented in all subclasses,
* please check the {@link Field()} method on the subclass for support. * please check the {@link Field()} method on the subclass for support.
* *
* @param string * @param string $template
*
* @return FormField
*/ */
public function setFieldHolderTemplate($template) { public function setFieldHolderTemplate($template) {
$this->fieldHolderTemplate = $template; $this->fieldHolderTemplate = $template;