PHP Class Prado\Web\UI\TControl

TControl is the base class for all components on a page hierarchy. It implements the following features for UI-related functionalities: - databinding feature - parent and child relationship - naming container and containee relationship - viewstate and controlstate features - rendering scheme - control lifecycles A property can be data-bound with an expression. By calling {@link dataBind}, expressions bound to properties will be evaluated and the results will be set to the corresponding properties. Parent and child relationship determines how the presentation of controls are enclosed within each other. A parent will determine where to place the presentation of its child controls. For example, a TPanel will enclose all its child controls' presentation within a div html tag. A control's parent can be obtained via {@link getParent Parent} property, and its {@link getControls Controls} property returns a list of the control's children, including controls and static texts. The property can be manipulated like an array for adding or removing a child (see {@link TList} for more details). A naming container control implements INamingContainer and ensures that its containee controls can be differentiated by their ID property values. Naming container and containee realtionship specifies a protocol to uniquely identify an arbitrary control on a page hierarchy by an ID path (concatenation of all naming containers' IDs and the target control's ID). Viewstate and controlstate are two approaches to preserve state across page postback requests. ViewState is mainly related with UI specific state and can be disabled if not needed. ControlState represents crucial logic state and cannot be disabled. A control is rendered via its {@link render()} method (the method is invoked by the framework.) Descendant control classes may override this method for customized rendering. By default, {@link render()} invokes {@link renderChildren()} which is responsible for rendering of children of the control. Control's {@link getVisible Visible} property governs whether the control should be rendered or not. Each control on a page will undergo a series of lifecycles, including control construction, Init, Load, PreRender, Render, and OnUnload. They work together with page lifecycles to process a page request.

Since: 3.0

Author: Qiang Xue ([email protected])

Inheritance: extends Prado\TApplicationComponent, implements Prado\Web\UI\IRenderable, implements Prado\Web\UI\IBindable

Mostrar archivo Open project: pradosoft/prado Class Usage Examples

Public Methods

