Docs For Class FormElement

FormElement __construct(
String
$name, [String
$id = ''])

General abstract, hidden formelement constructor.

Initializes basic form values. Must be called at the beginning of specialized element constructors.

Tags:

access:

protected

Overridden in child classes as:

AlignBlock::__construct(): Hidden constructor.

CustomHtml::__construct(): Hidden constructor.

FieldSet::__construct(): Hidden constructor.

InputButton::__construct(): Hidden constructor.

InputReset::__construct(): Hidden constructor.

InputCheckbox::__construct(): Hidden constructor.

InputHidden::__construct(): Hidden constructor.

InputRadio::__construct(): Hidden constructor.

InputSubmit::__construct(): Hidden constructor.

InputImage::__construct(): Hidden constructor.

InputText::__construct(): Hidden constructor.

InputFile::__construct(): Hidden constructor.

InputPassword::__construct(): Hidden constructor.

JsDateTime::__construct(): Hidden constructor.

Label::__construct(): Hidden constructor.

Select::__construct(): Hidden constructor.

TextArea::__construct(): Hidden constructor.

Parameters:

String	$name	internal name of the element (also html-name if one is needed)
String	$id	html-id of the element

[ Top ]

FormElement addCssClasses(
String
$cssClasses)

Adds one or many css-classes to the element's class-attribute.

This is simple string concatenation. You don't have to leave a blank at the start of the string to add.

Tags:

return:	method owner
access:	public

Parameters:

String

$cssClasses

the classes-string to add to the current one

[ Top ]

FormElement addElement(
FormElement
$element)

Adds a subelement to the element.

Is available but won't do anything for elements that have no container character.

Tags:

return:	method owner
access:	public

Parameters:

FormElement

$element

the element to add to the subelements

[ Top ]

Array[String] determineRefiller(
[Array[String]|null
$refiller = array()])

Returns the supposed source of refill values.

Either the provided array will be taken, or the method tries to determine the element's data source by the method of the masterform. If that fails the refiller defaults to $_POST. For internal use. Doesn't need to be overwritten or extended.

Tags:

return:	refill source for element
access:	protected

Parameters:

Array[String]|null

$refiller

predetermined refill source for element

[ Top ]

void doRender(
)

Returns the compiled html-code for the element.

Has to be implemented by specialized classes. Use the protected print-methods of this class to make life easier for you.

Tags:

abstract:
access:	public

Overridden in child classes as:

AlignBlock::doRender(): Compiles and returns the html-fragment for the element including all subelements.

CustomHtml::doRender(): Compiles and returns the html-fragment for the element.

FieldSet::doRender(): Compiles and returns the html-fragment for the element including all subelements.

InputButton::doRender(): Compiles and returns the html-fragment for the element.

InputReset::doRender(): Compiles and returns the html-fragment for the element.

InputCheckbox::doRender(): Compiles and returns the html-fragment for the element.

InputHidden::doRender(): Compiles and returns the html-fragment for the element.

InputRadio::doRender(): Compiles and returns the html-fragment for the element.

InputSubmit::doRender(): Compiles and returns the html-fragment for the element.

InputImage::doRender(): Compiles and returns the html-fragment for the element.

InputText::doRender(): Compiles and returns the html-fragment for the element.

InputFile::doRender(): Compiles and returns the html-fragment for the element.

InputPassword::doRender(): Compiles and returns the html-fragment for the element.

JsDateTime::doRender(): Compiles and returns the html-fragment for the element.

Label::doRender(): Compiles and returns the html-fragment for the element.

Select::doRender(): Compiles and returns the html-fragment for the element.

SelectList::doRender(): Compiles and returns the html-fragment for the element.

TextArea::doRender(): Compiles and returns the html-fragment for the element.

[ Top ]

String getId(
)

Return the element's html-id.

Tags:

return:	the element's html-id
access:	public

[ Top ]

String getLabel(
)

Return the element's label text.

Tags:

return:	the element's label text
access:	public

[ Top ]

FormElement getMasterElement(
)

Return the currently connected owner element for the element.

Tags:

return:	the element's owner element or null
access:	public

[ Top ]

HtmlForm getMasterForm(
)

Returns the currently connected owner form for the element.

Tags:

return:	the element's owner form or null
access:	public

[ Top ]

String getName(
)

Return the element's html-name.

Tags:

return:	the element's html-name
access:	public

[ Top ]

Array[FormElement] getSubElements(
)

Return all owned elements of this element.

Tags:

return:	all elements owned by this element
access:	public

[ Top ]

String getTitle(
)

Return the element's html-title.

Tags:

return:	the element's html-title
access:	public

[ Top ]

FormValidator getValidator(
)

Return the currently connected validator for the element.

Tags:

return:	the element's validator or null
access:	public

[ Top ]

null/String/Array[String] getValue(
)

Returns the value of the element if there is any.

Has to be implemented by all form elements.

Tags:

