Class TComponent

Description

TComponent class

TComponent is the base class for all PRADO components. TComponent implements the protocol of defining, using properties and events.

A property is defined by a getter method, and/or a setter method. Properties can be accessed in the way like accessing normal object members. Reading or writing a property will cause the invocation of the corresponding getter or setter method, e.g.,

  1.  $a=$this->Text;     // equivalent to $a=$this->getText();
  2.  $this->Text='abc';  // equivalent to $this->setText('abc');
The signatures of getter and setter methods are as follows,
  1.  // getter, defines a readable property 'Text'
  2.  function getText(... }
  3.  // setter, defines a writable property 'Text', with $value being the value to be set to the property
  4.  function setText($value... }
Property names are case-insensitive. It is recommended that they are written in the format of concatenated words, with the first letter of each word capitalized (e.g. DisplayMode, ItemStyle).

Since Prado 3.2 a new class of javascript-friendly properties have been introduced to better deal with potential security problems like cross-site scripting issues. All the data that gets sent clientside inside a javascript block is now encoded by default. Sometimes there's the need to bypass this encoding and be able to send raw javascript code. This new class of javascript-friendly properties are identified by their name starting with 'js' (case insensitive):

  1.  // getter, defines a readable property 'Text'
  2.  function getJsText(... }
  3.  // setter, defines a writable property 'Text', with $value being the value to be set to the property
  4.  function setJsText(TJavaScriptLiteral $value... }
Js-friendly properties can be accessed using both their Js-less name and their Js-enabled name:
  1.  // set some simple text as property value
  2.  $component->Text 'text';
  3.  // set some javascript code as property value
  4.  $component->JsText 'raw javascript';
In the first case, the property value will automatically gets encoded when sent clientside inside a javascript block. In the second case, the property will be 'marked' as being a safe javascript statement and will not be encoded when rendered inside a javascript block. This special handling makes use of the TJavaScriptLiteral class.

An event is defined by the presence of a method whose name starts with 'on'. The event name is the method name and is thus case-insensitive. An event can be attached with one or several methods (called event handlers). An event can be raised by calling raiseEvent method, upon which the attached event handlers will be invoked automatically in the order they are attached to the event. Event handlers must have the following signature,

  1.  function eventHandlerFuncName($sender,$param... }
where $sender refers to the object who is responsible for the raising of the event, and $param refers to a structure that may contain event-specific information. To raise an event (assuming named as 'Click') of a component, use
  1.  $component->raiseEvent('OnClick');
To attach an event handler to an event, use one of the following ways,
  1.  $component->OnClick=$callback;  // or $component->OnClick->add($callback);
  2.  $component->attachEventHandler('OnClick',$callback);
The first two ways make use of the fact that $component->OnClick refers to the event handler list TList for the 'OnClick' event. The variable $callback contains the definition of the event handler that can be either a string referring to a global function name, or an array whose first element refers to an object and second element a method name/path that is reachable by the object, e.g.
  • 'buttonClicked' : buttonClicked($sender,$param);
  • array($object,'buttonClicked') : $object->buttonClicked($sender,$param);
  • array($object,'MainContent.SubmitButton.buttonClicked') : $object->MainContent->SubmitButton->buttonClicked($sender,$param);

  • author: Qiang Xue <qiang.xue@gmail.com>
  • version: $Id: TComponent.php 3123 2012-03-26 10:10:51Z ctrlaltca@gmail.com $
  • since: 3.0

Located in /TComponent.php (line 99)


	
			
Direct descendents
Class Description
TCacheDependency TCacheDependency class.
TDummyDataSource TDummyDataSource class
TList TList class
TMap TMap class
TPagedDataSource TPagedDataSource class
TQueue TQueue class
TStack TStack class
TActiveRecord Base class for active records.
TActiveRecordGateway TActiveRecordGateway excutes the SQL command queries and returns the data record as arrays (for most finder methods).
TActiveRecordManager TActiveRecordManager provides the default DB connection, default active record gateway, and table meta data inspector.
TOracleTableInfo TDbTableInfo class describes the meta data of a database table.
TDbCommandBuilder TDbCommandBuilder provides basic methods to create query commands for tables giving by setTableInfo the property.
TDbMetaData TDbMetaData is the base class for retrieving metadata information, such as table and columns information, from a database connection.
TDbTableColumn TDbTableColumn class describes the column meta data of the schema for a database table.
TDbTableInfo TDbTableInfo class describes the meta data of a database table.
TDataGatewayCommand TDataGatewayCommand is command builder and executor class for TTableGateway and TActiveRecordGateway.
TSqlCriteria Search criteria for TDbDataGateway.
TTableGateway TTableGateway class provides several find methods to get data from the database and update, insert, and delete methods.
TDiscriminator The TDiscriminator corresponds to the <discriminator> tag within a <resultMap>.
TSubMap TSubMap class defines a submapping value and the corresponding <resultMap>
TParameterMap TParameterMap corresponds to the <parameterMap> element.
TParameterProperty TParameterProperty corresponds to the <property> tag and defines one object property for the <parameterMap>
TResultMap TResultMap corresponds to <resultMap> mapping tag.
TResultProperty TResultProperty corresponds a <property> tags inside a <resultMap> tag.
TSqlMapCacheModel TSqlMapCacheModel corresponds to the <cacheModel> sql mapping configuration tag.
TSqlMapStatement TSqlMapStatement class corresponds to <statement> element.
TSqlMapTypeHandler A simple interface for implementing custom type handlers.
TCachingStatement TCacheingStatement class.
TMappedStatement TMappedStatement class executes SQL mapped statements. Mapped Statements can hold any SQL statement and use Parameter Maps and Result Maps for input and output.
TSqlMapObjectCollectionTree TSQLMapObjectCollectionTree class.
TResultSetListItemParameter TResultSetListItemParameter class
TResultSetMapItemParameter TResultSetMapItemParameter class.
TPreparedStatement TpreparedStatement class.
TStaticSql TStaticSql class.
TSqlMapGateway DataMapper client, a fascade to provide access the rest of the DataMapper framework. It provides three core functions:
TSqlMapManager TSqlMapManager class holds the sqlmap configuation result maps, statements parameter maps and a type handler factory.
TDbCommand TDbCommand class.
TDbConnection TDbConnection class
TDbDataReader TDbDataReader class.
TDbTransaction TDbTransaction class.
Translation Translation class.
TTextWriter TTextWriter class.
TAuthorizationRule TAuthorizationRule class
TUser TUser class
TApplication TApplication class.
TApplicationConfiguration TApplicationConfiguration class.
TApplicationComponent TApplicationComponent class
TEventParameter TEventParameter class.
TComponentReflection TComponentReflection class.
TLogger TLogger class.
TPageConfiguration TPageConfiguration class
THttpCookie THttpCookie class.
TUri TUri class
TUrlMappingPattern TUrlMappingPattern class.
TAutoCompleteTemplate TAutoCompleteTemplate class.
TBaseActiveControl TBaseActiveControl class provided additional basic property for every active control. An instance of TBaseActiveControl or its decendent TBaseActiveCallbackControl is created by TActiveControlAdapter::getBaseActiveControl() method.
TCachePageStatePersister TCachePageStatePersister class
TClientSideOptions TClientSideOptions abstract class.
TCompositeLiteral TCompositeLiteral class
TPageStatePersister TPageStatePersister class
TSessionPageStatePersister TSessionPageStatePersister class
TDataSourceSelectParameters TDataSourceSelectParameters class
TDataSourceView TDataSourceView class
TFont TFont class
TMetaTag TMetaTag class.
THotSpot THotSpot class.
TListItem TListItem class.
TRepeatInfo TRepeatInfo class.
TStyle TStyle class
TWebControlDecorator TWebControlDecorator class
TWizardSideBarTemplate TWizardSideBarTemplate class.
TWizardSideBarListItemTemplate TWizardSideBarListItemTemplate class.
TWizardNavigationTemplate TWizardNavigationTemplate class.
TXmlElement TXmlElement class.
Method Summary
void addParsedObject (string|TComponent $object)
void attachEventHandler (string $name, callback $handler)
boolean canGetProperty (string $name)
boolean canSetProperty (string $name)
void createdOnTemplate (TComponent $parent)
boolean detachEventHandler (string $name, callback $handler)
mixed evaluateExpression ( $expression)
string evaluateStatements (string $statements)
mixed getSubProperty (string $path)
boolean hasEvent (string $name)
boolean hasEventHandler ( $name)
boolean hasProperty (string $name)
void raiseEvent (string $name, mixed $sender, TEventParameter $param)
void setSubProperty (string $path, mixed $value)
void __call (string $name, mixed $params)
mixed __get (string $name)
void __set (string $name, mixed $value)
void __sleep ()
void __wakeup ()
Methods
addParsedObject (line 527)

