PHP Class Gdn_Form, vanilla

Helps with the rendering of form controls that link directly to a data model.

Since: 2.0

Author: Mark O'Sullivan ([email protected])

Inheritance: extends Gdn_Pluggable

ファイルを表示 Open project: vanilla/vanilla Class Usage Examples

Public Properties

Property	Type	Description
$Action		Action with which the form should be sent.
$ErrorClass		Class name to assign to form elements with errors when InlineErrors is enabled.
$HiddenInputs		Associative array of hidden inputs with their "Name" attribute as the key.
$IDPrefix		All form-related elements (form, input, select, textarea, [etc] will have this value prefixed on their ID attribute. Default is "Form_". If the id value is overridden with the Attribute collection for an element, this value will not be used.
$Method		Form submit method. Options are 'post' or 'get'.
$_FormValues	array

Protected Properties

Property	Type	Description
$_DataArray		Associative array containing the key => value pairs being placed in the controls returned by this object. Assigned by $this->Open() or $this->SetData().
$_InlineErrors		Whether to display inline errors with form elements. Set with ShowErrors() and HideErrors().
$_Model		Model that enforces data rules on $this->_DataArray.
$_ValidationResults		Associative array of $FieldName => $ValidationFunctionName arrays that describe how each field specified failed validation.

Public Methods

Method	Description
__construct ( string $TableName = '', string $style = '' )	Constructor
__get ( strig $name ) : mixed	Backwards compatibility getter.
__set ( string $name, mixed $value )	Backwards compatibility setter.
addError ( $Error, string $FieldName = '' )	Adds an error to the errors collection and optionally relates it to the specified FieldName. Errors added with this method can be rendered with $this->Errors().
addErrorClass ( array &$Attributes )	Add ErrorClass to Attributes['class'].
addHidden ( string $FieldName, string $Value = null, boolean $ForceValue = false )	Adds a hidden input value to the form.
authenticatedPostBack ( boolean $throw = false ) : boolean	Returns a boolean value indicating if the current page has an authenticated postback.
bodyBox ( string $Column = 'Body', array $Attributes = [] ) : string	A special text box for formattable text.
button ( string $ButtonCode, array $Attributes = [] ) : string	Returns XHTML for a button.
buttonExists ( string $ButtonCode ) : boolean	Checks $this->FormValues() to see if the specified button translation code was submitted with the form (helps figuring out what button was pressed to submit the form when there is more than one button available).
calendar ( string $FieldName, array $Attributes = [] ) : string	Returns XHTML for a standard calendar input control.
captcha ( ) : string	Returns Captcha HTML & adds translations to document head.
categoryDropDown ( array $FieldName = 'CategoryID', array $Options = [] ) : string	Returns XHTML for a select list containing categories that the user has permission to use.
checkBox ( string $FieldName, string $Label = '', array $Attributes = [] ) : string	Returns XHTML for a checkbox input element.
checkBoxGrid ( string $FieldName, mixed $DataSet, mixed $ValueDataSet, array $Attributes ) : string	Returns the xhtml for a list of checkboxes; sorted into groups related to the TextField value of the dataset.
checkBoxGridGroup ( $GroupName, $Data, $FieldName ) : string
checkBoxGridGroups ( $Data, $FieldName ) : string
checkBoxList ( string $FieldName, mixed $DataSet, mixed $ValueDataSet = null, array $Attributes = [] ) : string	Returns the XHTML for a list of checkboxes.
clearInputs ( )	Emptys the $this->_FormValues collection so that all form fields will load empty.
close ( string $ButtonCode = '', string $Xhtml = '', $Attributes = [] ) : string	Returns the closing of the form tag with an optional submit button.
color ( string $fieldName ) : string	Builds a color-picker form element. Accepts three-character hex values with or without the leading '#', but the saved value will be coerced into a six-character hex code with the leading '#'.
currentImage ( type $FieldName, type $Attributes = [] )	Returns the current image in a field.
date ( string $FieldName, array $Attributes = [] ) : string	Returns XHTML for a standard date input control.
dropDown ( string $FieldName, mixed $DataSet, array $Attributes = [] ) : string	Returns XHTML for a select list.
dropDownGroup ( string $FieldName, array $Data, string $GroupField, string $TextField, string $ValueField, array $Attributes = [] ) : string	Returns the xhtml for a dropdown list with option groups.
errorCount ( ) : integer	Returns a count of the number of errors that have occurred.
errorString ( )
errors ( ) : string	Returns XHTML for all form-related errors that have occurred.
escapeFieldName ( string $string ) : string	Returns the provided fieldname with improper characters stripped.
escapeID ( string $FieldName, boolean $ForceUniqueID = true ) : string	Returns the provided fieldname with non-alpha-numeric values stripped and $this->IDPrefix prepended.
escapeString ( string $string ) : string
fileUpload ( string $fieldName, array $attributes = [] ) : string	Outputs a stylized file upload input. Requires dashboard.js and dashboard.css to look and work as intended.
fileUploadWrap ( string $fieldName, array $attributes = [] ) : string	Outputs a stylized file upload input with a input wrapper div. Requires dashboard.js and dashboard.css to look and work as intended.
formData ( ) : array	Get form data array
formDataSet ( ) : array
formValues ( $NewValue = null ) : array	If the form has been posted back, this method return an associative array of $FieldName => $Value pairs which were sent in the form.
getCheckBoxGridGroup ( string $GroupName, array $Group, array $Rows, array $Cols )	Returns a checkbox table.
getFormValue ( string $FieldName, mixed $Default = '' ) : unknown	Gets the value associated with $FieldName from the sent form fields.
getHidden ( ) : string	Returns XHTML for all hidden fields.
getStyle ( string $item, null $default = null ) : string	Get a style element for the form.
getValue ( string $FieldName, mixed $Default = false ) : mixed	Gets the value associated with $FieldName.
hidden ( string $FieldName, array $Attributes = [] ) : string	Returns the xhtml for a hidden input.
hideErrors ( )	Disable inline errors (this is the default).
imageUpload ( string $FieldName, array $Attributes = [] ) : string	Return a control for uploading images.
imageUploadPreview ( string $fieldName, string $label = '', string $labelDescription = '', string $currentImageUrl = '', string $removeUrl = '', string $removeText = '', string $removeConfirmText = '', string $tag = 'li', array $attributes = [] ) : string	Outputs the entire form group with both the label and input. Adds an image preview and a link to delete the current image. Handles the ajax clearing of the image preview on removal.
imageUploadWrap ( string $fieldName, array $attributes = [] ) : string	Return a control for uploading images with a wrapper div. The existing image should be displayed by the label.
inlineError ( string $FieldName ) : string	Returns XHTML of inline error for specified field.
input ( string $FieldName, string $Type = 'text', array $Attributes = [] ) : string	Returns the xhtml for a standard input tag.
inputWrap ( $FieldName, $Type = 'text', $Attributes = [] )
isMyPostBack ( ) : boolean	Check if THIS particular form was submitted
isPostBack ( ) : boolean	Examines the sent form variable collection to see if any data was sent via the form back to the server. Returns TRUE on if anything is found.
label ( string $TranslationCode, string $FieldName = '', array $Attributes = [] ) : string	Returns XHTML for a label element.
labelCode ( string \| array $Item ) : string	Generate a friendly looking label translation code from a camel case variable name
labelWrap ( $TranslationCode, $FieldName = '', $Attributes = [] )
linkButton ( string $code, string $destination = '', array $attributes = [] )	Return a linked that will look like a button.
open ( array $Attributes = [] ) : string	Returns the xhtml for the opening of the form (the form tag and all hidden elements).
radio ( string $FieldName, string $Label = '', array $Attributes = [] ) : string	Returns XHTML for a radio input element.
radioList ( string $FieldName, mixed $DataSet, array $Attributes = [] ) : string	Returns XHTML for an unordered list of radio button elements.
removeFormValue ( string $FieldName )	Remove an element from a form.
save ( ) : unknown	This is a convenience method so that you don't have to code this every time you want to save a simple model's data.
saveImage ( string $Field, array $Options = [] )	Save an image from a field and delete any old image that's been uploaded.
searchForm ( string $field, string $url, array $textBoxAttributes = [], string $searchInfo = '' ) : string	Renders a search form.
searchInput ( string $field, string $url, array $textBoxAttributes = [], string $searchInfo = '' ) : string	Renders a stylized search field. Requires dashboard.css to look as intended. Use with searchForm() to output an entire search form.
setData ( array $Data )	Assign a set of data to be displayed in the form elements.
setFormValue ( string $FieldName, mixed $Value = null )	Sets the value associated with $FieldName from the sent form fields.
setModel ( Gdn_Model $Model, Ressource $DataSet = false )	Set the name of the model that will enforce data rules on $this->_DataArray.
setStyles ( string $name ) : boolean	Set the styles to use when outputting controls.
setValidationResults ( $ValidationResults )
setValue ( string $FieldName, $Value )	Sets the value associated with $FieldName.
showErrors ( )	Enable inline errors.
simple ( array $Schema, type $Options = [] )	Generates a multi-field form from a schema.
textBox ( string $FieldName, array $Attributes = [] ) : string	Returns the xhtml for a text-based input.
textBoxWrap ( $FieldName, $Attributes = [] )
toggle ( string $fieldName, string $label, array $attributes = [], string $info = '' ) : string	Outputs a checkbox painted as a toggle. Includes label wrap id a label is given.
unescapeFieldName ( string $string ) : string	Unescape strings that were escaped with {@link Gdn_Form::escapeFieldName()}.
validateModel ( ) : integer	If not saving data directly to the model, this method allows you to utilize a model's schema to validate a form's inputs regardless.
validateRule ( string $FieldName, string \| array $Rule, string $CustomError = '' ) : boolean	Validates a rule on the form and adds its result to the errors collection.
validationResults ( ) : array	Gets the validation results in the form.

Protected Methods

Method	Description
_attributesToString ( array $Attributes ) : string	Takes an associative array of $Attributes and returns them as a string of param="value" sets to be placed in an input, select, textarea, etc tag.
_idAttribute ( string $FieldName, array $Attributes ) : string	Creates an ID attribute for a form input and returns it in this format: [ id="IDNAME"]
_nameAttribute ( string $FieldName, array $Attributes ) : string	Creates a NAME attribute for a form input and returns it in this format: [ name="NAME"]
_valueAttribute ( string $FieldName, array $Attributes ) : string	Creates a VALUE attribute for a form input and returns it in this format: [ value="VALUE"]

Private Methods

Method	Description
translateClasses ( string \| string[] $classes ) : string	Translate old CSS classes using the style array.

Method Details

__construct() public method

Constructor

public __construct ( string $TableName = '', string $style = '' )
$TableName	string
$style	string	The style key to use.

__get() public method

Backwards compatibility getter.

public __get ( strig $name ) : mixed
$name	strig	The property to get.
return	mixed	Returns the value of the property.

__set() public method

Backwards compatibility setter.

public __set ( string $name, mixed $value )
$name	string	The name of the property to set.
$value	mixed	The new value of the property.

_attributesToString() protected method

Takes an associative array of $Attributes and returns them as a string of param="value" sets to be placed in an input, select, textarea, etc tag.

protected _attributesToString ( array $Attributes ) : string
$Attributes	array	An associative array of attribute key => value pairs to be converted to a string. A number of "reserved" keys will be ignored: 'id', 'name', 'maxlength', 'value', 'method', 'action', 'type'.
return	string

_idAttribute() protected method

Creates an ID attribute for a form input and returns it in this format: [ id="IDNAME"]

protected _idAttribute ( string $FieldName, array $Attributes ) : string
$FieldName	string	The name of the field that is being converted to an ID attribute.
$Attributes	array	An associative array of attributes for the input. ie. maxlength, onclick, class, etc. If $Attributes contains an 'id' key, it will override the one automatically generated by $FieldName.
return	string

_nameAttribute() protected method

Creates a NAME attribute for a form input and returns it in this format: [ name="NAME"]

protected _nameAttribute ( string $FieldName, array $Attributes ) : string
$FieldName	string	The name of the field that is being converted to a NAME attribute.
$Attributes	array	An associative array of attributes for the input. ie. maxlength, onclick, class, etc. If $Attributes contains a 'name' key, it will override the one automatically generated by $FieldName.
return	string

_valueAttribute() protected method

Creates a VALUE attribute for a form input and returns it in this format: [ value="VALUE"]

protected _valueAttribute ( string $FieldName, array $Attributes ) : string
$FieldName	string	The name of the field that contains the value in $this->_DataArray.
$Attributes	array	An associative array of attributes for the input. ie. maxlength, onclick, class, etc. If $Attributes contains a 'value' key, it will override the one automatically generated by $FieldName.
return	string

addError() public method

Adds an error to the errors collection and optionally relates it to the specified FieldName. Errors added with this method can be rendered with $this->Errors().

public addError ( $Error, string $FieldName = '' )
$FieldName	string	The name of the field to relate the error to.

addErrorClass() public method

Add ErrorClass to Attributes['class'].

Since: 2.0.18

public addErrorClass ( array &$Attributes )
$Attributes	array	Field attributes passed by reference (property => value).

addHidden() public method

If the $ForceValue parameter remains FALSE, it will grab the value into the hidden input from the form on postback. Otherwise it will always force the assigned value to the input regardless of postback.

public addHidden ( string $FieldName, string $Value = null, boolean $ForceValue = false )
$FieldName	string	The name of the field being added as a hidden input on the form.
$Value	string	The value being assigned in the hidden input. Unless $ForceValue is changed to TRUE, this field will be retrieved from the form upon postback.
$ForceValue	boolean

authenticatedPostBack() public method

It validates the postback by looking at a transient value that was rendered using $this->Open() and submitted with the form. Ref: http://en.wikipedia.org/wiki/Cross-site_request_forgery

public authenticatedPostBack ( boolean $throw = false ) : boolean
$throw	boolean	Whether or not to throw an exception if this is a postback AND the transient key doesn't validate.
return	boolean	Returns true if the postback could be authenticated or false otherwise.

bodyBox() public method

Formatting plugins like ButtonBar will auto-attach to this element.

Since: 2.1

public bodyBox ( string $Column = 'Body', array $Attributes = [] ) : string
$Column	string
$Attributes	array
return	string	HTML element.

button() public method

Returns XHTML for a button.

public button ( string $ButtonCode, array $Attributes = [] ) : string
$ButtonCode	string	The translation code for the text on the button.
$Attributes	array	An associative array of attributes for the button. Here is a list of "special" attributes and their default values: Attribute Options Default ------------------------------------------------------------------------ Type The type of submit button 'submit' Value Ignored for $ButtonCode $ButtonCode translated
return	string

buttonExists() public method

Checks $this->FormValues() to see if the specified button translation code was submitted with the form (helps figuring out what button was pressed to submit the form when there is more than one button available).

public buttonExists ( string $ButtonCode ) : boolean
$ButtonCode	string	The translation code of the button to check for.
return	boolean

calendar() public method

Returns XHTML for a standard calendar input control.

public calendar ( string $FieldName, array $Attributes = [] ) : string
$FieldName	string	The name of the field that is being displayed/posted with this input. It should related directly to a field name in $this->_DataArray.
$Attributes	array	An associative array of attributes for the input. ie. onclick, class, etc
return	string

captcha() public method

Events: BeforeCaptcha

public captcha ( ) : string
return	string

categoryDropDown() public method

Returns XHTML for a select list containing categories that the user has permission to use.

public categoryDropDown ( array $FieldName = 'CategoryID', array $Options = [] ) : string
$FieldName	array	An array of category data to render.
$Options	array	An associative array of options for the select. Here is a list of "special" options and their default values: Attribute Options Default ------------------------------------------------------------------------ Value The ID of the category that FALSE is selected. IncludeNull Include a blank row? TRUE Context A set of categories to [] interset with the CategoryData that is relative to the category we're in. CategoryData Custom set of categories to CategoryModel::Categories() display.
return	string

checkBox() public method

Cannot consider all checkbox values to be boolean. (2009-04-02 mosullivan) Cannot assume checkboxes are stored in database as string 'TRUE'. (2010-07-28 loki_racer)

public checkBox ( string $FieldName, string $Label = '', array $Attributes = [] ) : string
$FieldName	string	Name of the field that is being displayed/posted with this input. It should related directly to a field name in $this->_DataArray.
$Label	string	Label to place next to the checkbox.
$Attributes	array	Associative array of attributes for the input. (e.g. onclick, class)\ Setting 'InlineErrors' to FALSE prevents error message even if $this->InlineErrors is enabled.
return	string

checkBoxGrid() public method

Returns the xhtml for a list of checkboxes; sorted into groups related to the TextField value of the dataset.

public checkBoxGrid ( string $FieldName, mixed $DataSet, mixed $ValueDataSet, array $Attributes ) : string
$FieldName	string	The name of the field that is being displayed/posted with this input. It should related directly to a field name in a user junction table. ie. LUM_UserRole.RoleID
$DataSet	mixed	The data to fill the options in the select list. Either an associative array or a database dataset. ie. RoleID, Name from LUM_Role.
$ValueDataSet	mixed	The data that should be checked in $DataSet. Either an associative array or a database dataset. ie. RoleID from LUM_UserRole for a single user.
$Attributes	array	An associative array of attributes for the select. Here is a list of "special" attributes and their default values: Attribute Options Default ------------------------------------------------------------------------ ValueField The name of the field in 'value' $DataSet that contains the option values. TextField The name of the field in 'text' $DataSet that contains the option text.
return	string

checkBoxGridGroup() public method

public checkBoxGridGroup ( $GroupName, $Data, $FieldName ) : string
$GroupName
$Data
$FieldName
return	string

checkBoxGridGroups() public method

public checkBoxGridGroups ( $Data, $FieldName ) : string
$Data
$FieldName
return	string

checkBoxList() public method

Returns the XHTML for a list of checkboxes.

public checkBoxList ( string $FieldName, mixed $DataSet, mixed $ValueDataSet = null, array $Attributes = [] ) : string
$FieldName	string	Name of the field being posted with this input.
$DataSet	mixed	Data to fill the checkbox list. Either an associative array or a database dataset. ex: RoleID, Name from GDN_Role.
$ValueDataSet	mixed	Values to be pre-checked in $DataSet. Either an associative array or a database dataset. ex: RoleID from GDN_UserRole for a single user.
$Attributes	array	An associative array of attributes for the select. Here is a list of "special" attributes and their default values: Attribute Options Default ------------------------------------------------------------------------ ValueField The name of the field in 'value' $DataSet that contains the option values. TextField The name of the field in 'text' $DataSet that contains the option text.
return	string

clearInputs() public method

Emptys the $this->_FormValues collection so that all form fields will load empty.

public clearInputs ( )

close() public method

Returns the closing of the form tag with an optional submit button.

public close ( string $ButtonCode = '', string $Xhtml = '', $Attributes = [] ) : string
$ButtonCode	string
$Xhtml	string
return	string

color() public method

The hex value to be saved is the value of the input with the color-picker-value class.

public color ( string $fieldName ) : string
$fieldName	string	Name of the field being posted with this input.
return	string	The form element for a color picker.

currentImage() public method

This is meant to be used with image uploads so that users can see the current value.

Since: 2.1

public currentImage ( type $FieldName, type $Attributes = [] )
$FieldName	type
$Attributes	type

date() public method

Returns XHTML for a standard date input control.

public date ( string $FieldName, array $Attributes = [] ) : string
$FieldName	string	The name of the field that is being displayed/posted with this input. It should related directly to a field name in $this->_DataArray.
$Attributes	array	An associative array of attributes for the input, e.g. onclick, class. Special attributes: YearRange, specified in yyyy-yyyy format. Default is 1900 to current year. Fields, array of month, day, year. Those are only valid values. Order matters.
return	string

dropDown() public method

Returns XHTML for a select list.

public dropDown ( string $FieldName, mixed $DataSet, array $Attributes = [] ) : string
$FieldName	string	The name of the field that is being displayed/posted with this input. It should related directly to a field name in $this->_DataArray. ie. RoleID
$DataSet	mixed	The data to fill the options in the select list. Either an associative array or a database dataset.
$Attributes	array	An associative array of attributes for the select. Here is a list of "special" attributes and their default values: Attribute Options Default ------------------------------------------------------------------------ ValueField The name of the field in 'value' $DataSet that contains the option values. TextField The name of the field in 'text' $DataSet that contains the option text. Value A string or array of strings. $this->_DataArray->$FieldName IncludeNull TRUE to include a blank row FALSE String to create disabled first option. InlineErrors Show inline error message? TRUE Allows disabling per-dropdown for multi-fields like Date()
return	string

dropDownGroup() public method

Returns the xhtml for a dropdown list with option groups.

public dropDownGroup ( string $FieldName, array $Data, string $GroupField, string $TextField, string $ValueField, array $Attributes = [] ) : string
$FieldName	string
$Data	array
$GroupField	string
$TextField	string
$ValueField	string
$Attributes	array
return	string

errorCount() public method

Returns a count of the number of errors that have occurred.

public errorCount ( ) : integer
return	integer

errorString() public method

public errorString ( )

errors() public method

Returns XHTML for all form-related errors that have occurred.

public errors ( ) : string
return	string

escapeFieldName() public method

PHP doesn't allow "." in variable names from external sources such as a HTML form. Some Vanilla components however rely on variable names such as "a.b.c". So we need to escape them for backwards compatibility. Replaces e.g. "\" with "\\", "-dot-" with "\\-dot-" and "." with "-dot-".

escapeID() public method

Returns the provided fieldname with non-alpha-numeric values stripped and $this->IDPrefix prepended.

public escapeID ( string $FieldName, boolean $ForceUniqueID = true ) : string
$FieldName	string
$ForceUniqueID	boolean
return	string

escapeString() public method

fileUpload() public method

Outputs a stylized file upload input. Requires dashboard.js and dashboard.css to look and work as intended.

public fileUpload ( string $fieldName, array $attributes = [] ) : string
$fieldName	string
$attributes	array
return	string

fileUploadWrap() public method

Outputs a stylized file upload input with a input wrapper div. Requires dashboard.js and dashboard.css to look and work as intended.

public fileUploadWrap ( string $fieldName, array $attributes = [] ) : string
$fieldName	string
$attributes	array
return	string

formData() public method

Returns an associative array containing all the pre-propulated field data for the current form.

public formData ( ) : array
return	array

formDataSet() public method

public formDataSet ( ) : array
return	array

formValues() public method

Note: these values are typically used by the model and it's validation object.

public formValues ( $NewValue = null ) : array
return	array

getCheckBoxGridGroup() public method

Returns a checkbox table.

public getCheckBoxGridGroup ( string $GroupName, array $Group, array $Rows, array $Cols )
$GroupName	string	The name of the checkbox table (the text that appears in the top-left cell of the table). This value will be passed through the T() function before render.
$Group	array	An array of $PermissionName => $CheckBoxXhtml to be rendered within the grid. This represents the final (third) part of the permission name string, as in the "Edit" part of "Garden.Roles.Edit". ie. 'Edit' => '';
$Rows	array	An array of rows to appear in the grid. This represents the middle part of the permission name, as in the "Roles" part of "Garden.Roles.Edit".
$Cols	array	An array of columns to appear in the grid for each row. This (again) represents the final part of the permission name, as in the "Edit" part of "Garden.Roles.Edit". ie. Row1 = array('Add', 'Edit', 'Delete');

getFormValue() public method

If $FieldName isn't found in the form, it returns $Default.

public getFormValue ( string $FieldName, mixed $Default = '' ) : unknown
$FieldName	string	The name of the field to get the value of.
$Default	mixed	The default value to return if $FieldName isn't found.
return	unknown

getHidden() public method

Returns XHTML for all hidden fields.

public getHidden ( ) : string
return	string

getStyle() public method

Get a style element for the form.

public getStyle ( string $item, null $default = null ) : string
$item	string	The item, such as the element name or whatnot.
$default	null	The default. If this isn't supplied then the "default" class will be returned.
return	string	Returns the element.

getValue() public method

If the form has been posted back, it will retrieve the value from the form. If it hasn't been posted back, it gets the value from $this->_DataArray. Failing either of those, it returns $Default.

public getValue ( string $FieldName, mixed $Default = false ) : mixed
$FieldName	string
$Default	mixed
return	mixed

hidden() public method

Returns the xhtml for a hidden input.

public hidden ( string $FieldName, array $Attributes = [] ) : string
$FieldName	string	The name of the field that is being hidden/posted with this input. It should related directly to a field name in $this->_DataArray.
$Attributes	array	An associative array of attributes for the input. ie. maxlength, onclick, class, etc
return	string

hideErrors() public method

Disable inline errors (this is the default).

public hideErrors ( )

imageUpload() public method

Return a control for uploading images.

Since: 2.1

public imageUpload ( string $FieldName, array $Attributes = [] ) : string
$FieldName	string
$Attributes	array
return	string

imageUploadPreview() public method

Requires dashboard.js and dashboard.css to look and work as intended.

public imageUploadPreview ( string $fieldName, string $label = '', string $labelDescription = '', string $currentImageUrl = '', string $removeUrl = '', string $removeText = '', string $removeConfirmText = '', string $tag = 'li', array $attributes = [] ) : string
$fieldName	string	The form field name for the input.
$label	string	The label.
$labelDescription	string	The label description.
$currentImageUrl	string	The url to the current image.
$removeUrl	string	The endpoint to remove the image.
$removeText	string	The text for the remove image anchor, defaults to t('Remove').
$removeConfirmText	string	The text for the confirm modal, defaults to t('Are you sure you want to do that?').
$tag	string	The tag for the form-group. Defaults to li, but you may want a div or something.
$attributes	array	The attributes to pass to the file upload function.
return	string

imageUploadWrap() public method

Return a control for uploading images with a wrapper div. The existing image should be displayed by the label.

public imageUploadWrap ( string $fieldName, array $attributes = [] ) : string
$fieldName	string
$attributes	array
return	string

inlineError() public method

Returns XHTML of inline error for specified field.

Since: 2.0.18

public inlineError ( string $FieldName ) : string
$FieldName	string	The name of the field that is being displayed/posted with this input. It should related directly to a field name in $this->_DataArray.
return	string

input() public method

Returns the xhtml for a standard input tag.

public input ( string $FieldName, string $Type = 'text', array $Attributes = [] ) : string
$FieldName	string	The name of the field that is being displayed/posted with this input. It should related directly to a field name in $this->_DataArray.
$Type	string	The type attribute for the input.
$Attributes	array	An associative array of attributes for the input. (e.g. maxlength, onclick, class) Setting 'InlineErrors' to FALSE prevents error message even if $this->InlineErrors is enabled.
return	string

inputWrap() public method

public inputWrap ( $FieldName, $Type = 'text', $Attributes = [] )

isMyPostBack() public method

Just like IsPostBack(), except auto populates FormValues and doesnt just check "was some data submitted lol?!".

public isMyPostBack ( ) : boolean
return	boolean

isPostBack() public method

Examines the sent form variable collection to see if any data was sent via the form back to the server. Returns TRUE on if anything is found.

public isPostBack ( ) : boolean
return	boolean

label() public method

Returns XHTML for a label element.

public label ( string $TranslationCode, string $FieldName = '', array $Attributes = [] ) : string
$TranslationCode	string	Code to be translated and presented within the label tag.
$FieldName	string	Name of the field that the label is for.
$Attributes	array	Associative array of attributes for the input that the label is for. This is only available in case the related input has a custom id specified in the attributes array.
return	string

labelCode() public static method

Generate a friendly looking label translation code from a camel case variable name

public static labelCode ( string \| array $Item ) : string
$Item	string \| array	The item to generate the label from. - string: Generate the label directly from the item. - array: Generate the label from the item as if it is a schema row passed to Gdn_Form::Simple().
return	string

labelWrap() public method

public labelWrap ( $TranslationCode, $FieldName = '', $Attributes = [] )

linkButton() public method

Return a linked that will look like a button.

open() public method

Returns the xhtml for the opening of the form (the form tag and all hidden elements).

public open ( array $Attributes = [] ) : string
$Attributes	array	An associative array of attributes for the form tag. Here is a list of "special" attributes and their default values: Attribute Options Default ---------------------------------------- method get,post post action [any url] [The current url] ajax TRUE,FALSE FALSE
return	string

radio() public method

Provides way of wrapping Input() with a label.

public radio ( string $FieldName, string $Label = '', array $Attributes = [] ) : string
$FieldName	string	Name of the field that is being displayed/posted with this input. It should related directly to a field name in $this->_DataArray.
$Label	string	Label to place next to the radio.
$Attributes	array	Associative array of attributes for the input (e.g. onclick, class). Special values 'Value' and 'Default' (see RadioList).
return	string

radioList() public method

Returns XHTML for an unordered list of radio button elements.

public radioList ( string $FieldName, mixed $DataSet, array $Attributes = [] ) : string
$FieldName	string	The name of the field that is being displayed/posted with this input. It should related directly to a field name in $this->_DataArray. ie. RoleID
$DataSet	mixed	The data to fill the options in the select list. Either an associative array or a database dataset.
$Attributes	array	An associative array of attributes for the list. Here is a list of "special" attributes and their default values: Attribute Options Default ------------------------------------------------------------------------ ValueField The name of the field in 'value' $DataSet that contains the option values. TextField The name of the field in 'text' $DataSet that contains the option text. Value A string or array of strings. $this->_DataArray->$FieldName Default The default value. empty InlineErrors Show inline error message? TRUE Allows disabling per-dropdown for multi-fields like Date()
return	string

removeFormValue() public method

Remove an element from a form.

public removeFormValue ( string $FieldName )
$FieldName	string

save() public method

It uses the assigned model to save the sent form fields. If saving fails, it populates $this->_ValidationResults with validation errors & related fields.

public save ( ) : unknown
return	unknown

saveImage() public method

Save an image from a field and delete any old image that's been uploaded.

public saveImage ( string $Field, array $Options = [] )
$Field	string	The name of the field. The image will be uploaded with the _New extension while the current image will be just the field name.
$Options	array

searchForm() public method

Renders a search form.

public searchForm ( string $field, string $url, array $textBoxAttributes = [], string $searchInfo = '' ) : string
$field	string	The search field, supported field names are 'search' or 'Keywords'
$url	string	The url to show the search results.
$textBoxAttributes	array	The attributes for the text box. Placeholders go here.
$searchInfo	string	The info to add under the search box, usually a result count.
return	string	The rendered form.

searchInput() public method

Renders a stylized search field. Requires dashboard.css to look as intended. Use with searchForm() to output an entire search form.

public searchInput ( string $field, string $url, array $textBoxAttributes = [], string $searchInfo = '' ) : string
$field	string	The search field, supported field names are 'search' or 'Keywords'
$url	string	The url to show the search results.
$textBoxAttributes	array	The attributes for the text box. Placeholders go here.
$searchInfo	string	The info to add under the search box, usually a result count.
return	string	The rendered search field.

setData() public method

Assign a set of data to be displayed in the form elements.

public setData ( array $Data )
$Data	array	A result resource or associative array containing data to be filled in

setFormValue() public method

Essentially overwrites whatever was retrieved from the form.

public setFormValue ( string $FieldName, mixed $Value = null )
$FieldName	string	The name of the field to set the value of.
$Value	mixed	The new value of $FieldName.

setModel() public method

This value is also used to identify fields in the $_POST or $_GET (depending on the forms method) collection when the form is submitted.

public setModel ( Gdn_Model $Model, Ressource $DataSet = false )
$Model	Gdn_Model	The Model that will enforce data rules on $this->_DataArray. This value is passed by reference so any changes made to the model outside this object apply when it is referenced here.
$DataSet	Ressource	A result resource containing data to be filled in the form.

setStyles() public method

Set the styles to use when outputting controls.

public setStyles ( string $name ) : boolean
$name	string	The name of the style. Currently this should be legacy or bootstrap.
return	boolean	Returns true if the styles were set or false otherwise.

setValidationResults() public method

public setValidationResults ( $ValidationResults )
$ValidationResults

setValue() public method

It sets the value in $this->_DataArray rather than in $this->_FormValues.

public setValue ( string $FieldName, $Value )
$FieldName	string

showErrors() public method

Enable inline errors.

public showErrors ( )

simple() public method

Generates a multi-field form from a schema.

public simple ( array $Schema, type $Options = [] )
$Schema	array	An array where each item of the array is a row that identifies a form field with the following information: - Name: The name of the form field. - Control: The type of control used for the field. This is one of the control methods on the Gdn_Form object. - LabelCode: The translation code for the label. Optional. - Description: An optional description for the field. - Items: If the control is a list control then its items are specified here. - Options: Additional options to be passed into the control.
$Options	type	Additional options to pass into the form. - Wrap: A two item array specifying the text to wrap the form in. - ItemWrap: A two item array specifying the text to wrap each form item in.

textBox() public method

Returns the xhtml for a text-based input.

public textBox ( string $FieldName, array $Attributes = [] ) : string
$FieldName	string	The name of the field that is being displayed/posted with this input. It should related directly to a field name in $this->_DataArray.
$Attributes	array	An associative array of attributes for the input. ie. maxlength, onclick, class, etc
return	string

textBoxWrap() public method

public textBoxWrap ( $FieldName, $Attributes = [] )

toggle() public method

Outputs a checkbox painted as a toggle. Includes label wrap id a label is given.

public toggle ( string $fieldName, string $label, array $attributes = [], string $info = '' ) : string
$fieldName	string	The key name for the field.
$label	string	The label for the field.
$attributes	array	The attributes for the checkbox input.
$info	string	The label description.
return	string	And HTML-formatted form field for a toggle.

unescapeFieldName() public method

Replaces e.g. "\\" with "\", "\\-dot-" with "-dot-" and "-dot-" with ".".

validateModel() public method

ie. A sign-in form that just needs to compare data to the model and still enforce it's rules. Returns the number of errors that were recorded through validation.

public validateModel ( ) : integer
return	integer

validateRule() public method

Validates a rule on the form and adds its result to the errors collection.

See also: Gdn_Validation::ValidateRule()

public validateRule ( string $FieldName, string \| array $Rule, string $CustomError = '' ) : boolean
$FieldName	string	The name of the field to validate.
$Rule	string \| array	The rule to validate against.
$CustomError	string	A custom error string.
return	boolean	Whether or not the rule succeeded.

validationResults() public method

Gets the validation results in the form.

public validationResults ( ) : array
return	array

Property Details

$Action public_oe property

Action with which the form should be sent.

public $Action

$ErrorClass public_oe property

Class name to assign to form elements with errors when InlineErrors is enabled.

public $ErrorClass

$HiddenInputs public_oe property

Associative array of hidden inputs with their "Name" attribute as the key.

public $HiddenInputs

$IDPrefix public_oe property

All form-related elements (form, input, select, textarea, [etc] will have this value prefixed on their ID attribute. Default is "Form_". If the id value is overridden with the Attribute collection for an element, this value will not be used.

public $IDPrefix

$Method public_oe property

Form submit method. Options are 'post' or 'get'.

public $Method

$_DataArray protected_oe property

Associative array containing the key => value pairs being placed in the controls returned by this object. Assigned by $this->Open() or $this->SetData().

protected $_DataArray

$_FormValues public_oe property

public array $_FormValues
return	array

$_InlineErrors protected_oe property

Whether to display inline errors with form elements. Set with ShowErrors() and HideErrors().

protected $_InlineErrors

$_Model protected_oe property

Model that enforces data rules on $this->_DataArray.

protected $_Model

$_ValidationResults protected_oe property

Associative array of $FieldName => $ValidationFunctionName arrays that describe how each field specified failed validation.

protected $_ValidationResults

public escapeFieldName ( string $string ) : string
$string	string
return	string

public escapeString ( string $string ) : string
$string	string
return	string

public linkButton ( string $code, string $destination = '', array $attributes = [] )
$code	string	The text of the anchor.
$destination	string	The URL path of the anchor.
$attributes	array	Additional attributes for the anchor.

public unescapeFieldName ( string $string ) : string
$string	string
return	string