ValidForm Builder API Documentation

Textarea extends Element
in package

ValidForm

Create textarea html elements

TextArea objects are used to create textarea html elements.

Example; Add a basic textarea

$objForm->addField(
    "message",
    "Your Message",
    ValidForm::VFORM_TEXT,
    array(
        // Make this field required
        "required" => true
    ),
    array(
        // Error message when required state isn't met
        "required" => "This is a required field"
    ),
    array(
        "cols" => 20,
        "rows" => 10
    )
);

Methods

__call() : mixed: Magic caller method
__construct() : mixed: Create new Textarea object
__get() : mixed: Magic getter method
__getValue() : string|null: Get the value of the field.
__set() : mixed: Magic setter method
__toHtml() : string: Render a single field's HTML
addCondition() : mixed: Add a new condition to the current field
addField() : Element
getCondition() : Condition|null: Get element's Condition object
getConditionRecursive() : Condition|null: This gets the condition of a given property, just like {@see \ValidFormBuilder\Base::getCondition()}.
getConditions() : array<string|int, mixed>: Get the conditions collection
getData() : mixed: Get a value from the internal data array.
getDefault() : array<string|int, mixed>|string: Get default value
getDynamicButtonMeta() : mixed: This method determines wheter or not to show the 'add extra field' dynamic button based on it's parent's condition state.
getDynamicCount() : int: Get the number of dynamic fields from the dynamic counter field.
getDynamicLabelMate() : array<string|int, mixed>
getDynamicName() : string: Same as getName() except getDynamicName adds the current dynamic count to the fieldname as a suffix (_1, _2 etc)
getDynamicRemoveLabelMate() : array<string|int, mixed>
getFieldMeta() : mixed: Get field meta property.
getHint() : string
getId() : string
getLabel() : string
getLabelMeta() : string: Get label meta property.
getMagicMeta() : array<string|int, mixed>
getMagicReservedMeta() : array<string|int, mixed>
getMeta() : mixed: Get meta property.
getMetCondition() : null|Condition: Only get a condition of a given type if that condition is met. If the condition is not met, this returns null
getName() : string: Return the (original) name of the current field.
getParent() : Base
getRandomId() : string: Generate a random ID for a given field name to prevent having two fields with the same name
getRequiredStyle() : string
getReservedFieldMeta() : array<string|int, mixed>
getReservedLabelMeta() : array<string|int, mixed>
getReservedMeta() : array<string|int, mixed>
getShortLabel() : string: Get the short label (meta 'summaryLabel') if available.
getTip() : string
getTipMeta() : array<string|int, mixed>
getType() : int
getValidator() : FieldValidator
getValue() : mixed: Get the *valid* value of the current field.
hasCondition() : bool: Check if the current field contains a condition object of a specific type
hasConditions() : bool: Check if the current object contains any conditions at all.
hasFields() : bool: Placeholder function to determine wheter or not a field contains other fields.
isDynamic() : bool: Check if the current field is a dynamic field.
isDynamicCounter() : bool: Checks if this element is a dynamic counter for another element
isValid() : bool: Validate the current field.
setConditionalMeta() : mixed: Based on which conditions are met, corresponding metadata is set on the object.
setConditions() : void
setData() : bool: Store data in the current object.
setDefault() : mixed: Set default value on this element
setDynamicCounter() : mixed: Add a dynamic counter object
setDynamicLabelMeta() : mixed: Set dynamic label specific meta data
setDynamicRemoveLabelMeta() : mixed: Set dynamic remove label specific meta data
setError() : mixed: Set a (custom) error message on this specific element
setFieldMeta() : mixed: Set field specific meta data
setHint() : void
setId() : void
setLabel() : void
setLabelMeta() : mixed: Set label specific meta data
setMeta() : array<string|int, mixed>: Set meta property.
setName() : void
setParent() : void
setRequiredStyle() : void
setTip() : void
setTipMeta() : mixed: Set tip specific meta data
setType() : void
setValidator() : void
toHtml() : string: Render HTML
toJS() : string: Render javascript

__call()

Magic caller method


    public
                    __call(string $method, mixed $values) : mixed

Parameters

$method : string
$values : mixed

__construct()

Create new Textarea object


    public
                    __construct(mixed $name, mixed $type[, mixed $label = "" ][, mixed $validationRules = array() ][, mixed $errorHandlers = array() ][, mixed $meta = array() ]) : mixed