Processes an object that is created during parsing template.

The object can be either a component or a static text string. This method can be overridden to customize the handling of newly created objects in template. Only framework developers and control developers should use this method.

void addParsedObject (string|TComponent $object)
  • string|TComponent $object: text string or component parsed and instantiated in template

Redefined in descendants as:
attachEventHandler (line 377)

Attaches an event handler to an event.

The handler must be a valid PHP callback, i.e., a string referring to a global function name, or an array containing two elements with the first element being an object and the second element a method name of the object. In Prado, you can also use method path to refer to an event handler. For example, array($object,'Parent.buttonClicked') uses a method path that refers to the method $object->Parent->buttonClicked(...).

The event handler must be of the following signature,

  1.  function handlerName($sender,$param{}
where $sender represents the object that raises the event, and $param is the event parameter.

This is a convenient method to add an event handler. It is equivalent to getEventHandlers($name)->add($handler). For complete management of event handlers, use getEventHandlers to get the event handler list first, and then do various TList operations to append, insert or remove event handlers. You may also do these operations like getting and setting properties, e.g.,

  1.  $component->OnClick[]=array($object,'buttonClicked');
  2.  $component->OnClick->insertAt(0,array($object,'buttonClicked'));
which are equivalent to the following
  1.  $component->getEventHandlers('OnClick')->add(array($object,'buttonClicked'));
  2.  $component->getEventHandlers('OnClick')->insertAt(0,array($object,'buttonClicked'));

  • throws: TInvalidOperationException if the event does not exist
  • access: public
void attachEventHandler (string $name, callback $handler)
  • string $name: the event name
  • callback $handler: the event handler
canGetProperty (line 246)

Determines whether a property can be read.

A property can be read if the class has a getter method for the property name. Note, property name is case-insensitive.

  • return: whether the property can be read
  • access: public
boolean canGetProperty (string $name)
  • string $name: the property name

Redefined in descendants as:
canSetProperty (line 258)

Determines whether a property can be set.

A property can be written if the class has a setter method for the property name. Note, property name is case-insensitive.

  • return: whether the property can be written
  • access: public
boolean canSetProperty (string $name)
  • string $name: the property name

Redefined in descendants as:
createdOnTemplate (line 514)

This method is invoked after the component is instantiated by a template.

When this method is invoked, the component's properties have been initialized. The default implementation of this method will invoke the potential parent component's addParsedObject. This method can be overridden.

void createdOnTemplate (TComponent $parent)
  • TComponent $parent: potential parent of this control

Redefined in descendants as:
detachEventHandler (line 389)

Detaches an existing event handler.

This method is the opposite of attachEventHandler.

  • return: if the removal is successful
  • access: public
boolean detachEventHandler (string $name, callback $handler)
  • string $name: event name
  • callback $handler: the event handler to be removed
evaluateExpression (line 468)

Evaluates a PHP expression in the context of this control.

  • return: the expression result
  • throws: TInvalidOperationException if the expression is invalid
  • access: public
mixed evaluateExpression ( $expression)
  • $expression
evaluateStatements (line 488)

Evaluates a list of PHP statements.

  • return: content echoed or printed by the PHP statements
  • throws: TInvalidOperationException if the statements are invalid
  • access: public
string evaluateStatements (string $statements)
  • string $statements: PHP statements
getEventHandlers (line 326)

Returns the list of attached event handlers for an event.

  • return: list of attached event handlers for an event
  • throws: TInvalidOperationException if the event is not defined
  • access: public
TList getEventHandlers ( $name)
  • $name
getSubProperty (line 271)

Evaluates a property path.

A property path is a sequence of property names concatenated by '.' character. For example, 'Parent.Page' refers to the 'Page' property of the component's 'Parent' property value (which should be a component also).

  • return: the property path value
  • access: public
mixed getSubProperty (string $path)
  • string $path: property path
hasEvent (line 307)

Determines whether an event is defined.

An event is defined if the class has a method whose name is the event name prefixed with 'on'. Note, event name is case-insensitive.

  • access: public
boolean hasEvent (string $name)
  • string $name: the event name
hasEventHandler (line 315)
  • return: whether an event has been attached one or several handlers
  • access: public
boolean hasEventHandler ( $name)
  • $name
hasProperty (line 231)

Determines whether a property is defined.

A property is defined if there is a getter or setter method defined in the class. Note, property names are case-insensitive.

  • return: whether the property is defined
  • access: public
boolean hasProperty (string $name)
  • string $name: the property name

Redefined in descendants as:
raiseEvent (line 415)

Raises an event.

This method represents the happening of an event and will invoke all attached event handlers for the event.

  • throws: TInvalidDataValueException If an event handler is invalid
  • throws: TInvalidOperationException if the event is undefined
  • access: public
void raiseEvent (string $name, mixed $sender, TEventParameter $param)
  • string $name: the event name
  • mixed $sender: the event sender object
  • TEventParameter $param: the event parameter
setSubProperty (line 287)

Sets a value to a property path.

A property path is a sequence of property names concatenated by '.' character. For example, 'Parent.Page' refers to the 'Page' property of the component's 'Parent' property value (which should be a component also).

  • access: public
void setSubProperty (string $path, mixed $value)
  • string $path: property path
  • mixed $value: the property path value
__call (line 202)

Calls a method.

Do not call this method. This is a PHP magic method that we override to allow using the following syntax to call a property setter or getter.

  1.  $this->getPropertyName($value)// if there's a $this->getjsPropertyName() method
  2.  $this->setPropertyName($value)// if there's a $this->setjsPropertyName() method

  • throws: TInvalidOperationException If the property is not defined or read-only.
  • access: public
void __call (string $name, mixed $params)
  • string $name: the getter or setter method name
  • mixed $params: method call parameters

Redefined in descendants as:
__get (line 122)

Returns a property value or an event handler list by property or event name.

Do not call this method. This is a PHP magic method that we override to allow using the following syntax to read a property:

  1.  $value=$component->PropertyName;
  2.  $value=$component->jsPropertyName// return JavaScript literal
and to obtain the event handler list for an event,
  1.  $eventHandlerList=$component->EventName;

  • return: the property value or the event handler list
  • throws: TInvalidOperationException if the property/event is not defined.
  • access: public
mixed __get (string $name)
  • string $name: the property name or the event name

Redefined in descendants as:
__set (line 162)

Sets value of a component property.

Do not call this method. This is a PHP magic method that we override to allow using the following syntax to set a property or attach an event handler.

  1.  $this->PropertyName=$value;
  2.  $this->jsPropertyName=$value// $value will be treated as a JavaScript literal
  3.  $this->EventName=$handler;

  • throws: TInvalidOperationException If the property is not defined or read-only.
  • access: public
void __set (string $name, mixed $value)
  • string $name: the property name or event name
  • mixed $value: the property value or event handler

Redefined in descendants as:
__sleep (line 546)

Returns an array with the names of all variables of that object that should be serialized.

Do not call this method. This is a PHP magic method that will be called automatically prior to any serialization.

  • access: public
void __sleep ()

Redefined in descendants as:
__wakeup (line 535)

Do not call this method. This is a PHP magic method that will be called automatically after any unserialization; it can perform reinitialization tasks on the object.

  • access: public
void __wakeup ()

Redefined in descendants as:

Documentation generated on Mon, 25 Jun 2012 14:37:36 +0200 by phpDocumentor 1.4.3