Method	Description
__get ( $name ) : mixed	Returns a property value by name or a control by ID.
__isset ( $name ) : boolean	Checks for the existance of a property value by name or a control by ID.
addParsedObject ( $object )	Adds the object instantiated on a template to the child control collection.
addedControl ( $control )	Adds a control into the child collection of the control.
applyStyleSheetSkin ( $page )	Applies a stylesheet skin to a control.
autoBindProperty ( $name, $expression )	Sets up the binding between a property (or property path) and an expression.
bindProperty ( $name, $expression )	Sets up the binding between a property (or property path) and an expression.
broadcastEvent ( $name, $sender, $param )	Broadcasts an event.
bubbleEvent ( $sender, $param ) : boolean	This method responds to a bubbled event.
clearNamingContainer ( )	Resets the control as a naming container.
clearViewState ( $key )	Clears a viewstate value.
convertUniqueIdToClientId ( $uniqueID ) : string	Converts a unique ID to a client ID.
createChildControls ( )	Creates child controls.
dataBind ( )	Performs the databinding for this control.
ensureChildControls ( )	Ensures child controls are created.
findControl ( $id ) : TControl \| null	Finds a control by ID path within the current naming container.
findControlsByID ( $id ) : array	Finds all child and grand-child controls with the specified ID.
findControlsByType ( $type, $strict = true ) : array	Finds all child and grand-child controls that are of the specified type.
focus ( )	Sets input focus to this control.
getAdapter ( ) : TControlAdapter
getAllowChildControls ( ) : boolean
getAttribute ( $name ) : string
getAttributes ( ) : TAttributeCollection	Returns the list of custom attributes.
getClientID ( ) : string	Returns the client ID of the control.
getControls ( ) : TControlCollection
getCustomData ( ) : mixed	Returns custom data associated with this control.
getEnableTheming ( ) : boolean
getEnableViewState ( $checkParents = false ) : boolean
getEnabled ( $checkParents = false ) : boolean	Returns a value indicating whether the control is enabled.
getHasAdapter ( ) : boolean
getHasAttributes ( ) : boolean
getHasChildInitialized ( ) : boolean
getHasControls ( ) : boolean
getHasInitialized ( ) : boolean
getHasLoaded ( ) : boolean
getHasLoadedPostData ( ) : boolean
getHasPreRendered ( ) : boolean
getID ( $hideAutoID = true ) : string	Returns the id of the control.
getIsSkinApplied ( )
getNamingContainer ( ) : TControl
getPage ( ) : TPage
getParent ( ) : TControl
getRegisteredObject ( $name ) : mixed	Returns the named registered object.
getSkinID ( ) : string
getSourceTemplateControl ( ) : TTemplateControl
getTemplateControl ( ) : TTemplateControl
getUniqueID ( ) : string	Returns a unique ID that identifies the control in the page hierarchy.
getViewState ( $key, $defaultValue = null ) : mixed	Returns a viewstate value.
getVisible ( $checkParents = true ) : boolean	Checks if a control is visible.
hasAttribute ( $name ) : boolean
isObjectRegistered ( $name ) : boolean
loadState ( )	This method is invoked right after the control has loaded its state.
onDataBinding ( $param )	Raises 'OnDataBinding' event.
onInit ( $param )	This method is invoked when the control enters 'OnInit' stage.
onLoad ( $param )	This method is invoked when the control enters 'OnLoad' stage.
onPreRender ( $param )	This method is invoked when the control enters 'OnPreRender' stage.
onUnload ( $param )	This method is invoked when the control enters 'OnUnload' stage.
registerObject ( $name, $object )	Registers an object by a name.
removeAttribute ( $name ) : string	Removes the named attribute.
removedControl ( $control )	Removes a control from the child collection of the control.
render ( $writer )	Renders the control.
renderChildren ( $writer )	Renders the children of the control.
renderControl ( $writer )	Renders the control.
saveState ( )	This method is invoked when control state is to be saved.
setAdapter ( TControlAdapter $adapter )
setAttribute ( $name, $value )	Sets a custom control attribute.
setCustomData ( $value )	Associates custom data with this control.
setEnableTheming ( $value )
setEnableViewState ( $value )
setEnabled ( $value )
setID ( $id )
setPage ( $page )	Sets the page for a control.
setSkinID ( $value )
setTemplateControl ( $control )	Sets the control whose template contains this control.
setViewState ( $key, $value, $defaultValue = null )	Sets a viewstate value.
setVisible ( $value )
trackViewState ( $enabled )	Sets a value indicating whether we should keep data in viewstate.
unbindProperty ( $name )	Breaks the binding between a property (or property path) and an expression.
unregisterObject ( $name )	Unregisters an object by name.

Protected Methods

Method	Description
autoDataBindProperties ( )	Auto databinding properties of the control.
clearChildState ( )	Clears up the child state data.
clearControlState ( $key )	Clears a controlstate value.
createControlCollection ( ) : TControlCollection	Creates a control collection object that is to be used to hold child controls
dataBindChildren ( )	Databinding child controls.
dataBindProperties ( )	Databinding properties of the control.
getChildControlsCreated ( ) : boolean
getControlStage ( ) : integer	Gets the lifecycle step the control is currently at.
getControlState ( $key, $defaultValue = null ) : mixed	Returns a controlstate value.
initRecursive ( $namingContainer = null )	Performs the Init step for the control and all its child controls.
isDescendentOf ( $ancestor ) : boolean
loadRecursive ( )	Performs the Load step for the control and all its child controls.
loadStateRecursive ( &$state, $needViewState = true )	Loads state (viewstate and controlstate) into a control and its children.
preRenderRecursive ( )	Performs the PreRender step for the control and all its child controls.
raiseBubbleEvent ( $sender, $param )	Invokes the parent's bubbleEvent method.
saveStateRecursive ( $needViewState = true ) : array	Saves all control state (viewstate and controlstate) as a collection.
setChildControlsCreated ( $value )	Sets a value indicating whether child controls are created.
setControlStage ( $value )	Sets the lifecycle step the control is currently at.
setControlState ( $key, $value, $defaultValue = null )	Sets a controlstate value.
traverseChildControls ( $param, $preCallback = null, $postCallback = null )	Traverse the whole control hierarchy rooted at this control.
unloadRecursive ( )	Performs the Unload step for the control and all its child controls.

Private Methods

Method	Description
broadcastEventInternal ( $name, $sender, $param )	Recursively broadcasts an event.
clearCachedUniqueID ( $recursive )	Clears the cached UniqueID.
clearNameTable ( )	Clears the list of the controls whose IDs are managed by the specified naming container.
fillNameTable ( $container, $controls )	Updates the list of the controls whose IDs are managed by the specified naming container.
generateAutomaticID ( )	Generates an automatic ID for the control.

Method Details

__get() public method

This overrides the parent implementation by allowing accessing a control via its ID using the following syntax,


$menuBar=$this->menuBar;

Note, the control must be configured in the template with explicit ID. If the name matches both a property and a control ID, the control ID will take the precedence.

__isset() public method

This overrides the parent implementation by allowing checking for the existance of a control via its ID using the following syntax,


$menuBarExists = isset($this->menuBar);

Do not call this method. This is a PHP magic method that we override to allow using isset() to detect if a component property is set or not. Note, the control must be configured in the template with explicit ID. If the name matches both a property and a control ID, the control ID will take the precedence.

addParsedObject() public method

This method overrides the parent implementation. Only framework developers and control developers should use this method.

addedControl() public method

Control lifecycles will be caught up during the addition. Only framework developers should use this method.

public addedControl ( $control )

applyStyleSheetSkin() public method

Applies a stylesheet skin to a control.

public applyStyleSheetSkin ( $page )

autoBindProperty() public method

Unlike regular databinding, the expression bound by this method is automatically evaluated during {@link prerenderRecursive()}. The context of the expression is the template control (or the control itself if it is a page).

public autoBindProperty ( $name, $expression )

autoDataBindProperties() protected method

Auto databinding properties of the control.

protected autoDataBindProperties ( )

bindProperty() public method

The context of the expression is the template control (or the control itself if it is a page).

public bindProperty ( $name, $expression )

broadcastEvent() public method

The event will be sent to all controls on the current page hierarchy. If a control defines the event, the event will be raised for the control. If a control implements {@link IBroadcastEventReceiver}, its {@link IBroadcastEventReceiver::broadcastEventReceived broadcastEventReceived()} method will be invoked which gives the control a chance to respond to the event. For example, when broadcasting event 'OnClick', all controls having 'OnClick' event will have this event raised, and all controls implementing {@link IBroadcastEventReceiver} will also have its {@link IBroadcastEventReceiver::broadcastEventReceived broadcastEventReceived()} invoked.

public broadcastEvent ( $name, $sender, $param )

bubbleEvent() public method

This method should be overriden to provide customized response to a bubbled event. Check the type of event parameter to determine what event is bubbled currently.

clearChildState() final protected method

After a control loads its state, those state that do not belong to any existing child controls are stored as child state. This method will remove these state. Only frameworker developers and control developers should use this method.

final protected clearChildState ( )

clearControlState() protected method

Clears a controlstate value.

protected clearControlState ( $key )

clearNamingContainer() public method

Only framework developers should use this method.

public clearNamingContainer ( )

clearViewState() public method

Clears a viewstate value.

public clearViewState ( $key )

convertUniqueIdToClientId() public static method

Converts a unique ID to a client ID.

public static convertUniqueIdToClientId ( $uniqueID ) : string
return	string	the client ID of the control

createChildControls() public method

This method can be overriden for controls who want to have their controls. Do not call this method directly. Instead, call {@link ensureChildControls} to ensure child controls are created only once.

public createChildControls ( )

createControlCollection() protected method

Creates a control collection object that is to be used to hold child controls

dataBind() public method