return:	the value the element provides in the implementation
abstract:
access:	public

Overridden in child classes as:

AlignBlock::getValue(): Since AlignBlock doesn't hold any value, this method will always return null.

CustomHtml::getValue(): Since CustomHtml doesn't hold any value, this method will always return null.

FieldSet::getValue(): Since FieldSet doesn't hold any value, this method will always return null.

InputButton::getValue(): Since InputButton doesn't hold any value, this method will always return null.

InputCheckbox::getValue(): Returns the current value of the element.

InputHidden::getValue(): Returns the currently set value of the element.

InputRadio::getValue(): Returns the current value of the element.

InputSubmit::getValue(): Returns if the submit-button was used for the last occurred form-submit.

InputImage::getValue(): Returns if the image_submit-button was used for the last occurred form-submit.

InputText::getValue(): Returns the current value of the element.

InputFile::getValue(): Returns the current value of the element.

Label::getValue(): Since Label doesn't hold any value, this method will always return null.

Select::getValue(): Returns the current value of the element.

TextArea::getValue(): Returns the current value of the element.

[ Top ]

FormValueSet getValueSet(
[
$addedSet = null])

Returns the compiled valueset for this element including the elements owned by this one.

Tags:

return:	the comiled valueset of this element and its descendants
see:	FormValueSet
access:	public

Parameters:

FormValueSet

$addedSet

a valueset to start with instead of an empty one

[ Top ]

FormElement insertElementAfter(
String
$targetElementName, FormElement
$element)

Searches the subelements of the element if present and inserts a given element after the first found one.

This method doesn't add an element right behind the element itself, but inserts one into the subelements if a match is found.

This method is available, but doesn't do anything for elements that have no container character.

Tags:

return:	method owner
access:	public

Parameters:

String	$targetElementName	the name of the subelement to search for
FormElement	$element	the element to insert into the subelements behind the found one

[ Top ]

Boolean isValid(
)

Answers if the element is in a valid state at the moment.

Per default an element is always valid, if a validator is added it can't be valid until it has been validated according to the rules of the validator.

Tags:

return:	yes/no answer
access:	public

[ Top ]

Boolean needsUtf8Safety(
)

Answers if the element needs to be treated with precautions according to possible utf-8 values.

This value is completely derived from the masterform if present, otherwise the value will be treated as utf-8 for security reasons.

Tags:

return:	yes/no answer
access:	protected

[ Top ]

String printCssClasses(
)

Compiles the html-class-attribute-string of the element.

Auto-includes an error-class if element is found invalid.

Tags:

return:	compiled attribute-string
access:	protected

[ Top ]

String printDisabled(
)

Compiles the html-disabled-attribute-string of the element.

Tags:

return:	compiled attribute-string
access:	protected

[ Top ]

String printId(
)

Compiles the html-id-attribute-string of the element.

Tags:

return:	compiled attribute-string
access:	protected

[ Top ]

String printJavascriptEventHandler(
)

Compiles html-javascript-eventhandler-string of the element.

Tags:

return:	compiled attribute-string
access:	protected

[ Top ]

String printJavascriptValidationCode(
)

Grabs the compiled JS-validation-code for the element from its validator, if present and returns the code as a string.

Tags:

return:	JS-code to validate the element's values on the fly
access:	public

[ Top ]

String printMessages(
[Boolean
$onlyCustomMessages = false])

Returns a string of all aggregated error messages of the element.

Makes only sense after a validation process took place.

Tags:

return:	aggregated error-message-string
access:	public

Parameters:

Boolean

$onlyCustomMessages

defines that only custom messages should be considered

[ Top ]

String printName(
)

Compiles the html-name-string of the element.

Tags:

return:	compiled attribute-string
access:	protected

[ Top ]

String printNameArray(
)

Comiles the html-name-string of the element, if the element is part of a group of values.

Tags:

return:	compiled attribute-string
access:	protected

[ Top ]

unit printTabIndex(
)

Calculates current ongoing tabindex of the form, refreshes it and returns the proper value for the element.

Tags:

return:	tabindex of the element
access:	protected

[ Top ]

String printTitle(
)

Compiles the html-title-string of the element.

Tags:

return:	compiled attribute-string
access:	protected

[ Top ]

String printWrapperClasses(
)

Compiles a string of all classes for the tag-wrapper for the element's html-code.

Auto-includes an error-class if element is found invalid and error marking is set to full.

Tags:

return:	compiled wrapper classes
access:	protected

[ Top ]

FormElement setCssClasses(
String
$cssClasses)

Sets the html-class-attribute for the element.

Use exactly the same notation you would use in html.

Tags:

return:	method owner
access:	public

Parameters:

String

$cssClasses

css-classes-string to use for the element

[ Top ]

FormElement setDisabled(
)

Set the element disabled.

Tags:

return:	method owner
access:	public

Overridden in child classes as:

InputCheckbox::setDisabled(): Set the element disabled, or set single options disabled.