Parameters

$name : mixed: Field name
$type : mixed: Field type
$label : mixed = "": Field label
$validationRules : mixed = array(): Validation rules
$errorHandlers : mixed = array(): Error rules
$meta : mixed = array(): The meta array

__get()

Magic getter method


    public
                    __get(string $property) : mixed

Parameters

$property : string

__getValue()

Get the value of the field.


    public
                    __getValue([bool $submitted = false ][, int $intDynamicPosition = 0 ]) : string|null

If the value is valid then it will return that value, otherwise the invalid value is returned.

Parameters

$submitted : bool = false: Indicate if the form is submitted.
$intDynamicPosition : int = 0: The position of the field in a dynamic field setup.

Return values

string|null

__set()

Magic setter method


    public
                    __set(string $property, mixed $value) : mixed

Parameters

$property : string
$value : mixed

__toHtml()

Render a single field's HTML


    public
                    __toHtml([mixed $submitted = false ][, mixed $blnSimpleLayout = false ][, mixed $blnLabel = true ][, mixed $blnDisplayErrors = true ][, mixed $intCount = 0 ]) : string

Parameters

$submitted : mixed = false
$blnSimpleLayout : mixed = false
$blnLabel : mixed = true
$blnDisplayErrors : mixed = true
$intCount : mixed = 0

Return values

string

addCondition()

Add a new condition to the current field


    public
                    addCondition(string $strType, bool $blnValue, array<string|int, mixed> $arrComparisons[, string $intComparisonType = ValidForm::VFORM_MATCH_ANY ]) : mixed

For examples, check Condition

Parameters

$strType : string: Define the condition type. This can be either required, visibile or enabled
$blnValue : bool: Define whether this condition activates if the comparison(s) are true or false.
$arrComparisons : array<string|int, mixed>: An array of Comparison objects
$intComparisonType : string = ValidForm::VFORM_MATCH_ANY: The comparison type. Either ValidForm::VFORM_MATCH_ANY or ValidForm::VFORM_MATCH_ALL. With VFORM_MATCH_ANY, as soon as one of the comparisons validates the condition, the condition is enforced. With ValidForm::VFORM_MATCH_ALL, all of the comparisons must validate before the condition will be enforced.

addField()


    public
                    addField() : Element

addField($name, $type, $validationRules = array(), $errorHandlers = array(), $meta = array()) Adds another field to this field if this field is a container

Return values

Element

getCondition()

Get element's Condition object


    public
                    getCondition(string $strProperty) : Condition|null

Note: When chaining methods, always use hasCondition() first before chaining for example getCondition()->isMet().

Parameters

$strProperty : string: Condition type e.g. 'required', 'visibile' and 'enabled'

Return values

Condition|null —

Found condition or null if no condition is found.

getConditionRecursive()

This gets the condition of a given property, just like {@see \ValidFormBuilder\Base::getCondition()}.


    public
                    getConditionRecursive(string $strProperty[, Element $objContext = null ]) : Condition|null

When no condition is found on the current element, the method searches for a condition in it's parent element.

Parameters

$strProperty : string: Condition type e.g. required, visibile and enabled
$objContext : Element = null

Return values

Condition|null

getConditions()

Get the conditions collection


    public
                    getConditions() : array<string|int, mixed>

Return values

array<string|int, mixed>

getData()

Get a value from the internal data array.


    public
                    getData([string $strKey = null ]) : mixed

Parameters

$strKey : string = null: The key of the data attribute to return

getDefault()

Get default value


    public
                    getDefault() : array<string|int, mixed>|string

Return values

array<string|int, mixed>|string

getDynamicButtonMeta()

This method determines wheter or not to show the 'add extra field' dynamic button based on it's parent's condition state.


    public
                    getDynamicButtonMeta() : mixed

getDynamicCount()

Get the number of dynamic fields from the dynamic counter field.


    public
                    getDynamicCount([bool $blnParentIsDynamic = false ]) : int

Parameters

$blnParentIsDynamic : bool = false

Return values

int —

The dynamic count of this field

getDynamicLabelMate()


    public
                    getDynamicLabelMate() : array<string|int, mixed>

getDynamicLabelMate() Returns the value of $__dynamiclabelmeta