Performs the databinding for this control.

public dataBind ( )

dataBindChildren() protected method

Databinding child controls.

protected dataBindChildren ( )

dataBindProperties() protected method

Databinding properties of the control.

protected dataBindProperties ( )

ensureChildControls() public method

If child controls are not created yet, this method will invoke {@link createChildControls} to create them.

public ensureChildControls ( )

findControl() public method

The current naming container is either the control itself if it implements {@link INamingContainer} or the control's naming container. The ID path is an ID sequence separated by {@link TControl::ID_SEPARATOR}. For example, 'Repeater1.Item1.Button1' looks for a control with ID 'Button1' whose naming container is 'Item1' whose naming container is 'Repeater1'.

public findControl ( $id ) : TControl \| null
return	TControl \| null	the control found, null if not found

findControlsByID() public method

Note, this method is different from {@link findControl} in that it searches through all controls that have this control as the ancestor while {@link findcontrol} only searches through controls that have this control as the direct naming container.

public findControlsByID ( $id ) : array
return	array	list of controls found

findControlsByType() public method

Finds all child and grand-child controls that are of the specified type.

public findControlsByType ( $type, $strict = true ) : array
return	array	list of controls found

focus() public method

Sets input focus to this control.

public focus ( )

getAdapter() public method

public getAdapter ( ) : TControlAdapter
return	TControlAdapter	control adapter. Null if not exists.

getAllowChildControls() public method

public getAllowChildControls ( ) : boolean
return	boolean	whether body contents are allowed for this control. Defaults to true.

getAttribute() public method

public getAttribute ( $name ) : string
return	string	attribute value, null if attribute does not exist

getAttributes() public method

Custom attributes are name-value pairs that may be rendered as HTML tags' attributes.

public getAttributes ( ) : TAttributeCollection
return	Prado\Collections\TAttributeCollection	the list of custom attributes

getChildControlsCreated() final protected method

final protected getChildControlsCreated ( ) : boolean
return	boolean	whether child controls have been created

getClientID() public method

The client ID can be used to uniquely identify the control in client-side scripts (such as JavaScript). Do not rely on the explicit format of the return ID.

public getClientID ( ) : string
return	string	the client ID of the control

getControlStage() protected method

This method should only be used by control developers.

protected getControlStage ( ) : integer
return	integer	the lifecycle step the control is currently at. The value can be CS_CONSTRUCTED, CS_CHILD_INITIALIZED, CS_INITIALIZED, CS_STATE_LOADED, CS_LOADED, CS_PRERENDERED.

getControlState() protected method

This function is mainly used in defining getter functions for control properties that must be kept in controlstate.

protected getControlState ( $key, $defaultValue = null ) : mixed
return	mixed	the controlstate value corresponding to $key

getControls() public method

public getControls ( ) : TControlCollection
return	TControlCollection	the child control collection

getCustomData() public method

A control may be associated with some custom data for various purposes. For example, a button may be associated with a string to identify itself in a generic OnClick event handler.

public getCustomData ( ) : mixed
return	mixed	custom data associated with this control. Defaults to null.

getEnableTheming() public method

public getEnableTheming ( ) : boolean
return	boolean	whether theming is enabled for this control. The theming is enabled if the control and all its parents have it enabled.

getEnableViewState() public method

public getEnableViewState ( $checkParents = false ) : boolean
return	boolean	whether viewstate is enabled

getEnabled() public method

A control is enabled if it allows client user interaction. If $checkParents is true, all parent controls will be checked, and unless they are all enabled, false will be returned. The property Enabled is mainly used for {@link TWebControl} derived controls.

public getEnabled ( $checkParents = false ) : boolean
return	boolean	whether the control is enabled.

getHasAdapter() public method

public getHasAdapter ( ) : boolean
return	boolean	whether there is an adapter for this control

getHasAttributes() public method

public getHasAttributes ( ) : boolean
return	boolean	whether the control has custom attributes

getHasChildInitialized() public method

