ValidForm Builder API Documentation

Area extends Base
in package

ValidForm

Group fields together in an Area

An area is about the same as a fieldset but an Area has more interactive options like the 'active' property or even the 'dynamic' meta.

An Area can be used to group form fields together. When an Area is active, it can toggle the disabled state on all it's child form fields using the auto-generated checkbox in the Area's legend.

Example; Active area

$objArea = $objForm->addArea("Disable fields", true, "fields-disabled");
$objArea->addField(
    "first-name",
    "First name",
    ValidForm::VFORM_STRING,
    array(
        // Make this field required
        "required" => true
    ),
    array(
        // Show this error to indicate this is an required field if no value is submitted
        "required" => "This field is required"
    )
);
$objArea->addField(
    "last-name",
    "Last name",
    ValidForm::VFORM_STRING,
    array(
        // Make this field required
        "required" => true
    ),
    array(
        // Show this error to indicate this is an required field if no value is submitted
        "required" => "This field is required"
    )
);

Example 2; Adding a string field to the area

$objArea = $objForm->addArea("Cool area");
$objArea->addField("first-name", "First name", ValidForm::VFORM_STRING);

Example 3; Addding a paragraph to the Area

$objArea->addParagraph(
    "Cool paragraph with lots of text in it. It's an absolute must-read.",
    "You must read this"
);

Methods

__call() : mixed: Magic caller method
__construct() : mixed: Create a new Area instance
__get() : mixed: Magic getter method
__set() : mixed: Magic setter method
addCondition() : mixed: Add a new condition to the current field
addField() : null|Element: Add a field to the Area.
addMultiField() : MultiField: Add a multifield to the Area
addParagraph() : Paragraph: Add paragraph to Area
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.
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 dynamic counter value if this is an dynamic area.
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.
getFields() : Collection: Return all children in a Collection
getId() : string: Return the Area name
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
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.
getTipMeta() : array<string|int, mixed>
getType() : number: For API compatibility, we've added the placeholder method 'getType'
getValue() : bool: If this is an active area, this will return the value of the checkbox.
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.
hasContent() : bool: Verify if any of the child fields in this area has submitted data
hasFields() : bool: Check if this area contains child objects.
isActive() : bool: Check if this is an active area
isDynamic() : bool: Check if the current field is a dynamic field.
isValid() : bool: Verify if all submitted data of this area and it's children is valid.
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.
setDynamicLabelMeta() : mixed: Set dynamic label specific meta data
setDynamicRemoveLabelMeta() : mixed: Set dynamic remove label specific meta data
setFieldMeta() : mixed: Set field specific meta data
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
setTipMeta() : mixed: Set tip specific meta data
toHtml() : string: Render the Area and it's children with toHtml()
toJS() : string: Generate Javascript code.

__call()

Magic caller method


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

Parameters

$method : string
$values : mixed

__construct()

Create a new Area instance


    public
                    __construct(string $label[, bool $active = false ][, string $name = null ][, bool $checked = false ][, array<string|int, mixed> $meta = array() ]) : mixed

The label is used as a small 'header' above the area. When setting an area to 'active', this label becomes clickable using a checkbox. This clickable header can toggle child fields to be enabled / disabled.

Parameters

$label : string: The Area's label
$active : bool = false: Whether the area should be active or not. When active, a checkbox will be prefixed to the header.
$name : string = null: The name for this area
$checked : bool = false: Whether or not the active area should be checked by default
$meta : array<string|int, mixed> = array(): The optional meta array

__get()

Magic getter method


    public
                    __get(string $property) : mixed

Parameters

$property : string

__set()

Magic setter method


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

Parameters

$property : string
$value : mixed

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()

Add a field to the Area.


    public
                    addField(string $name, string $label, int $type[, array<string|int, mixed> $validationRules = array() ][, array<string|int, mixed> $errorHandlers = array() ][, array<string|int, mixed> $meta = array() ]) : null|Element

See Area near the top of the page for an example

Parameters