InputRadio::setDisabled(): Set the element disabled, or set single options disabled.

Select::setDisabled(): Set the element disabled, or set single options disabled.

[ Top ]

FormElement setId(
String
$id)

Sets the html-id for this element.

Tags:

return:	method owner
access:	public

Parameters:

String

$id

html-id to use for this element

[ Top ]

FormElement setJavascriptEventHandler(
String
$handler, String
$reaction)

Sets a javascript-handler for the element.

If you want to use such things as "onchange" or "onclick", you can set that with this method. At the moment only one handler per element is allowed, because this is supposed to be a comfortable way of inserting little quirks and not a programming interface. If you need to do complicated things, use raw javascript or jquery and reference the element by a fitting selector.

Tags:

return:	method owner
access:	public

Parameters:

String	$handler	the handler attribute
String	$reaction	the javascript-code to execute if handler fires

[ Top ]

FormElement setLabel(
string
$label)

Inserts a label for the element.

This is not a label in the html-sense, but to be seen as a description for the purpose of the element. The label is rendered into an own tag before the widget.

Tags:

return:	method owner
see:	Label
access:	public

Parameters:

string

$label

text to display in the element-label

[ Top ]

FormElement setMasterElement(
FormElement
$master)

Sets the owning element for an element.

Some elements can contain others, allowing a tree structure of the form object. Every element eventually knows the form it is in, but additionally knows which element contains it, if it is not directly put into the form. For internal use. Use element->addElement() instead.

Tags:

return:	method owner
access:	public

Parameters:

FormElement

$master

the formelement to set as owner of the element

[ Top ]

FormElement setMasterForm(

$master)

Sets the owning form for an element and by doing so inserts the element into the logical structure of the form.

For internal use. Use form->addElement() instead.

Tags:

return:	method owner
access:	public

Parameters:

HtmlForm

$master

the form this element belongs to

[ Top ]

FormElement setTitle(
String
$title)

Sets the html-title for this element.

Tags:

return:	method owner
access:	public

Parameters:

String

$title

html-title to use for this element

[ Top ]

FormElement setUsable(
Boolean
$expression)

Set the element usables or disabled based on an expression.

Tags:

return:	method owner
access:	public

Parameters:

Boolean

$expression

boolean expression to determine if element is usable

[ Top ]

FormElement setValidator(

$validator)

Sets a validator for a value-bearing element.

By doing so you render the element invalid by default. To get it valid again you have to validate the form it is in or the element itself. A validator can be set up with a set of rules for the value of the element. If one of those rules is broken the element is treated as being invalid.

Tags:

return:	method owner
see:	FormValidator
access:	public

Parameters:

FormValidator

$validator

the validator holding the rules to validate the elements value(s)

[ Top ]

Boolean validate(
)

Starts validation for the element and all subelements according to the rules laid out in the element's validator.

Calculates the compiled validity-state for the element and all descendants recursively. After this call, isValid() always returns the correct calculated state.

If element has no masterform at the moment of call the validators work on default settings.

This method must be overwritten in specialized classes and called at the beginning of the overwriting method.

Tags:

return:	element is valid yes/no
access:	public

Overridden in child classes as:

InputCheckbox::validate(): Starts the validation-process for the element.

InputHidden::validate(): Starts the validation-process for the element.

InputRadio::validate(): Starts the validation-process for the element.

InputText::validate(): Starts the validation-process for the element.

Select::validate(): Starts the validation-process for the element.

TextArea::validate(): Starts the validation-process for the element.

[ Top ]

Class: FormElement

Class Overview

Author(s):

Version:

Variables

Constants

Methods

Child classes:

Class Details

Tags:

Class Variables

$cssClasses =

Tags:

$disabled =

Tags:

$id =

Tags:

$isValid =

Tags:

$jsEventHandler =

Tags:

$label =

Tags:

$masterElement =

Tags:

$masterForm =

Tags:

$name =

Tags:

$subElements =

Tags:

$title =

Tags:

$validator =

Tags:

Class Methods

constructor __construct [line 160]

Tags:

Parameters:

method addCssClasses [line 532]

Tags:

Parameters:

method addElement [line 546]

Tags:

Parameters:

method determineRefiller [line 593]

Tags:

Parameters:

method doRender [line 799]

Tags:

method getId [line 376]

Tags:

method getLabel [line 409]

Tags:

method getMasterElement [line 354]

Tags:

method getMasterForm [line 343]

Tags:

method getName [line 387]

Tags:

method getSubElements [line 420]

Tags:

method getTitle [line 398]

Tags:

method getValidator [line 365]

Tags:

method getValue [line 458]

Tags:

method getValueSet [line 433]

Tags:

Parameters:

method insertElementAfter [line 567]

Tags:

Parameters:

method isValid [line 472]

Tags:

method needsUtf8Safety [line 485]

Tags:

method printCssClasses [line 659]

Tags: