Upgrading from v2.x and v1.x

PRADO v3.0 is NOT backward compatible with earlier versions of PRADO.

A good news is, properties and events of most controls remain intact, and the syntax of control templates remains largely unchanged. Therefore, developers' knowledge of earlier versions of PRADO are still applicable in v3.0.

We summarize in the following the most significant changes in v3.0 to help developers upgrade their v2.x and v1.x PRADO applications more easily, if needed.

Component Definition

Version 3.0 has completely discarded the need of component specification files. It relies more on conventions for defining component properties and events. In particular, a property is defined by the existence of a getter method and/or a setter method, while an event is defined by the existence of an on-method. Property and event names in v3.0 are both case-insensitive. As a consequence, developers are now required to take care of type conversions when a component property is being set. For example, the following code is used to define the setter method for the Enabled property of TControl, which is of boolean type,

public function setEnabled($value)

where TPropertyValue::ensureBoolean() is used to ensure that the input value be a boolean. This is because when the property is configured in template, a string value is passed to the setter. In previous versions, PRADO knows the property type based on the component specification files and does the type conversion for you.

Application Controller

Application controller now implements a modular architecture. Modules can be plugged in and configured in application specifications. Each module assumes a particular functionality, and they are coordinated together by the application lifecycle. The concept of v2.x modules is replaced in v3.0 by page directories. As a result, the format of v3.0 application specification is also different from earlier versions.


Pages in v3.0 are organized in directories which may be compared to the module concept in v2.x. Pages are requested using the path to them. For example, a URL index.php?page=Controls.Samples.Sample1 would be used to request for a page named Sample1 stored under the [BasePath]/Controls/Samples directory, where [BasePath] refers to the root page path. The file name of a page template must be ended with .page, mainly to differentiate page templates from non-page control templates whose file names must be ended with .tpl.

Control Relationship

Version 3.0 redefines the relationships between controls. In particular, the parent-child relationship now refers to the enclosure relationship between controls' presentation. And a new naming-container relationship is introduced to help better manage control IDs. For more details, see the controls section.

Template Syntax

The syntax of control templates in v3.0 remains similar to those in earlier versions, with many enhancements. A major change is about the databinding expression. In v3.0, this is done by the following,

<com:MyComponent PropertyName=<%# PHP expression %> .../>

Expression and statement tags are also changed similarly. For more details, see the template definition section.

Theme Syntax

Themes in v3.0 are defined like control templates with a few restrictions.