Return values

array<string|int, mixed>

getDynamicName()

Same as getName() except getDynamicName adds the current dynamic count to the fieldname as a suffix (_1, _2 etc)


    public
                    getDynamicName([int $intCount = 0 ]) : string

When the dynamic count === 0, the return value equals the output of getName()

Parameters

$intCount : int = 0: The dynamic count

Return values

string —

The field name

getDynamicRemoveLabelMate()


    public
                    getDynamicRemoveLabelMate() : array<string|int, mixed>

getDynamicRemoveLabelMate() Returns the value of $__dynamicremovelabelmeta

Return values

array<string|int, mixed>

getFieldMeta()

Get field meta property.


    public
                    getFieldMeta([string $property = null ][, string $fallbackValue = "" ]) : mixed

Parameters

$property : string = null: Property to get from internal field meta array.
$fallbackValue : string = "": Optional fallback value if no value is found for requested property

getHint()


    public
                    getHint() : string

getHint() Returns the value of $__hint

Return values

string

getId()


    public
                    getId() : string

getId() Returns the value of $__id

Return values

string

getLabel()


    public
                    getLabel() : string

getLabel() Returns the value of $__label

Return values

string

getLabelMeta()

Get label meta property.


    public
                    getLabelMeta([string $property = null ][, string $fallbackValue = "" ]) : string

Parameters

$property : string = null: Property to get from internal label meta array.
$fallbackValue : string = "": Optional fallback value if requested property has no value

Return values

string —

Property value or empty string of none is set.

getMagicMeta()


    public
                    getMagicMeta() : array<string|int, mixed>

getMagicMeta() Returns the value of $__magicmeta

Return values

array<string|int, mixed>

getMagicReservedMeta()


    public
                    getMagicReservedMeta() : array<string|int, mixed>

getMagicReservedMeta() Returns the value of $__magicreservedmeta

Return values

array<string|int, mixed>

getMeta()

Get meta property.


    public
                    getMeta([string $property = null ][, string $fallbackValue = "" ]) : mixed

Parameters

$property : string = null: Property to get from internal meta array.
$fallbackValue : string = "": Optional fallback value if requested property has no value

getMetCondition()

Only get a condition of a given type if that condition is met. If the condition is not met, this returns null


    public
                    getMetCondition(string $strProperty) : null|Condition

Parameters

$strProperty : string: Condition type e.g. 'required', 'visibile' and 'enabled'

Return values

null|Condition

getName()

Return the (original) name of the current field.


    public
                    getName() : string

Use getDynamicName() to get the field name + dynamic count

Return values

string —

The original field name

getParent()


    public
                    getParent() : Base

getParent() Returns the value of $__parent

Return values

Base

getRandomId()

Generate a random ID for a given field name to prevent having two fields with the same name


    public
                    getRandomId(string $name) : string

Parameters

$name : string: Field name

Return values

string

getRequiredStyle()


    public
                    getRequiredStyle() : string

getRequiredStyle() Returns the value of $__requiredstyle

Return values

string

getReservedFieldMeta()


    public
                    getReservedFieldMeta() : array<string|int, mixed>

getReservedFieldMeta() Returns the value of $__reservedfieldmeta

Return values

array<string|int, mixed>

getReservedLabelMeta()


    public
                    getReservedLabelMeta() : array<string|int, mixed>

getReservedLabelMeta() Returns the value of $__reservedlabelmeta

Return values

array<string|int, mixed>

getReservedMeta()


    public
                    getReservedMeta() : array<string|int, mixed>

getReservedMeta() Returns the value of $__reservedmeta

Return values

array<string|int, mixed>

getShortLabel()

Get the short label (meta 'summaryLabel') if available.


    public
                    getShortLabel() : string

Use the 'long' (regular) label as a fallback return value.

Return values

string —

The short or regular element label

getTip()


    public
                    getTip() : string

getTip() Returns the value of $__tip

Return values

string

getTipMeta()


    public
                    getTipMeta() : array<string|int, mixed>

getTipMeta() Returns the value of $__tipmeta

Return values

array<string|int, mixed>

getType()


    public
                    getType() : int

getType() Returns the value of $__type

Return values

int

getValidator()


    public
                    getValidator() : FieldValidator

getValidator() Returns the value of $__validator

