Form/Element.php

Show:

inherited

Classes
- \Zend_Form_Element

Table of Contents

Zend Framework

LICENSE

This source file is subject to the new BSD license that is bundled with this package in the file LICENSE.txt. It is also available through the world-wide-web at this URL: http://framework.zend.com/license/new-bsd If you did not receive a copy of the license and are unable to obtain it through the world-wide-web, please send an email to [email protected] so we can send you a copy immediately.

Category: Zend
Copyright: Copyright (c) 2005-2012 Zend Technologies USA Inc. (http://www.zend.com)
License: New BSD License
Package: Zend_Form

\Zend_Form_Element
jump to top

Package: Zend\Form\Element

Zend_Form_Element

Implements: \Zend_Validate_Interface
Children: \Zend_Dojo_Form_Element_Dijit; \Zend_Form_Element_Xhtml
Category: Zend
Copyright: Copyright (c) 2005-2012 Zend Technologies USA Inc. (http://www.zend.com)
License: New BSD License
Version: $Id: Element.php 25173 2012-12-22 20:05:32Z rob $

Constants

 
                DECORATOR
                = 'DECORATOR'

Element Constants

 
                FILTER
                = 'FILTER'

 
                VALIDATE
                = 'VALIDATE'

Properties

bool $_allowEmpty = true

'Allow empty' flag

Default valuetrueDetails

Type: bool

bool $_autoInsertNotEmptyValidator = true

Flag indicating whether or not to insert NotEmpty validator when element is required

Default valuetrueDetails

Type: bool

string $_belongsTo =

Array to which element belongs

Details

Type: string

array $_decorators = array()

Element decorators

Default valuearray()Details

Type: array

string $_description =

Element description

Details

Type: string

bool $_disableLoadDefaultDecorators = false

Should we disable loading the default decorators?

Default valuefalseDetails

Type: bool

string $_errorMessageSeparator = '; '

Separator to use when concatenating aggregate error messages (for elements having array values)

Default value'; 'Details

Type: string

array $_errorMessages = array()

Custom error messages

Default valuearray()Details

Type: array

array $_errors = array()

Validation errors

Default valuearray()Details

Type: array

array $_filters = array()

Element filters

Default valuearray()Details

Type: array

bool $_ignore = false

Ignore flag (used when retrieving values at form level)

Default valuefalseDetails

Type: bool

bool $_isArray = false

Does the element represent an array?

Default valuefalseDetails

Type: bool

bool $_isError = false

Is the error marked as in an invalid state?

Default valuefalseDetails

Type: bool

bool $_isErrorForced = false

Has the element been manually marked as invalid?

Default valuefalseDetails

Type: bool

bool $_isPartialRendering = false

Is a specific decorator being rendered via the magic renderDecorator()?

This is to allow execution of logic inside the render() methods of child elements during the magic call while skipping the parent render() method.

Default valuefalseDetails

Type: bool

string $_label =

Element label

Details

Type: string

array $_loaders = array()

Plugin loaders for filter and validator chains

Default valuearray()Details

Type: array

array $_messages = array()

Formatted validation error messages

Default valuearray()Details

Type: array

string $_name =

Element name

Details

Type: string

int $_order =

Order of element

Details

Type: int

bool $_required = false

Required flag

Default valuefalseDetails

Type: bool

\Zend_Translate $_translator =

Details

Type: \Zend_Translate

bool $_translatorDisabled = false

Is translation disabled?

Default valuefalseDetails

Type: bool

string $_type =

Element type

Details

Type: string

array $_validatorRules = array()

Array of un-initialized validators

Default valuearray()Details

Type: array

array $_validators = array()

Array of initialized validators

<p>Validators</p>

Default valuearray()Details

Type: array

mixed $_value =

Element value

Details

Type: mixed

\Zend_View_Interface $_view =

Details

Type: \Zend_View_Interface

string $helper = 'formText'

Default view helper to use

Default value'formText'Details

Type: string

Methods

__call(string $method, array $args) : string

Overloading: allow rendering specific decorators

Call renderDecoratorName() to render a specific decorator.

Parameters

Name	Type	Description
$method	string
$args	array

Returns

Type	Description
string

Throws

Exception	Description
\Zend_Form_Exception	for invalid decorator or invalid method call

__construct(string | array | \Zend_Config $spec, array | \Zend_Config $options = null) : void

Constructor

$spec may be: - string: name of element - array: options with which to configure element - Zend_Config: Zend_Config with options for configuring element

Parameters

Name	Type	Description
$spec	string \| array \| \Zend_Config
$options	array \| \Zend_Config

Throws

Exception	Description
\Zend_Form_Exception	if no element name after initialization

__get(string $key) : mixed

Overloading: retrieve object property

Prevents access to properties beginning with '_'.

Parameters

Name	Type	Description
$key	string

Returns

Type	Description
mixed

__set(string $key, mixed $value) : \voide

Overloading: set object property

Parameters

Name	Type	Description
$key	string
$value	mixed

Returns

Type	Description
\voide

__toString() : string

String representation of form element

Proxies to render().

Returns

Type	Description
string

_filterValue(string $value, string $key) : void

Filter a value

Parameters

Name	Type	Description
$value	string
$key	string

_getDecorator(string $name, null | array $options) : \Zend_Form_Decorator_Interface

Instantiate a decorator based on class name or class name fragment

Parameters

Name	Type	Description
$name	string
$options	null \| array

Returns

Type	Description
\Zend_Form_Decorator_Interface

_getErrorMessages() : array

Retrieve error messages and perform translation and value substitution

Returns

Type	Description
array

_hasErrorMessages() : bool

Are there custom error messages registered?

Returns

Type	Description
bool

_loadDecorator(array $decorator, mixed $name) : \Zend_Form_Decorator_Interface

Lazy-load a decorator

Parameters

Name	Type	Description
$decorator	array	Decorator type and options
$name	mixed	Decorator name or alias

Returns

Type	Description
\Zend_Form_Decorator_Interface

_loadFilter(array $filter) : \Zend_Filter_Interface

Lazy-load a filter

Parameters

Name	Type	Description
$filter	array

Returns

Type	Description
\Zend_Filter_Interface

_loadValidator(array $validator) : \Zend_Validate_Interface

Lazy-load a validator

Parameters

Name	Type	Description
$validator	array	Validator definition

Returns

Type	Description
\Zend_Validate_Interface

addDecorator(string | \Zend_Form_Decorator_Interface $decorator, array | \Zend_Config $options = null) : \Zend_Form_Element

Add a decorator for rendering the element

Parameters

Name	Type	Description
$decorator	string \| \Zend_Form_Decorator_Interface
$options	array \| \Zend_Config	Options with which to initialize decorator

Returns

Type	Description
\Zend_Form_Element

addDecorators(array $decorators) : \Zend_Form_Element

Add many decorators at once

Parameters

Name	Type	Description
$decorators	array

Returns

Type	Description
\Zend_Form_Element

addError(string $message) : \Zend_Form_Element

Add an error message and mark element as failed validation

Parameters

Name	Type	Description
$message	string

Returns

Type	Description
\Zend_Form_Element

addErrorMessage(string $message) : \Zend_Form_Element

Add a custom error message to return in the event of failed validation

Parameters

Name	Type	Description
$message	string

Returns

Type	Description
\Zend_Form_Element

addErrorMessages(array $messages) : \Zend_Form_Element

Add multiple custom error messages to return in the event of failed validation

Parameters

Name	Type	Description
$messages	array

Returns

Type	Description
\Zend_Form_Element

addErrors(array $messages) : \Zend_Form_Element

Add multiple error messages and flag element as failed validation

Parameters

Name	Type	Description
$messages	array

Returns

Type	Description
\Zend_Form_Element

addFilter(string | \Zend_Filter_Interface $filter, $options = array()) : \Zend_Form_Element

Add a filter to the element

Parameters

Name	Type	Description
$filter	string \| \Zend_Filter_Interface
$options

Returns

Type	Description
\Zend_Form_Element

addFilters(array $filters) : \Zend_Form_Element

Add filters to element

Parameters

Name	Type	Description
$filters	array

Returns

Type	Description
\Zend_Form_Element

addPrefixPath(string $prefix, string $path, string $type = null) : \Zend_Form_Element

Add prefix path for plugin loader

If no $type specified, assumes it is a base path for both filters and validators, and sets each according to the following rules: - decorators: $prefix = $prefix . '_Decorator' - filters: $prefix = $prefix . '_Filter' - validators: $prefix = $prefix . '_Validate'

Otherwise, the path prefix is set on the appropriate plugin loader.

Parameters

Name	Type	Description
$prefix	string
$path	string
$type	string

Returns

Type	Description
\Zend_Form_Element

Throws

Exception	Description
\Zend_Form_Exception	for invalid type

addPrefixPaths(array $spec) : \Zend_Form_Element

Add many prefix paths at once

Parameters

Name	Type	Description
$spec	array

Returns

Type	Description
\Zend_Form_Element

addValidator(string | \Zend_Validate_Interface $validator, bool $breakChainOnFailure = false, array $options = array()) : \Zend_Form_Element

Add validator to validation chain

Note: will overwrite existing validators if they are of the same class.

Parameters

Name	Type	Description
$validator	string \| \Zend_Validate_Interface
$breakChainOnFailure	bool
$options	array

Returns

Type	Description
\Zend_Form_Element

Throws

Exception	Description
\Zend_Form_Exception	if invalid validator type

addValidators(array $validators) : \Zend_Form_Element

Add multiple validators

Parameters

Name	Type	Description
$validators	array

Returns

Type	Description
\Zend_Form_Element

autoInsertNotEmptyValidator() : bool

Get flag indicating whether a NotEmpty validator should be inserted when element is required

Returns

Type	Description
bool

clearDecorators() : \Zend_Form_Element

Clear all decorators

Returns

Type	Description
\Zend_Form_Element

clearErrorMessages() : \Zend_Form_Element

Clear custom error messages stack

Returns

Type	Description
\Zend_Form_Element

clearFilters() : \Zend_Form_Element

Clear all filters

Returns

Type	Description
\Zend_Form_Element

clearValidators() : \Zend_Form_Element

Clear all validators

Returns

Type	Description
\Zend_Form_Element

filterName(string $value, bool $allowBrackets = false) : string

Filter a name to only allow valid variable characters

Parameters

Name	Type	Description
$value	string
$allowBrackets	bool

Returns

Type	Description
string

getAllowEmpty() : bool

Get 'allow empty' flag

Returns

Type	Description
bool

getAttrib(string $name) : string

Retrieve element attribute

Parameters

Name	Type	Description
$name	string

Returns

Type	Description
string

getAttribs() : array

Return all attributes

Returns

Type	Description
array

getBelongsTo() : string

Return array name to which element belongs

Returns

Type	Description
string

getDecorator(string $name) : false | \Zend_Form_Decorator_Abstract

Retrieve a registered decorator

Parameters

Name	Type	Description
$name	string

Returns

Type	Description
false \| \Zend_Form_Decorator_Abstract

getDecorators() : array

Retrieve all decorators

Returns

Type	Description
array

getDescription() : string

Retrieve element description

Returns

Type	Description
string

getErrorMessageSeparator() : string

Get errorMessageSeparator

Returns

Type	Description
string

getErrorMessages() : array

Retrieve custom error messages

Returns

Type	Description
array

getErrors() : array

Retrieve validator chain errors

Returns

Type	Description
array

getFilter(string $name) : \Zend_Filter_Interface

Retrieve a single filter by name

Parameters

Name	Type	Description
$name	string

Returns

Type	Description
\Zend_Filter_Interface

getFilters() : array

Get all filters

Returns

Type	Description
array

getFullyQualifiedName() : string

Get fully qualified name

Places name as subitem of array and/or appends brackets.

Returns

Type	Description
string

getId() : string

Get element id

Returns

Type	Description
string

getIgnore() : bool

Get ignore flag (used when retrieving values at form level)

Returns

Type	Description
bool

getLabel() : string

Retrieve element label

Returns

Type	Description
string

getMessages() : array

Retrieve error messages

The array keys are validation failure message identifiers, and the array values are the corresponding human-readable message strings.

If isValid() was never called or if the most recent isValid() call returned true, then this method returns an empty array.

Returns

Type	Description
array

getName() : string

Return element name

Returns

Type	Description
string

getOrder() : int

Retrieve element order

Returns

Type	Description
int

getPluginLoader(string $type) : \Zend_Loader_PluginLoader

Retrieve plugin loader for validator or filter chain

Instantiates with default rules if none available for that type. Use 'decorator', 'filter', or 'validate' for $type.

Parameters

Name	Type	Description
$type	string

Returns

Type	Description
\Zend_Loader_PluginLoader

Throws

Exception	Description
\Zend_Loader_Exception	on invalid type.

getTranslator() : \Zend_Translate_Adapter | null

Retrieve localization translator object

Returns

Type	Description
\Zend_Translate_Adapter \| null

getType() : string

Return element type

Returns

Type	Description
string

getUnfilteredValue() : mixed

Retrieve unfiltered element value

Returns

Type	Description
mixed

getValidator(string $name) : \Zend_Validate_Interface | false

Retrieve a single validator by name

Parameters

Name	Type	Description
$name	string

Returns

Type	Description
\Zend_Validate_Interface \| false	False if not found, validator otherwise

getValidators() : array

Retrieve all validators

Returns

Type	Description
array

getValue() : mixed

Retrieve filtered element value

Returns

Type	Description
mixed

getView() : null | \Zend_View_Interface

Retrieve view object

Retrieves from ViewRenderer if none previously set.

Returns

Type	Description
null \| \Zend_View_Interface

hasErrors() : bool

Are there errors registered?

Returns

Type	Description
bool

hasTranslator() : bool

Does this element have its own specific translator?

Returns

Type	Description
bool

init() : void

Initialize object; used by extending classes

isArray() : bool

Is the element representing an array?

Returns

Type	Description
bool

isRequired() : bool

Is the element required?

Returns

Type	Description
bool

isValid(mixed $value, mixed $context = null) : boolean

Validate element value

If a translation adapter is registered, any error messages will be translated according to the current locale, using the given error code; if no matching translation is found, the original message will be utilized.

Note: The filtered value is validated.

Parameters

Name	Type	Description
$value	mixed
$context	mixed

Returns

Type	Description
boolean

Throws

Exception	Description
\Zend_Validate_Exception	If validation of $value is impossible

loadDefaultDecorators() : \Zend_Form_Element

Load default decorators

Returns

Type	Description
\Zend_Form_Element

loadDefaultDecoratorsIsDisabled() : bool

Should we load the default decorators?

Returns

Type	Description
bool

markAsError() : \Zend_Form_Element

Mark the element as being in a failed validation state

Returns

Type	Description
\Zend_Form_Element

removeDecorator(string $name) : \Zend_Form_Element

Remove a single decorator

Parameters

Name	Type	Description
$name	string

Returns

Type	Description
\Zend_Form_Element

removeFilter(string $name) : \Zend_Form_Element

Remove a filter by name

Parameters

Name	Type	Description
$name	string

Returns

Type	Description
\Zend_Form_Element

removeValidator(string $name) : bool

Remove a single validator by name

Parameters

Name	Type	Description
$name	string

Returns

Type	Description
bool

render(\Zend_View_Interface $view = null) : string

Render form element

Parameters

Name	Type	Description
$view	\Zend_View_Interface

Returns

Type	Description
string

resolveElementId(\Zend_Form_Decorator_Interface $decorator) : string

static

Used to resolve and return an element ID

Passed to the HtmlTag decorator as a callback in order to provide an ID.

Parameters

Name	Type	Description
$decorator	\Zend_Form_Decorator_Interface

Returns

Type	Description
string

setAllowEmpty(bool $flag) : \Zend_Form_Element

Set 'allow empty' flag

When the allow empty flag is enabled and the required flag is false, the element will validate with empty values.

Parameters

Name	Type	Description
$flag	bool

Returns

Type	Description
\Zend_Form_Element

setAttrib(string $name, mixed $value) : \Zend_Form_Element

Set element attribute

Parameters

Name	Type	Description
$name	string
$value	mixed

Returns

Type	Description
\Zend_Form_Element

Throws

Exception	Description
\Zend_Form_Exception	for invalid $name values

setAttribs(array $attribs) : \Zend_Form_Element

Set multiple attributes at once

Parameters

Name	Type	Description
$attribs	array

Returns

Type	Description
\Zend_Form_Element

setAutoInsertNotEmptyValidator(bool $flag) : \Zend_Form_Element

Set flag indicating whether a NotEmpty validator should be inserted when element is required

Parameters

Name	Type	Description
$flag	bool

Returns

Type	Description
\Zend_Form_Element

setBelongsTo(string $array) : \Zend_Form_Element

Set array to which element belongs

Parameters

Name	Type	Description
$array	string

Returns

Type	Description
\Zend_Form_Element

setConfig(\Zend_Config $config) : \Zend_Form_Element

Set object state from Zend_Config object

Parameters

Name	Type	Description
$config	\Zend_Config

Returns

Type	Description
\Zend_Form_Element

setDecorators(array $decorators) : \Zend_Form_Element

Overwrite all decorators

Parameters

Name	Type	Description
$decorators	array

Returns

Type	Description
\Zend_Form_Element

setDescription(string $description) : \Zend_Form_Element

Set element description

Parameters

Name	Type	Description
$description	string

Returns

Type	Description
\Zend_Form_Element

setDisableLoadDefaultDecorators(bool $flag) : \Zend_Form_Element

Set flag to disable loading default decorators

Parameters

Name	Type	Description
$flag	bool

Returns

Type	Description
\Zend_Form_Element

setDisableTranslator(bool $flag) : \Zend_Form_Element

Indicate whether or not translation should be disabled

Parameters

Name	Type	Description
$flag	bool

Returns

Type	Description
\Zend_Form_Element

setErrorMessageSeparator(string $separator) : \Zend_Form_Element

Set errorMessageSeparator

Parameters

Name	Type	Description
$separator	string

Returns

Type	Description
\Zend_Form_Element

setErrorMessages(array $messages) : \Zend_Form_Element

Same as addErrorMessages(), but clears custom error message stack first

Parameters

Name	Type	Description
$messages	array

Returns

Type	Description
\Zend_Form_Element

setErrors(array $messages) : \Zend_Form_Element

Overwrite any previously set error messages and flag as failed validation

Parameters

Name	Type	Description
$messages	array

Returns

Type	Description
\Zend_Form_Element

setFilters(array $filters) : \Zend_Form_Element

Add filters to element, overwriting any already existing

Parameters

Name	Type	Description
$filters	array

Returns

Type	Description
\Zend_Form_Element

setIgnore(bool $flag) : \Zend_Form_Element

Set ignore flag (used when retrieving values at form level)

Parameters

Name	Type	Description
$flag	bool

Returns

Type	Description
\Zend_Form_Element

setIsArray(bool $flag) : \Zend_Form_Element

Set flag indicating if element represents an array

Parameters

Name	Type	Description
$flag	bool

Returns

Type	Description
\Zend_Form_Element

setLabel(string $label) : \Zend_Form_Element

Set element label

Parameters

Name	Type	Description
$label	string

Returns

Type	Description
\Zend_Form_Element

setName(string $name) : \Zend_Form_Element

Set element name

Parameters

Name	Type	Description
$name	string

Returns

Type	Description
\Zend_Form_Element

setOptions(array $options) : \Zend_Form_Element

Set object state from options array

Parameters

Name	Type	Description
$options	array

Returns

Type	Description
\Zend_Form_Element

setOrder(int $order) : \Zend_Form_Element

Set element order

Parameters

Name	Type	Description
$order	int

Returns

Type	Description
\Zend_Form_Element

setPluginLoader(\Zend_Loader_PluginLoader_Interface $loader, string $type) : \Zend_Form_Element

Set plugin loader to use for validator or filter chain

Parameters

Name	Type	Description
$loader	\Zend_Loader_PluginLoader_Interface
$type	string	'decorator', 'filter', or 'validate'

Returns

Type	Description
\Zend_Form_Element

Throws

Exception	Description
\Zend_Form_Exception	on invalid type

setRequired(bool $flag = true) : \Zend_Form_Element

Set required flag

Parameters

Name	Type	Description
$flag	bool	Default value is true

Returns

Type	Description
\Zend_Form_Element

setTranslator(\Zend_Translate | null $translator = null) : \Zend_Form_Element

Set translator object for localization

Parameters

Name	Type	Description
$translator	\Zend_Translate \| null

Returns

Type	Description
\Zend_Form_Element

setValidators(array $validators) : \Zend_Form_Element

Set multiple validators, overwriting previous validators

Parameters

Name	Type	Description
$validators	array

Returns

Type	Description
\Zend_Form_Element

setValue(mixed $value) : \Zend_Form_Element

Set element value

Parameters

Name	Type	Description
$value	mixed

Returns

Type	Description
\Zend_Form_Element

setView(\Zend_View_Interface $view = null) : \Zend_Form_Element

Set view object

Parameters

Name	Type	Description
$view	\Zend_View_Interface

Returns

Type	Description
\Zend_Form_Element

translatorIsDisabled() : bool

Is translation disabled?

Returns

Type	Description
bool

Form/Element.php

\Zend_Form_Elementjump to top

Constants

Properties

Methods

\Zend_Form_Element
jump to top