$name : string
$label : string
$type : int: One of the ValidForm::VFORM_ field types
$validationRules : array<string|int, mixed> = array(): Standard validation rules array
$errorHandlers : array<string|int, mixed> = array(): Standard error handler array
$meta : array<string|int, mixed> = array(): Standard meta array

Return values

null|Element —

Returns an instance of the field type generated

addMultiField()

Add a multifield to the Area


    public
                    addMultiField([string $label = null ][, array<string|int, mixed> $meta = array() ]) : MultiField

Parameters

$label : string = null: The multifield's label
$meta : array<string|int, mixed> = array(): The standard meta array

Return values

MultiField

addParagraph()

Add paragraph to Area


    public
                    addParagraph(string $strBody[, string $strHeader = "" ][, array<string|int, mixed> $meta = array() ]) : Paragraph

Example

$objArea->addParagraph(
    "Cool paragraph with lots of text in it. It's an absolute must-read.",
    "You must read this"
);

Parameters

$strBody : string: The paragraph's body text
$strHeader : string = "": The paragraph's optional header
$meta : array<string|int, mixed> = array(): Standard meta array

Return values

Paragraph

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

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 dynamic counter value if this is an dynamic area.


    public
                    getDynamicCount() : int

Return values

int —

Defaults to 0 if not an dynamic area. If dynamic, this returns the number of times the user duplicated this area.

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

getFields()

Return all children in a Collection


    public
                    getFields() : Collection

Return values

Collection

getId()

Return the Area name


    public
                    getId() : string

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

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

getTipMeta()


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

getTipMeta() Returns the value of $__tipmeta

Return values

array<string|int, mixed>

getType()

For API compatibility, we've added the placeholder method 'getType'


    public
                    getType() : number

Return values

number

getValue()

If this is an active area, this will return the value of the checkbox.


    public
                    getValue([string $intCount = null ]) : bool

Parameters

$intCount : string = null: Dynamic counter, defaults to null

Return values

bool

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.

hasContent()

Verify if any of the child fields in this area has submitted data


    public
                    hasContent([int $intCount = 0 ]) : bool

Parameters

$intCount : int = 0: Optional counter to do the same for dynamic multifields.

Return values

bool —

True if area childs contain submitted data, false if not.

hasFields()

Check if this area contains child objects.


    public
                    hasFields() : bool

Return values

bool —

True if fields collection > 0, false if not.

isActive()

Check if this is an active area


    public
                    isActive() : bool

Return values

bool

isDynamic()

Check if the current field is a dynamic field.


    public
                    isDynamic() : bool

Return values

bool —

True if dynamic, false if not.

isValid()

Verify if all submitted data of this area and it's children is valid.


    public
                    isValid() : bool

Return values

bool

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.

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

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

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

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

toHtml()

Render the Area and it's children with toHtml()


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

Parameters

$submitted : bool = false: Define if the area has been submitted and propagate that flag to the child fields
$blnSimpleLayout : bool = false: Only render in simple layout mode
$blnLabel : bool = true
$blnDisplayErrors : bool = true: Display generated errors

Return values

string —

Rendered Area

toJS()

Generate Javascript code.


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

See Base::toJS()

Parameters

$intDynamicPosition : int = 0: The dynamic position counter

Return values

string —

Generated javascript code

Area extends Base in package ValidForm

Example; Active area

Example 2; Adding a string field to the area

Example 3; Addding a paragraph to the Area

Tags

Table of Contents

Methods

Methods

__call()

Parameters

Tags

__construct()

Parameters

__get()

Parameters

Tags

__set()

Parameters

Tags

addCondition()

Parameters

Tags

addField()

Parameters

Return values

addMultiField()

Parameters

Return values

addParagraph()

Example

Parameters

Return values

getCondition()

Parameters

Return values

getConditionRecursive()

Parameters

Return values

getConditions()

Return values

getData()

Parameters

getDynamicButtonMeta()

getDynamicCount()

Return values

getDynamicLabelMate()

Return values

getDynamicName()

Parameters

Return values

getDynamicRemoveLabelMate()

Return values

getFieldMeta()

Parameters

getFields()

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

getRequiredStyle()

Return values

getReservedFieldMeta()

Return values

Area extends Base
in package

ValidForm