Components: Introduction

A component is an instance of TComponent or its child class. The base class TComponent implements the mechanism of component properties and events.

Component Properties

A component property can be viewed as a public variable describing a specific aspect of the component, such as the background color, the font size, etc. A property is defined by the existence of a getter and/or a setter method in the component class. For example, in TControl, we define its ID property using the following getter and setter methods,

class TControl extends TComponent {
    public function getID() {
        ...
    }
    public function setID($value) {
        ...
    }
}

To get or set the ID property, do as follows, just like working with a variable,

$id = $component->ID;
$component->ID = $id;

This is equivalent to the following,

$id = $component->getID();
$component->setID( $id );

A property is read-only if it has a getter method but no setter method. Since PHP method names are case-insensitive, property names are also case-insensitive. A component class inherits all its ancestor classes' properties.

Subproperties

A subproperty is a property of some object-typed property. For example, TWebControl has a Font property which is of TFont type. Then the Name property of Font is referred to as a subproperty (with respect to TWebControl).

To get or set the Name subproperty, use the following method,

$name = $component->getSubProperty('Font.Name');
$component->setSubProperty('Font.Name', $name);

This is equivalent to the following,

$name = $component->getFont()->getName();
$component->getFont()->setName( $name );

Js-friendly properties

A JavaScript-friendly property is a property that can accept both simple strings and raw javascript. Prado automatically encodes all properties sent clientside inside javascript blocks to avoid security problems (like injections or cross site scripting). If a property is known to always contain only safe javascript code and its value needs to bypass this encoding, that property can be defined in a special way that will make Prado mark its value as "safe". Js-friendly properties are identified by their name starting with 'js' (case insensitive):

// getter, defines a readable property 'Text'
function getJsText() { … }
// setter, defines a writable property 'Text', with $value being the value to be set to the property
function setJsText(TJavaScriptLiteral $value) { … }

Js-friendly properties can be accessed using both their Js-less name and their Js-enabled name:

// set some simple text as property value
$component->Text = 'text';
// set some javascript code as property value
$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.

Namespaces

A namespace refers to a logical grouping of some class names so that they can be differentiated from other class names even if their names are the same. Historically PHP did not support namespaces, so all PRADO classes are prefixed with a letter 'T' (meaning 'Type') to differentiate from user defined classes. Nowadays that PHP has native support for namespaces, users are advised to use it when possible.

PRADO has an internal support for namespaces that predates PHP namespac support. A namespace in PRADO is considered as a directory containing one or several class files. A class may be specified without ambiguity using such a namespace followed by the class name. Each namespace in PRADO is specified in the following format,

PathAlias.Dir1.Dir2

where PathAlias is an alias of some directory, while Dir1 and Dir2 are subdirectories under that directory. A class named MyClass defined under Dir2 may now be fully qualified as PathAlias.Dir1.Dir2.MyClass.

To use a namespace in code, do as follows,

Prado::using('PathAlias.Dir1.Dir2.*');

which appends the directory referred to by PathAlias.Dir1.Dir2 into PHP include path so that classes defined under that directory may be instantiated without the namespace prefix. You may also include an individual class definition by

Prado::using('PathAlias.Dir1.Dir2.MyClass');

which will include the class file if MyClass is not defined.

For more details about defining path aliases, see application configuration section.

Component Instantiation

Component instantiation means creating instances of component classes. There are two types of component instantation: static instantiation and dynamic instantiation. The created components are called static components and dynamic components, respectively.

Dynamic Component Instantiation

Dynamic component instantiation means creating component instances in PHP code. It is the same as the commonly referred object creation in PHP. A component can be dynamically created using one of the following two methods in PHP,

$component = new ComponentClassName;
$component = Prado::createComponent('ComponentType');

where ComponentType refers to a class name or a type name in namespace format (e.g. System.Web.UI.TControl). The second approach is introduced to permit the creation of classes using Prado's namespace format and ther automatic configuration of new classes via configuration directives.

Static Component Instantiation

Static component instantiation is about creating components via configurations. The actual creation work is done by the PRADO framework. For example, in an application configuration, one can configure a module to be loaded when the application runs. The module is thus a static component created by the framework. Static component instantiation is more commonly used in templates. Every component tag in a template specifies a component that will be automatically created by the framework when the template is loaded. For example, in a page template, the following tag will lead to the creation of a TButton component on the page,

<com:TButton Text="Register" />