public getHasChildInitialized ( ) : boolean
return	boolean	true if the child control has been initialized.

getHasControls() public method

public getHasControls ( ) : boolean
return	boolean	whether the control has child controls

getHasInitialized() public method

public getHasInitialized ( ) : boolean
return	boolean	true if the onInit event has raised.

getHasLoaded() public method

public getHasLoaded ( ) : boolean
return	boolean	true if the onLoad event has raised.

getHasLoadedPostData() public method

public getHasLoadedPostData ( ) : boolean
return	boolean	true if the control has loaded post data.

getHasPreRendered() public method

public getHasPreRendered ( ) : boolean
return	boolean	true if onPreRender event has raised.

getID() public method

Control ID can be either manually set or automatically generated. If $hideAutoID is true, automatically generated ID will be returned as an empty string.

public getID ( $hideAutoID = true ) : string
return	string	the ID of the control

getIsSkinApplied() public method

public getIsSkinApplied ( )

getNamingContainer() public method

public getNamingContainer ( ) : TControl
return	TControl	the naming container of this control

getPage() public method

public getPage ( ) : TPage
return	TPage	the page that contains this control

getParent() public method

public getParent ( ) : TControl
return	TControl	the parent of this control

getRegisteredObject() public method

A component with explicit ID on a template will be registered to the template owner. This method allows you to obtain this component with the ID.

public getRegisteredObject ( $name ) : mixed
return	mixed	the named registered object. Null if object is not found.

getSkinID() public method

public getSkinID ( ) : string
return	string	the skin ID of this control, '' if not set

getSourceTemplateControl() public method

public getSourceTemplateControl ( ) : TTemplateControl
return	TTemplateControl	the control whose template is loaded from some external storage, such as file, db, and whose template ultimately contains this control.

getTemplateControl() public method

public getTemplateControl ( ) : TTemplateControl
return	TTemplateControl	the control whose template contains this control

getUniqueID() public method

A unique ID is the contenation of all naming container controls' IDs and the control ID. These IDs are separated by '$' character. Control users should not rely on the specific format of UniqueID, however.

public getUniqueID ( ) : string
return	string	a unique ID that identifies the control in the page hierarchy

getViewState() public method

This function is very useful in defining getter functions for component properties that must be kept in viewstate.

public getViewState ( $key, $defaultValue = null ) : mixed
return	mixed	the viewstate value corresponding to $key

getVisible() public method

If parent check is required, then a control is visible only if the control and all its ancestors are visible.

public getVisible ( $checkParents = true ) : boolean
return	boolean	whether the control is visible (default=true).

hasAttribute() public method

public hasAttribute ( $name ) : boolean
return	boolean	whether the named attribute exists

initRecursive() protected method

Only framework developers should use this method.

protected initRecursive ( $namingContainer = null )

isDescendentOf() final protected method

final protected isDescendentOf ( $ancestor ) : boolean
return	boolean	if the control is a descendent (parent, parent of parent, etc.) of the specified control

isObjectRegistered() public method

loadRecursive() protected method

Only framework developers should use this method.

protected loadRecursive ( )

loadState() public method

You can override this method to initialize data from the control state. Parent implementation must be invoked.

public loadState ( )

loadStateRecursive() protected method

This method should only be used by framework developers.

protected loadStateRecursive ( &$state, $needViewState = true )

onDataBinding() public method

This method is invoked when {@link dataBind} is invoked.

public onDataBinding ( $param )

onInit() public method

The method raises 'OnInit' event. If you override this method, be sure to call the parent implementation so that the event handlers can be invoked.

public onInit ( $param )

onLoad() public method

The method raises 'OnLoad' event. If you override this method, be sure to call the parent implementation so that the event handlers can be invoked.

public onLoad ( $param )

onPreRender() public method

The method raises 'OnPreRender' event. If you override this method, be sure to call the parent implementation so that the event handlers can be invoked.

public onPreRender ( $param )

onUnload() public method