Return values

FieldValidator

getValue()

Get the *valid* value of the current field.


    public
                    getValue([int $intDynamicPosition = 0 ]) : mixed

Parameters

$intDynamicPosition : int = 0: Optional parameter to get the value of a dynamic field.

Return values

mixed —

The valid value of this field. If validation fails, it returns null.

hasCondition()

Check if the current field contains a condition object of a specific type


    public
                    hasCondition(string $strProperty) : bool

Parameters

$strProperty : string: Condition type e.g. required, visibile and enabled

Return values

bool —

True if element has condition object set, false if not

hasConditions()

Check if the current object contains any conditions at all.


    public
                    hasConditions() : bool

Return values

bool —

True if it contains conditions, false if not.

hasFields()

Placeholder function to determine wheter or not a field contains other fields.


    public
                    hasFields() : bool

Return values

bool —

Return false by default.

isDynamic()

Check if the current field is a dynamic field.


    public
                    isDynamic() : bool

Return values

bool —

True if dynamic, false if not.

isDynamicCounter()

Checks if this element is a dynamic counter for another element


    public
                    isDynamicCounter() : bool

Return values

bool —

True if it is, false if not. Default false.

isValid()

Validate the current field.


    public
                    isValid([null $intCount = null ]) : bool

This is a wrapper method to call the Validator->validate() method. Although you could validate fields on a per-field basis with this method, this is mostly used internally. For instance, when ValidForm::validate() is called, it loops through its elements collection and calls this method for each element it finds.

Parameters

$intCount : null = null: Optional. If set, only the dynamic field with this index will be validated.

Return values

bool —

True if field validates, false if not.

setConditionalMeta()

Based on which conditions are met, corresponding metadata is set on the object.


    public
                    setConditionalMeta() : mixed

setConditions()


    public
                    setConditions() : void

setConditions(array $value) Overwrites the value of $__conditions

setData()

Store data in the current object.


    public
                    setData([string $strKey = null ][, mixed $varValue = null ]) : bool

This data will not be visibile in any output and will only be used for internal purposes. For example, you can store some custom data from your CMS or an other library in a field object, for later use.

Note: Using this method will overwrite any previously set data with the same key!

Parameters

$strKey : string = null: The key for this storage
$varValue : mixed = null: The value to store

Return values

bool —

True if set successful, false if not.

setDefault()

Set default value on this element


    public
                    setDefault(array<string|int, mixed>|string $varValue) : mixed

Parameters

$varValue : array<string|int, mixed>|string: The value to set as default value

setDynamicCounter()

Add a dynamic counter object


    public
                    setDynamicCounter(Element &$objCounter) : mixed

Parameters

$objCounter : Element

setDynamicLabelMeta()

Set dynamic label specific meta data


    public
                    setDynamicLabelMeta(string $property, mixed $value[, bool $blnOverwrite = false ]) : mixed

Parameters

$property : string: Property name.
$value : mixed: Property value.
$blnOverwrite : bool = false: Optionally use this boolean to force an overwrite of previous property value.

Return values

mixed —

The newly set value

setDynamicRemoveLabelMeta()

Set dynamic remove label specific meta data


    public
                    setDynamicRemoveLabelMeta(string $property, mixed $value[, bool $blnOverwrite = false ]) : mixed

Parameters

$property : string: Property name.
$value : mixed: Property value.
$blnOverwrite : bool = false: Optionally use this boolean to force an overwrite of previous property value.

Return values

mixed —

The newly set value

setError()

Set a (custom) error message on this specific element


    public
                    setError(string $strError[, int $intDynamicPosition = 0 ]) : mixed

This is mostly used when doing custom server-side validation like validating a username existance. Example:

if ($objForm->isSubmitted() && $objForm->isValid()) {
    $objUserNameField = $objForm->getValidField("username");
    $strUserName = $objUserNameField->getValue();
    if (User::exists($strUserName)) {
        $objUserNameField->setError("User already exists.");
        $strOutput = $objForm->toHtml();
    } else {
        $strOutput = "Account created successfully with the following details:<br />";
        $strOutput .= $objForm->valuesAsHtml();
    }
}

Parameters

$strError : string: The error message
$intDynamicPosition : int = 0: Set the error message on a specific dynamic field with this index

setFieldMeta()

