Class \Prado\Web\UI\TControl

TControl class

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 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 \Prado\Web\UI\getParent property, and its \Prado\Web\UI\getControls 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 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 render() method (the method is invoked by the framework.) Descendant control classes may override this method for customized rendering. By default, render() invokes renderChildren() which is responsible for rendering of children of the control. Control's \Prado\Web\UI\getVisible 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.

Class hierarchy

\Prado\Web\UI\TControl implements IRenderable, IBindable

\Prado\TApplicationComponent

\Prado\TComponent

Author: Qiang Xue <qiang.xue@gmail.com>
Since: 3.0

Methods summary
`public`	`__get(string $name) : mixed` Returns a property value by name or a control by ID. 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.
`public`	`__isset(string $name) : bool` Checks for the existance of a property value by name or a control by ID. 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.
`public`	`addedControl(TControl $control) : mixed` Adds a control into the child collection of the control. Control lifecycles will be caught up during the addition. Only framework developers should use this method.
`public`	`addParsedObject(TComponent\|string $object) : mixed` Adds the object instantiated on a template to the child control collection. This method overrides the parent implementation. Only framework developers and control developers should use this method.
`public`	`applyStyleSheetSkin(TPage $page) : mixed` Applies a stylesheet skin to a control.
`public`	`autoBindProperty(string $name, string $expression) : mixed` Sets up the binding between a property (or property path) and an expression. Unlike regular databinding, the expression bound by this method is automatically evaluated during prerenderRecursive(). The context of the expression is the template control (or the control itself if it is a page).
`public`	`bindProperty(string $name, string $expression) : mixed` Sets up the binding between a property (or property path) and an expression. The context of the expression is the template control (or the control itself if it is a page).
`public`	`broadcastEvent(string $name, TControl $sender, TEventParameter $param) : mixed` Broadcasts an event. 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 IBroadcastEventReceiver, its \Prado\Web\UI\IBroadcastEventReceiver::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 IBroadcastEventReceiver will also have its \Prado\Web\UI\IBroadcastEventReceiver::broadcastEventReceived invoked.
`public`	`bubbleEvent(TControl $sender, TEventParameter $param) : bool` This method responds to a bubbled event. 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.
`public`	`clearNamingContainer() : mixed` Resets the control as a naming container. Only framework developers should use this method.
`public`	`clearViewState(string $key) : mixed` Clears a viewstate value.
`public static`	`convertUniqueIdToClientId(string $uniqueID) : string` Converts a unique ID to a client ID.
`public`	`createChildControls() : mixed` Creates child controls. This method can be overriden for controls who want to have their controls. Do not call this method directly. Instead, call ensureChildControls to ensure child controls are created only once.
`public`	`dataBind() : mixed` Performs the databinding for this control.
`public`	`ensureChildControls() : mixed` Ensures child controls are created. If child controls are not created yet, this method will invoke createChildControls to create them.
`public`	`findControl(string $id) : null\|mixed` Finds a control by ID path within the current naming container. The current naming container is either the control itself if it implements INamingContainer or the control's naming container. The ID path is an ID sequence separated by 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`	`findControlsByID(string $id) : array<string\|int, mixed>` Finds all child and grand-child controls with the specified ID. Note, this method is different from findControl in that it searches through all controls that have this control as the ancestor while findcontrol only searches through controls that have this control as the direct naming container.
`public`	`findControlsByType(string $type[, bool $strict = true ]) : array<string\|int, mixed>` Finds all child and grand-child controls that are of the specified type.
`public`	`focus() : mixed` Sets input focus to this control.
`public`	`getAdapter() : TControlAdapter`
`public`	`getAllowChildControls() : bool`
`public`	`getAttribute(mixed $name) : string`
`public`	`getAttributes() : TAttributeCollection` Returns the list of custom attributes. Custom attributes are name-value pairs that may be rendered as HTML tags' attributes.
`public`	`getAutoGlobalListen() : bool` TControl need not auto listen to global events because class behaviors are not typically added in the middle of running a page and the overhead of so many TControls listening and unlistening.
`public`	`getClientID() : string` Returns the client ID of the control. 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`	`getControls() : TControlCollection`
`public`	`getCustomData() : mixed` Returns custom data associated with this control. 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`	`getEnabled([bool $checkParents = false ]) : bool` Returns a value indicating whether the control is enabled. 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 TWebControl derived controls.
`public`	`getEnableTheming() : bool`
`public`	`getEnableViewState([mixed $checkParents = false ]) : bool`
`public`	`getHasAdapter() : bool`
`public`	`getHasAttributes() : bool`
`public`	`getHasChildInitialized() : bool`
`public`	`getHasControls() : bool`
`public`	`getHasInitialized() : bool`
`public`	`getHasLoaded() : bool`
`public`	`getHasLoadedPostData() : bool`
`public`	`getHasPreRendered() : bool`
`public`	`getID([bool $hideAutoID = true ]) : string` Returns the id of the control. 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`	`getIsSkinApplied() : bool`
`public`	`getNamingContainer() : TControl`
`public`	`getPage() : TPage`
`public`	`getParent() : TControl`
`public`	`getPluginModule() : null\|IPluginModule` Returns the module associated with the class path of the control. This is for Composer extensions adding their own Controls to access their associated Module.
`public`	`getRegisteredObject(mixed $name) : mixed` Returns the named registered object. 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`	`getSkinID() : string`
`public`	`getSourceTemplateControl() : TTemplateControl`
`public`	`getTemplateControl() : TTemplateControl`
`public`	`getUniqueID() : string` Returns a unique ID that identifies the control in the page hierarchy. 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`	`getViewState(string $key[, mixed $defaultValue = null ]) : mixed` Returns a viewstate value. This function is very useful in defining getter functions for component properties that must be kept in viewstate.
`public`	`getVisible([bool $checkParents = true ]) : bool` Checks if a control is visible. If parent check is required, then a control is visible only if the control and all its ancestors are visible.
`public`	`hasAttribute(mixed $name) : bool`
`public`	`isObjectRegistered(mixed $name) : bool`
`public`	`loadState() : mixed` This method is invoked right after the control has loaded its state. You can override this method to initialize data from the control state. Parent implementation must be invoked.
`public`	`onDataBinding(TEventParameter $param) : mixed` Raises 'OnDataBinding' event. This method is invoked when dataBind is invoked.
`public`	`onInit(TEventParameter $param) : mixed` This method is invoked when the control enters 'OnInit' stage. 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`	`onLoad(TEventParameter $param) : mixed` This method is invoked when the control enters 'OnLoad' stage. 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`	`onPreRender(TEventParameter $param) : mixed` This method is invoked when the control enters 'OnPreRender' stage. 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`	`onUnload(TEventParameter $param) : mixed` This method is invoked when the control enters 'OnUnload' stage. 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`	`registerObject(string $name, object $object) : mixed` Registers an object by a name. A registered object can be accessed like a public member variable. This method should only be used by framework and control developers.
`public`	`removeAttribute(string $name) : string` Removes the named attribute.
`public`	`removedControl(TControl $control) : mixed` Removes a control from the child collection of the control. Only framework developers should use this method.
`public`	`render(THtmlWriter $writer) : mixed` Renders the control. This method is invoked by 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`	`renderChildren(THtmlWriter $writer) : mixed` Renders the children of the control. This method iterates through all child controls and static text strings and renders them in order.
`public`	`renderControl(THtmlWriter $writer) : mixed` Renders the control. Only when the control is visible will the control be rendered.
`public`	`saveState() : mixed` This method is invoked when control state is to be saved. You can override this method to do last step state saving. Parent implementation must be invoked.
`public`	`setAdapter(TControlAdapter $adapter) : mixed`
`public`	`setAttribute(string $name, string $value) : mixed` Sets a custom control attribute.
`public`	`setCustomData(mixed $value) : mixed` Associates custom data with this control. Note, the custom data must be serializable and unserializable.
`public`	`setEnabled(bool $value) : mixed`
`public`	`setEnableTheming(bool $value) : mixed`
`public`	`setEnableViewState(bool $value) : mixed`
`public`	`setID(string $id) : mixed`
`public`	`setPage(TPage $page) : mixed` Sets the page for a control. Only framework developers should use this method.
`public`	`setSkinID(string $value) : mixed`
`public`	`setTemplateControl(TTemplateControl $control) : mixed` Sets the control whose template contains this control. Only framework developers should use this method.
`public`	`setViewState(string $key, mixed $value[, null\|mixed $defaultValue = null ]) : mixed` Sets a viewstate value. 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`	`setVisible(bool $value) : mixed`
`public`	`trackViewState(bool $enabled) : mixed` Sets a value indicating whether we should keep data in viewstate. 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`	`unbindProperty(string $name) : mixed` Breaks the binding between a property (or property path) and an expression.
`public`	`unregisterObject(string $name) : mixed` Unregisters an object by name.
`protected`	`autoDataBindProperties() : mixed` Auto databinding properties of the control.
`protected final`	`clearChildState() : mixed` Clears up the child state data. 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.
`protected`	`clearControlState(string $key) : mixed` Clears a controlstate value.
`protected`	`createControlCollection() : TControlCollection` Creates a control collection object that is to be used to hold child controls
`protected`	`dataBindChildren() : mixed` Databinding child controls.
`protected`	`dataBindProperties() : mixed` Databinding properties of the control.
`protected final`	`getChildControlsCreated() : bool`
`protected`	`getControlStage() : int` Gets the lifecycle step the control is currently at. This method should only be used by control developers.
`protected`	`getControlState(string $key[, mixed $defaultValue = null ]) : mixed` Returns a controlstate value. This function is mainly used in defining getter functions for control properties that must be kept in controlstate.
`protected`	`initRecursive([TControl $namingContainer = null ]) : mixed` Performs the Init step for the control and all its child controls. Only framework developers should use this method.
`protected final`	`isDescendentOf(TControl $ancestor) : bool`
`protected`	`loadRecursive() : mixed` Performs the Load step for the control and all its child controls. Only framework developers should use this method.
`protected`	`loadStateRecursive(array<string\|int, mixed> &$state[, bool $needViewState = true ]) : mixed` Loads state (viewstate and controlstate) into a control and its children. This method should only be used by framework developers.
`protected`	`preRenderRecursive() : mixed` Performs the PreRender step for the control and all its child controls. Only framework developers should use this method.
`protected`	`raiseBubbleEvent(TControl $sender, TEventParameter $param) : mixed` Invokes the parent's bubbleEvent method. A control who wants to bubble an event must call this method in its onEvent method.
`protected`	`saveStateRecursive([bool $needViewState = true ]) : array<string\|int, mixed>` Saves all control state (viewstate and controlstate) as a collection. This method should only be used by framework developers.
`protected final`	`setChildControlsCreated(bool $value) : mixed` Sets a value indicating whether child controls are created. If false, any existing child controls will be cleared up.
`protected`	`setControlStage(int $value) : mixed` Sets the lifecycle step the control is currently at. This method should only be used by control developers.
`protected`	`setControlState(string $key, mixed $value[, null\|mixed $defaultValue = null ]) : mixed` Sets a controlstate value. 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`	`traverseChildControls(mixed $param[, null\|callable $preCallback = null ][, null\|callable $postCallback = null ]) : mixed` Traverse the whole control hierarchy rooted at this control. 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`	`unloadRecursive() : mixed` Performs the Unload step for the control and all its child controls. Only framework developers should use this method.
`private`	`broadcastEventInternal(string $name, TControl $sender, TBroadcastEventParameter $param) : mixed` Recursively broadcasts an event. This method should only be used by framework developers.
`private`	`clearCachedUniqueID(bool $recursive) : mixed` Clears the cached UniqueID. If $recursive=true, all children's cached UniqueID will be cleared as well.
`private`	`clearNameTable() : mixed` Clears the list of the controls whose IDs are managed by the specified naming container.
`private`	`fillNameTable(TControl $container, TControlCollection $controls) : mixed` Updates the list of the controls whose IDs are managed by the specified naming container.
`private`	`generateAutomaticID() : mixed` Generates an automatic ID for the control.

