API Documentation

Zend/Form/Element.php

Show: inherited
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 license@zend.com 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

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 24594 2012-01-05 21:27:01Z matthew $  

Constants

Constant  DECORATOR = 'DECORATOR'

Element Constants

Constant  FILTER = 'FILTER'
Constant  VALIDATE = 'VALIDATE'

Properties

Propertyprotectedbool  $_allowEmpty= 'true'

'Allow empty' flag

Default valuetrueDetails
Type
bool
Propertyprotectedbool  $_autoInsertNotEmptyValidator= 'true'

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

Default valuetrueDetails
Type
bool
Propertyprotectedstring  $_belongsTo= ''

Array to which element belongs

Details
Type
string
Propertyprotectedarray  $_decorators= 'array()'

Element decorators

Default valuearray()Details
Type
array
Propertyprotectedstring  $_description= ''

Element description

Details
Type
string
Propertyprotectedbool  $_disableLoadDefaultDecorators= 'false'

Should we disable loading the default decorators?

Default valuefalseDetails
Type
bool
Propertyprotectedstring  $_errorMessageSeparator= ''; ''

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

Default value'; 'Details
Type
string
Propertyprotectedarray  $_errorMessages= 'array()'

Custom error messages

Default valuearray()Details
Type
array
Propertyprotectedarray  $_errors= 'array()'

Validation errors

Default valuearray()Details
Type
array
Propertyprotectedarray  $_filters= 'array()'

Element filters

Default valuearray()Details
Type
array
Propertyprotectedbool  $_ignore= 'false'

Ignore flag (used when retrieving values at form level)

Default valuefalseDetails
Type
bool
Propertyprotectedbool  $_isArray= 'false'

Does the element represent an array?

Default valuefalseDetails
Type
bool
Propertyprotectedbool  $_isError= 'false'

Is the error marked as in an invalid state?

Default valuefalseDetails
Type
bool
Propertyprotectedbool  $_isErrorForced= 'false'

Has the element been manually marked as invalid?

Default valuefalseDetails
Type
bool
Propertyprotectedbool  $_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
Propertyprotectedstring  $_label= ''

Element label

Details
Type
string
Propertyprotectedarray  $_loaders= 'array()'

Plugin loaders for filter and validator chains

Default valuearray()Details
Type
array
Propertyprotectedarray  $_messages= 'array()'

Formatted validation error messages

Default valuearray()Details
Type
array
Propertyprotectedstring  $_name= ''

Element name

Details
Type
string
Propertyprotectedint  $_order= ''

Order of element

Details
Type
int
Propertyprotectedbool  $_required= 'false'

Required flag

Default valuefalseDetails
Type
bool
Propertyprotected\Zend_Translate  $_translator= ''

Details
Type
\Zend_Translate
Propertyprotectedbool  $_translatorDisabled= 'false'

Is translation disabled?

Default valuefalseDetails
Type
bool
Propertyprotectedstring  $_type= ''

Element type

Details
Type
string
Propertyprotectedarray  $_validatorRules= 'array()'

Array of un-initialized validators

Default valuearray()Details
Type
array
Propertyprotectedarray  $_validators= 'array()'

Array of initialized validators

Validators
Default valuearray()Details
Type
array
Propertyprotectedmixed  $_value= ''

Element value

Details
Type
mixed
Propertyprotected\Zend_View_Interface  $_view= ''

Details
Type
\Zend_View_Interface
Propertypublicstring  $helper= ''formText''

Default view helper to use

Default value'formText'Details
Type
string

Methods

methodpublic__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
methodpublic__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
methodpublic__get( string $key ) : mixed

Overloading: retrieve object property

Prevents access to properties beginning with '_'.

Parameters
Name Type Description
$key string
Returns
Type Description
mixed
methodpublic__set( string $key, mixed $value ) : \voide

Overloading: set object property

Parameters
Name Type Description
$key string
$value mixed
Returns
Type Description
\voide
methodpublic__toString( ) : string

String representation of form element

Proxies to {@link render()}.

Returns
Type Description
string
methodprotected_filterValue( string $value, string $key ) : void

Filter a value

Parameters
Name Type Description
$value string
$key string
methodprotected_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
methodprotected_getErrorMessages( ) : array

Retrieve error messages and perform translation and value substitution

Returns
Type Description
array
methodprotected_hasErrorMessages( ) : bool

Are there custom error messages registered?

Returns
Type Description
bool
methodprotected_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
methodprotected_loadFilter( array $filter ) : \Zend_Filter_Interface

Lazy-load a filter

Parameters
Name Type Description
$filter array
Returns
Type Description
\Zend_Filter_Interface
methodprotected_loadValidator( array $validator ) : \Zend_Validate_Interface