Set field specific meta data


    public
                    setFieldMeta(string $property, mixed $value[, bool $blnOverwrite = false ]) : mixed

Parameters

$property : string: Property name.
$value : mixed: Property value.
$blnOverwrite : bool = false: Optionally use this boolean to force an overwrite of previous property value.

Return values

mixed —

The newly set value

setHint()


    public
                    setHint() : void

setHint(string $value) Overwrites the value of $__hint

setId()


    public
                    setId() : void

setId(string $value) Overwrites the value of $__id

setLabel()


    public
                    setLabel() : void

setLabel(string $value) Overwrites the value of $__label

setLabelMeta()

Set label specific meta data


    public
                    setLabelMeta(string $property, mixed $value[, bool $blnOverwrite = false ]) : mixed

Parameters

$property : string: Property name.
$value : mixed: Property value.
$blnOverwrite : bool = false: Optionally use this boolean to force an overwrite of previous property value.

Return values

mixed —

The newly set value

setMeta()

Set meta property.


    public
                    setMeta(string $property, mixed $value[, bool $blnOverwrite = false ]) : array<string|int, mixed>

Parameters

$property : string: Property name.
$value : mixed: Property value.
$blnOverwrite : bool = false: Optionally use this boolean to force an overwrite of previous property value.

Return values

array<string|int, mixed>

setName()


    public
                    setName() : void

setName(string $value) Overwrites the value of $__name

setParent()


    public
                    setParent() : void

setParent(Base $value) Overwrites the value of $__parent

setRequiredStyle()


    public
                    setRequiredStyle() : void

setRequiredStyle(string $value) Overwrites the value of $__requiredstyle

setTip()


    public
                    setTip() : void

setTip(string $value) Overwrites the value of $__tip

setTipMeta()

Set tip specific meta data


    public
                    setTipMeta(string $property, mixed $value[, bool $blnOverwrite = false ]) : mixed

Parameters

$property : string: Property name.
$value : mixed: Property value.
$blnOverwrite : bool = false: Optionally use this boolean to force an overwrite of previous property value.

Return values

mixed —

The newly set value

setType()


    public
                    setType() : void

setType(integer $value) Overwrites the value of $__type

setValidator()


    public
                    setValidator() : void

setValidator(FieldValidator $value) Overwrites the value of $__validator

toHtml()

Render HTML


    public
                    toHtml([mixed $submitted = false ][, mixed $blnSimpleLayout = false ][, mixed $blnLabel = true ][, mixed $blnDisplayErrors = true ]) : string

Parameters

$submitted : mixed = false: Force if this field should behave like a submitted field or not (e.g. validate etc.)
$blnSimpleLayout : mixed = false: Force 'simple layout' output -- no labels and wrapping divs.
$blnLabel : mixed = true: Show label. Don't show if false.
$blnDisplayErrors : mixed = true: Show errors (default true). Don't show errors if false.

Return values

string

toJS()

Render javascript


    public
                    toJS([mixed $intDynamicPosition = 0 ]) : string

Parameters

$intDynamicPosition : mixed = 0: Dynamic position counter

Return values

string

Textarea extends Element in package ValidForm

Example; Add a basic textarea

Tags

Table of Contents

Methods

Methods

__call()

Parameters

Tags

__construct()

Parameters

__get()

Parameters

Tags

__getValue()

Parameters

Return values

__set()

Parameters

Tags

__toHtml()

Parameters

Tags

Return values

addCondition()

Parameters

Tags

addField()

Return values

getCondition()

Parameters

Return values

getConditionRecursive()

Parameters

Return values

getConditions()

Return values

getData()

Parameters

getDefault()

Return values

getDynamicButtonMeta()

getDynamicCount()

Parameters

Return values

getDynamicLabelMate()

Return values

getDynamicName()

Parameters

Return values

getDynamicRemoveLabelMate()

Return values

getFieldMeta()

Parameters

getHint()

Return values

getId()

Return values

getLabel()

Return values

getLabelMeta()

Parameters

Return values

getMagicMeta()

Return values

getMagicReservedMeta()

Return values

getMeta()

Parameters

getMetCondition()

Parameters

Return values

getName()

Return values

getParent()

Return values

getRandomId()

Parameters

Return values

getRequiredStyle()

Textarea extends Element
in package

ValidForm