Inherited methods
__call, __callStatic, __clone, __construct, __destruct, __get, __isset, __set, __sleep, __unset, __wakeup, addParsedObject, asa, attachBehavior, attachBehaviors, attachClassBehavior, attachEventHandler, callBehaviorsMethod, canGetProperty, canSetProperty, clearBehaviors, createdOnTemplate, detachBehavior, detachBehaviors, detachClassBehavior, detachEventHandler, disableBehavior, disableBehaviors, enableBehavior, enableBehaviors, evaluateExpression, evaluateStatements, fxAttachClassBehavior, fxDetachClassBehavior, getApplication, getAutoGlobalListen, getBehaviors, getBehaviorsEnabled, getClassHierarchy, getEventHandlers, getListeningToGlobalEvents, getRequest, getResponse, getService, getSession, getSubProperty, getUser, hasEvent, hasEventHandler, hasMethod, hasProperty, isa, listen, publishAsset, publishFilePath, raiseEvent, setSubProperty, unlisten, _getZappableSleepProps, getCallChain, getClassFxEvents, instanceBehavior, filter_prado_fx

Constants summary
`public mixed`	`AUTOMATIC_ID_PREFIX` prefix to an ID automatically generated	`'ctl'`
`public mixed`	`CLIENT_ID_SEPARATOR` separator char between IDs in a ClientID	`'_'`
`public mixed`	`CS_CHILD_INITIALIZED`	`1`
`public mixed`	`CS_CONSTRUCTED` the stage of lifecycles that the control is currently at	`0`
`public mixed`	`CS_INITIALIZED`	`2`
`public mixed`	`CS_LOADED`	`4`
`public mixed`	`CS_PRERENDERED`	`5`
`public mixed`	`CS_STATE_LOADED`	`3`
`public mixed`	`ID_FORMAT` format of control ID	`'/^[a-zA-Z_]\\w*$/'`
`public mixed`	`ID_SEPARATOR` separator char between IDs in a UniqueID	`'$'`
`public mixed`	`IS_CHILD_CREATED`	`0x20`
`public mixed`	`IS_CREATING_CHILD`	`0x40`
`public mixed`	`IS_DISABLE_THEMING`	`0x10`
`public mixed`	`IS_DISABLE_VIEWSTATE`	`0x2`
`public mixed`	`IS_ID_SET` State bits.	`0x1`
`public mixed`	`IS_SKIN_APPLIED`	`0x4`
`public mixed`	`IS_STYLESHEET_APPLIED`	`0x8`
`public mixed`	`RF_ADAPTER`	`9`
`public mixed`	`RF_AUTO_BINDINGS`	`10`
`public mixed`	`RF_CHILD_STATE`	`1`
`public mixed`	`RF_CONTROLS` Indexes for the rare fields.	`0`
`public mixed`	`RF_CONTROLSTATE`	`7`
`public mixed`	`RF_DATA_BINDINGS`	`5`
`public mixed`	`RF_EVENTS`	`6`
`public mixed`	`RF_NAMED_CONTROLS`	`2`
`public mixed`	`RF_NAMED_CONTROLS_ID`	`3`
`public mixed`	`RF_NAMED_OBJECTS`	`8`
`public mixed`	`RF_SKIN_ID`	`4`

Inherited constants
`\Prado\TApplicationComponent::FX_CACHE_FILE, \Prado\TComponent::GLOBAL_RAISE_EVENT_LISTENER`

Classes

Interfaces

Traits

Search results

Class \Prado\Web\UI\TControl

Class hierarchy