The method raises 'OnUnload' event. If you override this method, be sure to call the parent implementation so that the event handlers can be invoked.

public onUnload ( $param )

preRenderRecursive() protected method

Only framework developers should use this method.

protected preRenderRecursive ( )

raiseBubbleEvent() protected method

A control who wants to bubble an event must call this method in its onEvent method.

registerObject() public method

A registered object can be accessed like a public member variable. This method should only be used by framework and control developers.

removeAttribute() public method

Removes the named attribute.

public removeAttribute ( $name ) : string
return	string	attribute value removed, null if attribute does not exist.

removedControl() public method

Only framework developers should use this method.

public removedControl ( $control )

render() public method

This method is invoked by {@link renderControl} when the control is visible. You can override this method to provide customized rendering of the control. By default, the control simply renders all its child contents.

public render ( $writer )

renderChildren() public method

This method iterates through all child controls and static text strings and renders them in order.

public renderChildren ( $writer )

renderControl() public method

Only when the control is visible will the control be rendered.

public renderControl ( $writer )

saveState() public method

You can override this method to do last step state saving. Parent implementation must be invoked.

public saveState ( )

saveStateRecursive() protected method

This method should only be used by framework developers.

protected saveStateRecursive ( $needViewState = true ) : array
return	array	the collection of the control state (including its children's state).

setAdapter() public method

public setAdapter ( TControlAdapter $adapter )
$adapter	TControlAdapter

setAttribute() public method

Sets a custom control attribute.

public setAttribute ( $name, $value )

setChildControlsCreated() final protected method

If false, any existing child controls will be cleared up.

final protected setChildControlsCreated ( $value )

setControlStage() protected method

This method should only be used by control developers.

protected setControlStage ( $value )

setControlState() protected method

This function is very useful in defining setter functions for control properties that must be kept in controlstate. Make sure that the controlstate value must be serializable and unserializable.

protected setControlState ( $key, $value, $defaultValue = null )

setCustomData() public method

Note, the custom data must be serializable and unserializable.

public setCustomData ( $value )

setEnableTheming() public method

public setEnableTheming ( $value )

setEnableViewState() public method

public setEnableViewState ( $value )

setEnabled() public method

public setEnabled ( $value )

setID() public method

public setID ( $id )

setPage() public method

Only framework developers should use this method.

public setPage ( $page )

setSkinID() public method

public setSkinID ( $value )

setTemplateControl() public method

Only framework developers should use this method.

public setTemplateControl ( $control )

setViewState() public method

This function is very useful in defining setter functions for control properties that must be kept in viewstate. Make sure that the viewstate value must be serializable and unserializable.

public setViewState ( $key, $value, $defaultValue = null )

setVisible() public method

public setVisible ( $value )

trackViewState() public method

When it is false, data saved via setViewState() will not be persisted. By default, it is true, meaning data will be persisted across postbacks.

public trackViewState ( $enabled )

traverseChildControls() protected method

Callback function may be invoked for each control being visited. A pre-callback is invoked before traversing child controls; A post-callback is invoked after traversing child controls. Callback functions can be global functions or class methods. They must be of the following signature:


function callback_func($control,$param) {...}

where $control refers to the control being visited and $param is the parameter that is passed originally when calling this traverse function.

protected traverseChildControls ( $param, $preCallback = null, $postCallback = null )

unbindProperty() public method

Breaks the binding between a property (or property path) and an expression.

public unbindProperty ( $name )

unloadRecursive() protected method

Only framework developers should use this method.

protected unloadRecursive ( )

unregisterObject() public method

Unregisters an object by name.

public __get ( $name ) : mixed
return	mixed	the property value or the target control

public __isset ( $name ) : boolean
return	boolean	wether the control or property exists

public bubbleEvent ( $sender, $param ) : boolean
return	boolean	true if the event bubbling is handled and no more bubbling.

protected createControlCollection ( ) : TControlCollection
return	TControlCollection	control collection

public isObjectRegistered ( $name ) : boolean
return	boolean	whether an object has been registered with the name