tonyair/silverstripe-framework
1
0
Fork 0
mirror of https://github.com/silverstripe/silverstripe-framework synced 2024-06-29 07:59:31 +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
/**
* Represents a field in a form.
*
* A FieldList contains a number of FormField objects which make up the whole of a form.
* In addition to single fields, FormField objects can be "composite", for example, the {@link TabSet}
* field. Composite fields let us define complex forms without having to resort to custom HTML.
* A FieldList contains a number of FormField objects which make up the whole
* of a form. In addition to single fields, FormField objects can be
* "composite", for example, the {@link TabSet} field. Composite fields let us
* define complex forms without having to resort to custom HTML.
*
* <b>Subclassing</b>
*
* 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</$tag>";
else return "<$tag$preparedAttributes />";
if($content || $tag != 'input') {
return "<$tag$preparedAttributes>$content</$tag>";
}
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;