Lazy-load a validator

Parameters
Name Type Description
$validator array

Validator definition

Returns
Type Description
\Zend_Validate_Interface
methodpublicaddDecorator( 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
methodpublicaddDecorators( array $decorators ) : \Zend_Form_Element

Add many decorators at once

Parameters
Name Type Description
$decorators array
Returns
Type Description
\Zend_Form_Element
methodpublicaddError( 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
methodpublicaddErrorMessage( 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
methodpublicaddErrorMessages( 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
methodpublicaddErrors( 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
methodpublicaddFilter( 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
methodpublicaddFilters( array $filters ) : \Zend_Form_Element

Add filters to element

Parameters
Name Type Description
$filters array
Returns
Type Description
\Zend_Form_Element
methodpublicaddPrefixPath( 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
methodpublicaddPrefixPaths( array $spec ) : \Zend_Form_Element

Add many prefix paths at once

Parameters
Name Type Description
$spec array
Returns
Type Description
\Zend_Form_Element
methodpublicaddValidator( 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
methodpublicaddValidators( array $validators ) : \Zend_Form_Element

Add multiple validators

Parameters
Name Type Description
$validators array
Returns
Type Description
\Zend_Form_Element
methodpublicautoInsertNotEmptyValidator( ) : bool

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

Returns
Type Description
bool
methodpublicclearDecorators( ) : \Zend_Form_Element

Clear all decorators

Returns
Type Description
\Zend_Form_Element
methodpublicclearErrorMessages( ) : \Zend_Form_Element

Clear custom error messages stack

Returns
Type Description
\Zend_Form_Element
methodpublicclearFilters( ) : \Zend_Form_Element

Clear all filters

Returns
Type Description
\Zend_Form_Element
methodpublicclearValidators( ) : \Zend_Form_Element

Clear all validators

Returns
Type Description
\Zend_Form_Element
methodpublicfilterName( 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
methodpublicgetAllowEmpty( ) : bool

Get 'allow empty' flag

Returns
Type Description
bool
methodpublicgetAttrib( string $name ) : string

Retrieve element attribute

Parameters
Name Type Description
$name string
Returns
Type Description
string
methodpublicgetAttribs( ) : array

Return all attributes

Returns
Type Description
array
methodpublicgetBelongsTo( ) : string

Return array name to which element belongs

Returns
Type Description
string
methodpublicgetDecorator( 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
methodpublicgetDecorators( ) : array

Retrieve all decorators

Returns
Type Description
array
methodpublicgetDescription( ) : string

Retrieve element description

Returns
Type Description
string
methodpublicgetErrorMessageSeparator( ) : string

Get errorMessageSeparator

Returns
Type Description
string
methodpublicgetErrorMessages( ) : array

Retrieve custom error messages

Returns
Type Description
array
methodpublicgetErrors( ) : array

Retrieve validator chain errors

Returns
Type Description
array
methodpublicgetFilter( string $name ) : \Zend_Filter_Interface

Retrieve a single filter by name

Parameters
Name Type Description
$name string
Returns
Type Description
\Zend_Filter_Interface
methodpublicgetFilters( ) : array

Get all filters

Returns
Type Description
array
methodpublicgetFullyQualifiedName( ) : string

Get fully qualified name

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

Returns
Type Description
string
methodpublicgetId( ) : string

Get element id

Returns
Type Description
string
methodpublicgetIgnore( ) : bool

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

Returns
Type Description
bool
methodpublicgetLabel( ) : string

Retrieve element label

Returns
Type Description
string
methodpublicgetMessages( ) : array

Retrieve error messages

Returns
Type Description
array
methodpublicgetName( ) : string

Return element name

Returns
Type Description
string
methodpublicgetOrder( ) : int

Retrieve element order

Returns
Type Description
int
methodpublicgetPluginLoader( 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.
methodpublicgetTranslator( ) : \Zend_Translate_Adapter|null

Retrieve localization translator object

Returns
Type Description
\Zend_Translate_Adapter|null
methodpublicgetType( ) : string

Return element type

Returns
Type Description
string
methodpublicgetUnfilteredValue( ) : mixed

Retrieve unfiltered element value

Returns
Type Description
mixed
methodpublicgetValidator( 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
methodpublicgetValidators( ) : array

Retrieve all validators

Returns
Type Description
array
methodpublicgetValue( ) : mixed

Retrieve filtered element value

Returns
Type Description
mixed
methodpublicgetView( ) : null|\Zend_View_Interface

Retrieve view object

Retrieves from ViewRenderer if none previously set.

Returns
Type Description
null|\Zend_View_Interface
methodpublichasErrors( ) : bool

Are there errors registered?

Returns
Type Description
bool
methodpublichasTranslator( ) : bool

Does this element have its own specific translator?

Returns
Type Description
bool
methodpublicinit( ) : void

Initialize object; used by extending classes

methodpublicisArray( ) : bool

Is the element representing an array?

Returns
Type Description
bool
methodpublicisRequired( ) : bool

Is the element required?

Returns
Type Description
bool
methodpublicisValid( 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
methodpublicloadDefaultDecorators( ) : \Zend_Form_Element

Load default decorators

Returns
Type Description
\Zend_Form_Element
methodpublicloadDefaultDecoratorsIsDisabled( ) : bool

Should we load the default decorators?

Returns
Type Description
bool
methodpublicmarkAsError( ) : \Zend_Form_Element

Mark the element as being in a failed validation state

Returns
Type Description
\Zend_Form_Element
methodpublicremoveDecorator( string $name ) : \Zend_Form_Element

Remove a single decorator

Parameters
Name Type Description
$name string
Returns
Type Description
\Zend_Form_Element
methodpublicremoveFilter( string $name ) : \Zend_Form_Element

Remove a filter by name

Parameters
Name Type Description
$name string
Returns
Type Description
\Zend_Form_Element
methodpublicremoveValidator( string $name ) : bool

Remove a single validator by name

Parameters
Name Type Description
$name string
Returns
Type Description
bool
methodpublicrender( \Zend_View_Interface $view = null ) : string

Render form element

Parameters
Name Type Description
$view \Zend_View_Interface
Returns
Type Description
string
methodpublicresolveElementId( \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
methodpublicsetAllowEmpty( 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
methodpublicsetAttrib( 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
methodpublicsetAttribs( array $attribs ) : \Zend_Form_Element

Set multiple attributes at once

Parameters
Name Type Description
$attribs array
Returns
Type Description
\Zend_Form_Element
methodpublicsetAutoInsertNotEmptyValidator( 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
methodpublicsetBelongsTo( string $array ) : \Zend_Form_Element

Set array to which element belongs

Parameters
Name Type Description
$array string
Returns
Type Description
\Zend_Form_Element
methodpublicsetConfig( \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
methodpublicsetDecorators( array $decorators ) : \Zend_Form_Element

Overwrite all decorators

Parameters
Name Type Description
$decorators array
Returns
Type Description
\Zend_Form_Element
methodpublicsetDescription( string $description ) : \Zend_Form_Element

Set element description

Parameters
Name Type Description
$description string
Returns
Type Description
\Zend_Form_Element
methodpublicsetDisableLoadDefaultDecorators( bool $flag ) : \Zend_Form_Element

Set flag to disable loading default decorators

Parameters
Name Type Description
$flag bool
Returns
Type Description
\Zend_Form_Element
methodpublicsetDisableTranslator( 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
methodpublicsetErrorMessageSeparator( string $separator ) : \Zend_Form_Element

Set errorMessageSeparator

Parameters
Name Type Description
$separator string
Returns
Type Description
\Zend_Form_Element
methodpublicsetErrorMessages( 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
methodpublicsetErrors( 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
methodpublicsetFilters( 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
methodpublicsetIgnore( 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
methodpublicsetIsArray( 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
methodpublicsetLabel( string $label ) : \Zend_Form_Element

Set element label

Parameters
Name Type Description
$label string
Returns
Type Description
\Zend_Form_Element
methodpublicsetName( string $name ) : \Zend_Form_Element

Set element name

Parameters
Name Type Description
$name string
Returns
Type Description
\Zend_Form_Element
methodpublicsetOptions( array $options ) : \Zend_Form_Element

Set object state from options array

Parameters
Name Type Description
$options array
Returns
Type Description
\Zend_Form_Element
methodpublicsetOrder( int $order ) : \Zend_Form_Element

Set element order

Parameters
Name Type Description
$order int
Returns
Type Description
\Zend_Form_Element
methodpublicsetPluginLoader( \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
methodpublicsetRequired( 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
methodpublicsetTranslator( \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
methodpublicsetValidators( array $validators ) : \Zend_Form_Element

Set multiple validators, overwriting previous validators

Parameters
Name Type Description
$validators array
Returns
Type Description
\Zend_Form_Element
methodpublicsetValue( mixed $value ) : \Zend_Form_Element

Set element value

Parameters
Name Type Description
$value mixed
Returns
Type Description
\Zend_Form_Element
methodpublicsetView( \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
methodpublictranslatorIsDisabled( ) : bool

Is translation disabled?

Returns
Type Description
bool
Documentation was generated by DocBlox 0.15.1.