PHP开发利器－PRADO 1.6

第1章 入门
1.1  PRADO是什么?

　　PRADO是在PHP5环境下的一个基于事件驱动和基于组件的WEB应用开发框架。使用PRADO开发WEB应用，你主要需要做的工作就是使用已有的组件（原文是"实例化已经定义好的组件"，熟悉面向对象编程的开发者可能比较容易理解这句话），设置组件的属性，为控件组件的各种事件编写对应的处理函数，然后把这些组织成一个个的页面。（译者注：个人倾向于将component翻译为组件，control翻译为控件，事实上大多数场合两者没有什么区别，但是为了读者能够更加容易理解原文，本文一律按此规则翻译。）这个过程和使用RAD开发工具（比如Delphi或者Visual Basic）来开发Windows应用程序非常类似。

　　下面用一个简单的例子来说明PRADO框架的工作原理。假定我们现在要使用PRADO来开发一个常见的登录页面。首先我们选择PRADO中的2个TTextBox控件和1个TButton控件来分别对应用户名输入，密码输入和提交按钮。然后把对应密码输入的TTextBox控件的TextMode属性设置为"Password"，并为TButton控件的onClick事件指定一个处理函数login。最后把这些控件放到页面模板的合适的位置上（后面会解释什么是页面模板，实际上它和一个html页面很相似），一个功能完善的登录页面就实现了。控件会自己处理好如何显示数据，如何得到用户输入的数据，如何响应用户的操作等这些事情。例如，TTextBox控件会显示一个输入框让用户输入；用户输入的密码会被显示为*号，而开发者在代码中可以通过读取TTextBox控件的Text属性来获取用户实际输入的密码；当用户点击了提交按钮的时候，login 函数将会被自动调用。这和传统的PHP编程处理方式很不一样。使用传统的PHP编程方式，开发人员需要使用HTML标签来显示用户输入框和按钮，同时需要自己解析POST数据来获得用户的输入以及判断按钮是否被点击了等等这些事情。

PRADO

　　基于组件的编程方式使代码的重用极为方便。一些重复性的单调的工作比如表单输入的验证，页面状态的管理等都可以使用PRADO已经提供的组件来处理。开发者也可以通过继承现有的组件或者组合现有的组件来开发新的组件满足要求。另外一些新的组件即将发布。

　　总来的说，PRADO 为PHP的编程人员提供了以下的有益之处：

可重用性 - 符合PRADO组件标准的代码是高度可重用的。
易于使用 - 使用PRADO组件非常简单，通常只需要配置它们的属性，编写相关的事件处理函数。
健壮性 - PRADO让开发者不再被那些令人厌烦的有很多错误的的代码所困扰。它的代码都是有对象，方法和属性组成的；而不是Url地址和各种query参数。PHP5最新的Exception处理机制也被引入进来，让开发人员能够精确定位到错误代码的所在行数。
高效 - PRADO开发的Web应用运行很快。PRADO实现了一种缓存机制，使用其开发的应用的运行效率能够和那些通常使用的模版引擎开发的应用的运行效率相媲美。
团队协作 - PRADO允许内容和表现方式分离。组件，尤其是页面，将内容（逻辑）和表现方式分别保存在不同的文件中。
　　目前已经有很多PHP的框架，Mojavi, WACT , PHP.MVC, Phrame等等。它们主要是建立一套松散的PHP代码组织方式（比如 Model-view-controller）。其中一些更多的面向开发一个内容管理系统，并提供了诸如用户管理模块等更多的功能。

　　和这些框架相比，PRADO更专注于建立一个代码重用和事件驱动的编程标准。如果你曾经用Delphi或者Visual Basic等这些RAD开发工具来开发Windows程序的话，那么你会发现使用PRADO来开发WEB应用是非常类似的，你可以很快就掌握PRADO来进行WEB应用的开发。大多数情况下，你要做的仅仅是设置组件的属性和响应组件的事件。更高层次的代码重用，比如前面所说的用户管理模块，可以基于PRADO组件来实现。

　　PRADO的思想最先我是从Apache Tapestry项目想到的。在设计和实现的时候， Borland Delphi 和Microsoft ASP.NET的设计思想起到了很重要的作用 。实际上，使用过ASP.NET的人可以发现PRADO中有很多地方和它是相似的。

1.2  安装

　　PRADO需要PHP5的环境，以及SimpleXML模块（PHP5缺省安装后的环境下已经包括了这个模块）。在Windows XP和RedHat Linux环境下，已经在Apache和IIS Web服务器上都通过了测试。

　　PRADO框架使用一个.zip文件发布。在Linux下可以使用unzip，在Windows下可以使用Winzip来解压。解压完毕后，会在当前目录下创建一个目录prado。这个目录主要包括以下这些文件和目录：

 README.html            此项目的说明文件 index.html             和README.html中的内容是一样的 COPYRIGHT              此项目的版权信息 HISTORY                版本升级信息 framework/             PRADO框架的核心代码 examples/              PRADO的一些例子 docs/                  PRADO的帮助文档
　　完成了解压之后，把prado目录的所有东西复制到Web服务器的根目录下。（也可以把它复制到某一个子目录下，甚至更深层次的目录下，PRADO对此没有限制。如果你将它复制到了某一个子目录下，以下的URL地址需要做相应的修改。）

　　非常简单，安装已经完成了!现在你可以试一下PRADO发布包中的三个例子了：``Hello, world!", the Hangman Game（一个猜单词的游戏）, 和PRADO通讯录，它们的URL地址是：

``Hello, world!" - http://<Web-server-address>/examples/helloworld.php
the Hangman game - http://<Web-server-address>/examples/hangman.php
the PRADO phonebook - http://<Web-server-address>/examples/phonebook.php

1.3  范例: Hello, World!

　　在这一节中，我们主要来说明``Hello, world!''''

　　这个例子，让你对使用PRADO开发有一个印象。这个例子非常的简单，只有一个页面，上面显示了一个"Click me"的按钮。当用户点击了这个按钮，这个按钮的标题会变成``Hello, world!''''。

　　要完成这个功能需要这些文件,

helloworld.php , 应用的主入口;
helloworld/application.spec, 应用的配置文件;
helloworld/HomePage.php, 页面的类文件;
helloworld/HomePage.tpl, 页面的模板文件.
　　注意，目录 helloworld 应该设置为Web用户不可以访问的（读的权限也不能给），因为其中的文件包括了一些重要的数据信息（比如数据库的连接口令等等）。不用担心这么设置Web用户会不能正常的访问，因为实际上他们根本不用去访问helloworld 目录中的文件。在其它使用PRADO开发的应用中你也应该这么做。

　　在helloworld.php 文件中，程序主要是实例化 TApplication 这个类，（译者注：如果对实例化这个词不怎么理解，你也可以这么理解，就是申明一个类型为TApplication的变量。）并开始运行应用，代码如下：

 <?php require_once(''../framework/TApplication.php''); $app=TApplication::getInstance(''helloworld/application.spec''); $app->run(); ?>

　　这里我们假定框架的代码位于 ../framework 目录下。

　　每一个 PRADO应用都应该有这么一个入口文件。他们之间主要的区别在于 getInstance
函数的参数的不同，这个参数指明了应用的配置文件的位置。

application.spec 是一个XML文件，用来配置应用级别的参数。（就好象全局变量一样，当然现在是只读的，我们正在决定是否下一版本中允许可读写的）在这个例子中，它包含了如下的代码：

 <?xml version="1.0" encoding="UTF-8"?> <application default-page="HomePage" cache-path="">    <alias name="Pages" path="." />    <using namespace="System.Web.UI.WebControls" />    <using namespace="Pages" /> </application>
  <alias> 元素（译者注：按XML文件通常的译法，<alias>...</alias>整个翻译为元素，其中alias翻译为元素的标签，一对闭合的alias标签中的值翻译为元素值，name, path这些则翻译为属性名，它们的值翻译为属性值，参考"<标签 属性名= 属性值>元素值</标签>"）定义了路径的别名。别名System 是系统内部定义好的，用来指示框架核心代码所在的目录。可以使用路径别名来定义命名空间。命名空间实际上就是一个加入到PHP搜索路径 include_path中的目录。 <using> 元素指明启动应用使用的命名空间。(也可以在代码中调用 using() 函数来使用一个命名空间)

  <application> 的default-page 属性指明了应用启动时缺省进入哪一个页面。在这里我们指定了HomePage页面，它对应了一个页面类HomePage （关于页面和页面类后面会专门对它们进行解释的）。

　　HomePage.tpl 文件是页面类HomePage一个模板文件，包含如下的代码：

 <html> <head> <title>Hello, world!</title> </head> <body>   <com:TForm>     <com:TButton Text="Click me" onClick="clickMe" />   </com:TForm> </body> </html>
　　它和HTML页面非常的相似。唯一不同的地方就是元素 <com:TButton> ，它代表了一个
TButton 组件。 TButton 组件将会显示为一个表单的按钮，按钮的标题是"Click Me"，"Click
Me"是在 Text 属性中被指定的。通过设置 onClick ，可以指定页面方法 clickMe 来响应按钮的 onClick 事件。因此，当按钮被点击的时候，方法 clickMe 就会被自动调用了。

  HomePage.php 文件包含了定义页面类 HomePage 的代码，如下：

 <?php class HomePage extends TPage {    function clickMe($sender,$param)    {        $sender->Text="Hello, world!";    } } ?>

HomePage 类继承了 TPage 类。TPage 类是PRADO框架本身提供的，它是所有页面类的基类。HomePage 类只包含了一个方法clickMe ，这个方法就是刚才我们提到的页面模板中响应按钮onClick 事件的方法clickMe  。这个方法的代码的作用是设置事件的发送者$sender（这里就是这个按钮）的Text 属性为 ``Hello, world!"。我们期望当用户点击这个按钮的时候，按钮的标题改为``Hello, world!" 。
　 这个包含在 PRADO 发布包中的例子可以通过此URL来访问：href="http:///examples/helloworld.php''>http:///examples/helloworld.php">http://<Web-server-address>/examples/helloworld.php
.
　　你可能会说完成这么一个简单的功能有什么大惊小怪的。是的，这个功能确实非常简单，用几行php代码就可以完成。但是这个例子主要是目的是为了让你感受一下PRADO编程方式，它是面向对象的，基于组件和基于事件驱动的。用类似的编程方式可以实现更复杂的功能，请继续看下面几章。

 

[下一页]

 

第2章 用PRADO编程
　　现在让我们更深入的了解一下PRADO框架。这一章我们会介绍一些框架的基本概念和如何使用现有的PRADO组件来开发一个PRADO应用。

2.1  组件

　　根据Clemens Szyperski的说法， ``软件组件是一个具有特定接口的组合单元，可以独立存在，参与组成其它组建。''''

　　在PRADO中, 组件是 TComponent 或者其子类的实例。PRADO框架中已经包括了 TComponent
类，它主要实现了组件的属性和事件机制。

属性可以被认为是描述组件某一特性的公共变量，比如背景颜色，字体大小等等。属性是有类型的，比如 string, integer , 等等。属性可以是只读的，也可以是可读写的。
事件使代理函数可以对组件中进行的一些活动作出响应，比如鼠标的点击，输入文本的变化等。

　　一个组件会继承它所有父类组件的属性和方法，因为组件本身其实就是一个类。

　　一个完整的组件类定义包括两个文件：

一个类文件，它定义了组件类的逻辑。这个文件主要是PHP代码。这个文件的文件名必须和类的名字一样，而且以.php 作为文件后缀。
一个规格文件，它定义了组件类的属性和方法。这个文件是XML格式。如果这个组件类没有定义父类之外的新的属性和事件，那么这个文件是可以省略不要的。缺省情况下，这个文件和组件的类文件在一个目录中，而且名字是一样的，唯一不同的是它们的文件名后缀（类文件的后缀是.php ，规格文件是 .spec ）。值得注意的是，PRADO也允许你用不同的文件名来命名规格文件和模板文件，但是类文件名还是必须遵循与类同名，并且后缀为.php 的规则的。这时候你需要在类的常量SPECIFICATION_FILE中指定规格文件的包含路径的文件名，可以使用绝对或者相对路径（相对类文件所在位置）。

　　注意：PRADO 是区分大小写的，组件类型，属性名称，事件名称，文件名等等这些都是区分大小写的。

　　2.1.1  控件

　　控件是定义了用户界面的PRADO 组件。每一个控件都有一个父控件和一些子控件（注意，这里的父，子这些关系和面向对象中的父类子类的概念是完全不一样的。一个控件是另外一个控件的父控件只是说明了前者拥有后者，这个拥有关系可以理解为一个目录下包含了一个子目录；而绝不是后者是前者的子类、是从前者继承而来的这个概念）。页面是最高级别的控件，它没有父控件（当然你也可以认为Application是它的父控件）。一个PRADO的应用是一个页面的集合，每一个页面都代表了一个层次树状结构的控件集，控件与控件之间关系是通过父子关系联系在一起的。

　　这种父子关系可以通过模板文件来建立。模板文件的格式和HTML是很像的，只不过在HTML的基础上增加了一些特殊的标签来定应控件。如果一个控件的标签被另外一个控件的标签所包括，那么前者就被认为是后者的子控件。静态文本也被认为是子控件。

　　控件可以拥有一个模板文件来描述它的界面内容。缺省情况下模板文件和类文件在同一个目录下，而且文件名是相同的，模板文件的后缀则为 .tpl 。同规格文件一样，如果你需要把模板文件放在不同地方或者用鳖的文件名，可以通过设置类常量 TEMPLATE_FILE 的值来指明模板文件的位置。

　　每一个控件都有一个ID，它可以在同一级别的控件中来唯一标识控件本身。ID路径则是在控件的树状结构中，从当前控件到目标控件的所有控件ID的序列，它可以用于访问一个控件。比如，在
HomePage中，有一个 Menu 控件，它拥有一个子控件 Button 。对于控件HomePage而言，可以通过ID(Menu,Button)路径来访问 Button 控件。如果用PHP代码来书写，就是 $this->Menu->Button .

　　2.1.2  实例化组件

　　组件有两种方式来实例化。一种方法是在一个控件的模板文件中定义它，当这个控件被创建的时候，框架会自动的去实例化这个组件。还有一种方法是在PHP代码中手动的实例化。我们先来看一下前面一种静态的创建方法，稍后再来看一下动态的创建方法。

　　静态创建组件
　　通常只有控件在模板文件中被静态创建。

　　一个控件在模板文件组件标签来声明，其语法如下：

 ......
<com:ComponentType ID="..." PropertyName="..." EventName="...">
    ....body contents....
</com:ComponentType>
......
　　这里  ComponentType, PropertyName, 和 EventName 应该被真正的组件类名，属性名和事件名所替代。 ID 属性是可选的。如果定义了ID 属性，那么ID 的值必须在平级的控件中是唯一的。如果没有定义，那么框架会自动为这个控件分配一个唯一的ID的。当然，这要求组件的标签被正确的嵌套，每一个开放的组件标签都应该和一个闭合的组件标签组成一对，这个规则和XML的规则是一样的。（译者著：如果你对XML一点都不了解，建议你先看一下一些基本的XML概念，要求并不高，你只需要知道如何正确书写一个XML文件即可。）

　　注意：控件的ID必须是一个以字母开头的，后面只包含字母，数字和下划线的字符串。

　　模板文件中属性的初始值字符串会被自动转换为正确的属性类型。目前有六种属性类型： string, integer, float, boolean, array  face="Courier New">和 object. 前面三种类型的字符串格式是非常简单的。 boolean 类型只允许使用两个字符串: true  face="Courier New">和 false。 array 类型接受如 (value1,value2,key3=>value3,...) 格式一样的字符串，这和 PHP 数组的初始化是一样的。 而 object 类型就比较复杂了，它取决于属性是如何被定义的。一些属性可以允许使用字符串，并会把它转换为对象，但是有些属性就不行了。

　　当组件被创建（实例化）的时候，通过规格文件定义的组件的属性和对应事件处理方法就会立刻生效了。

　　动态创建组件

　　PRADO

　　允许开发者在自己的PHP代码中实例化组件。组件可以通过调用一个静态类方法Application::createComponent($type)来被实例化，该方法的参数$type 指明了要创建的组件的名称。组件也可以使用new 操作符来实例化。这两者方法的区别是：前者会使用一种缓存机制，下一次创建相同的组件时速度会快很多；而后者不会使用缓存机制，每次都要完全重复执行实例化的步骤。通常情况你应该使用TApplication::createComponent($type) 来实例化（如果你想了解更多，请参考下面的注释）。

　　如果新创建的组件是一个控件，那么可以通过调用把这个控件作为其他控件的子控件。注意，如果你需要指定这个控件的ID，应该在将它添加作为其他控件的子控件之前就指定ID；否则的话框架会自动为它分配一个ID，而且这个ID是不能更改的。

　　注：如果在构造函数中使用或申请了资源句柄的话，只能使用 new 操作符来实例化。因为PRADO使用了缓存机制来实例化组件，因此如果在构造函数中使用了资源句柄的话，下次实例化的时候从缓存读出来的数据中的资源句柄部分依然对应着原来的那块内存地址，这样就极容易导致系统崩溃。所以如果你要设计一个自己的组件，也尽可能的不要在构造函数中使用和申请资源句柄，而是应该把这些代码组织在一个别的方法中，在页面的OnInit事件或其它事件中调用。一般来说构造函数只需要实现简单的变量初始化即可。在PRADO的核心代码中，所有的组件的构造函数都没有使用到资源句柄。你在开发自己的组件的时候，可以参考一下它们的源代码。

　　2.1.3  访问组件属性

　　PHP 5 使用了一种很好的方式来访问组件的属性。你可以把一个组件的属性当作组件的成员变量来使用。比如要设置TButton 控件的Text 属性，你可以使用$button->Text="xxx"的代码，这里$button 代表了控件的实例。对于控件来说，你还可以使用它的ID路径来访问属性。假定现在HomePage页面有一个子控件MenuBar ，MenuBar 控件有一个子控件HyperLink ，那么在页面环境中，可以使用的代码$this->MenuBar->HyperLink->NavigateUrl来读取HyperLink 控件的NavigateUrl 属性。

　　注意，由于PHP5.0中的一个BUG，如果你需要设置一个属性的值，那么你必须首先通过它的控件的ID路径来获得控件，然后再来设置这个属性的值。在上面这个例子中，需要用下面两行代码来设置NavigateUrl 属性。

 $link=$this->MenuBar->HyperLink; $link->NavigateUrl="...";

　　如果直接使用 $this->MenuBar->HyperLink->NavigateUrl 来设置属性值会产生一个错误。但是你还可以下面这段代码来设置属性的值，这样就可以避免那个错误了。

 $this->MenuBar->HyperLink->setNavigateUrl("...");

　　2.1.4  使用事件

　　事件响应函数通常在规格文件或者模板文件中指定给对应的事件，指定事件响应函数和指定属性的初始值是类似的。注意，在规格文件或者模板文件中指定的事件响应函数，必须在此规格文件或模板文件对应的组件中定义，它的语法如下：

 function handlerName($sender,$param) {    ... }

　　这里 $sender 指向的是触发这个事件的控件， $param 是事件的参数，它的内容取决于事件的类型。

　　在编程的时候也可以使用TComponent::addEventHandler() 方法来动态的指定一个事件响应方法。

　　你可以为一个事件指定多个响应方法。当这个事件被触发的时候，所有指定的响应方法都被自动调用。所以，PRADO实现的是多点派发事件触发机制。

　　2.1.5  数据绑定（Data Binding）

 

　　只有控件才可以数据绑定。

　　你可以给控件的属性绑定一个表达式，当这个控件的dataBind() 方法被调用的时候，这个属性的值回自动被设置为这个表达式的值。数据绑定在开发数据组件时是非常有用的，这些组件的很多属性值都是来源于数据源提供的数据的。你可以在组件的规格或者模版文件中设定数据绑定，也可以在代码中设定。

　　在模版中设定数据绑定的话，只要给属性的值指定一个有效的PHP表达式的字符串，并在前面加上一个# 作为前缀。比如在页面模版文件中使用如下的代码：

 <com:TLabel Text="#$this->Page->ID" />

　　这段代码给TLabel 组件的Text 属性绑定了一个的表达式$this->Page->ID 。这个表达式的作用是获得当前控件所在页面的ID。注意，这个表达式中的$this指的是TLabel控件本身，因为$this所在上下文环境是在TLabel 中。

　　在代码中要设定数据绑定，可以调用组件的bindProperty() 方法，这时候不需要在前面加上字符# 。

　　注意，给属性绑定的表达式只有在dataBind() 被调用时才会计算该表达式的值，并把它赋值给属性。具体内容可以参考dataBind() 的相关文档。

　　另外，如果在模板文件中你需要给一个属性赋初始值，而不是数据绑定的话，如果这个值是以#开头的，那么应该将#重复一次，就像PropertyName="##...." 一样。

 

[下一页]

　　2.1.6  PRADO 组件类树

　　目前发布的 PRADO 包括如下所示的组件树，这些组件的属性，事件和类的方法在PRADO文档中都可以查到。

TComponent
    TAdodb
    TControl
        TExpression
        TForm
        TLiteral
        TPage
TPlaceHolder
        TRepeater
TRepeaterItem
        TStatements
        TWebControl
            TButton
            TCheckBox
                TRadioButton
            TDropDownList
            THyperLink
            TImage
                TImageButton
            TLabel
            TLinkButton
            TListBox
            TPanel
            TTextBox
                TDatePicker
                THtmlArea
            TValidationSummary
            TValidator
                TCompareValidator
                TCustomValidator
                TRangeValidator
                TRegularExpressionValidator
                    TEmailAddressValidator
                TRequiredFieldValidator
2.2  页面

　　页面是 TPage 或者它的子类的一个实例。它是最高级别的组件，即没有父组件也不包含在一个容器中。PRADO的应用是由一些页面组成的。

　　2.2.1  页面的生命周期

　　理解页面的生命周期对掌握PRADO编程是非常重要的。

　　首先我们要介绍一下postback的概念。我们把一个form的提交称之为postback，如果form的数据是提交给包含该form的页面的。postback可以被认为是由用户在客户端触发的一个事件。PRADO会区分出把postback事件交给哪一个服务器端的组件来响应。如果找到了这个组件，比如是一个TButton
，那么我们就把这个TButton 组件称为事件的发送者(sender)。

　　页面在被请求调用的时候会经过几个状态。当一个页面是由于它发生了一个postback而被调用的时候，这个页面会经历以下的生命周期：

页面的创建：页面和它所有子组件是被递归创建的。框架根据各个组件的规格文件和模板文件的配置来初始化组件的属性。你一个可以重载页面的构造函数来做一些其他的初始化工作，比如给一些属性赋一些缺省值。但是需要注意的是，在这一步的时候，是不能够访问其他组件，因为组件之间的关系这时候还没有被建立。
OnInit 事件： OnInit 事件会被广播给整个页面的组件树（也就是说所有的组件都会被触发OnInit事件）。可以重载页面的onInit() 方法或者给OnInit事件指定一个处理方法来做一些初始化的工作，比如建立数据库连接等等。这时候组件和组件的关系已经被建立了。
导入显示状态（Viewstate）：将先前的显示状态导入到页面中。页面自己会将上次显示给用户看的状态保存起来。关于显示状态，下一章会有更详细的解释。
导入提交的数据：页面中的一些组件的属性会根据用户提交的数据而更新。比如，TTextBox 组件的Text 属性会被用户在此组件的文本输入框中输入的文本而更新。
OnLoad 事件：在这个阶段，页面会设置为提交前用户看到的状态。OnLoad
事件也会被广播给整个页面的组件树。同样也可以重载onLoad() 方法或者给OnLoad 事件指定一个处理函数。
导入提交的数据：一些在OnLoad 步骤创建的组件在这时候有机会导入提交的数据。
产生提交数据变化事件。如果一个组件的数据被用户改变了，那么就会机会产生一个事件来指明这个变化。比如用户改变了一个TTextBox 组件的文本输入框的值，那么这个TTextBox 组件就会触发一个OnTextChanged 事件。开发者能够为这个事件指定处理方法。
输入验证：如果事件的提交者需要验证，这时候页面注册的验证组件会来对应的数据。
Postback事件：postback事件通过事件的发送者被触发。比如，用户点击了一个按钮引起了一次postback，那么这个按钮对应的TButton 组件就触发一个事件onClick。你可以指定这个事件的处理函数来响应这个事件。
OnPreRender 事件：在这一步，页面已经完成了被提交的数据的导入和postback事件的处理。OnPreRender 事件会被广播给整个页面的组件树 。在页面被绘制之前，你可以重载onPreRender() 函数或者给OnPreRender 事件指定一个事件处理函数。
整个页面的组件树的显示状态被保存在一个固定的存储空间（比如表单的隐藏字段，session，或者数据库中）。
通过递归的方式页面类来显示这个页面，页面中的组件会自己显示自己（意思是说每一个组件都会负责显示它自己）。通常情况下，组件会在对应所在模板的位置上来显示自己。你也可以重载TComponent 的render() 方法来自己控制组件的显示。
OnUnload 事件：页面和它所有的子组件从内存中被释放。同样，这个事件也会被广播给整个页面的组件树。你可以通过重载onUnload() 函数或者给OnUnload 事件指定一个处理函数来完成一些清除工作，比如断开数据库的连接等等。
　　当页面是第一次被请求的时候，上述的生命周期会简单一些。具体来说，导入显示状态，导入提交的数据，产生提交数据变化事件，输入验证和postback事件这几个状态是没有的。

2.3  应用

　　每一个 PRADO Web应用都有且只有一个的实例。它主要是负责编码解码用户请求，服务器的页面请求，和维护应用级别的参数。

　　2.3.1  应用的配置

　　每一个PRADO应用都应该有一个XML格式的配置文件。在"hello world"这个例子中，这个文件的文件名为 application.spec .

　　应用配置文件的格式如下：

 <?xml version="1.0" encoding="UTF-8"?> <application default-page="..." cache-path="..."              session-class="..." user-class="...">    <alias name="..." path="..." />    <alias name="..." path="..." />    <using namespace="..." />    <using namespace="..." />    <secured page="..." role="..." />    <secured page="..." role="..." />    <parameter name="...">...</parameter>    <parameter name="...">...</parameter>    <parameter file="..." /> </application>

　　alias 元素定义了文件路径的别名，路径可以是绝对是绝对路径也可以是相对路径。

　　using 元素定义了要增加到 PHP搜索路径 include_path 变量中的命名空间。命名空间是用"."号连接的。第一段是路径的别名，之后是子目录。比如System.Web.UI 代表了框架所在目录下的Web/UI/子目录。框架的目录的别名已经被定义成System 。在编程的时候，也可以调用using() 函数来增加一个命名空间。

　　secured 标签知名了页面是否需要验证/授权，page 属性指名的是页面的名称或者是页面名称的匹配表达式。如果一个页面被标明是的，那么说明这个页面需要用户验证的。另外如果role 属性不是空的，那么要求用户是属于指定的角色的。

　　parameter 元素定义了用户参数。可以通过设置parameter 元素的file 属性来导入一个参数文件。参数文件的格式如下：

 <?xml version="1.0" encoding="UTF-8"?> <parameters>    <parameter name="...">...</parameter>    <parameter name="...">...</parameter> </parameters>

　　default-page 属性和 cache-path 属性分别知名了缺省的页面和缓存路径。如果应用需要使用session， session-class 属性也需要设置。如果应用需要使用框架的验证/授权支持，那么还应该指定user-class 属性。

　　2.3.2  页面服务

　　PRADO 使用 GET 变量 page 来指明要请求的页面。比如下面的这个URL：

 /examples/phonebook.php?page=AddEntryPage

　　这段代码将会请求 AddEntryPage 页面。如果没有指定page 变量，那么就会调用应用配置中的缺省页面。

　　你也可以使用 TApplication::constructUrl() 方法来请求一个页面。

　　2.3.3  数据编码和解码

　　缺省情况  TApplication 会对所有的POST和GET数据进行HTML编码。 '', ", <, >, & 会被转化为&#039;,&quote;,&lt;,&gt;和&amp;。之所以要进行编码主要是为了让这些字符能被保存到数据库中，并且能正确显示回给用户。如果有必要的话，可以调用pradoDecodeData()函数来进行解码。也可以重载TApplication::beginRequest() 函数不进行编码。

 

[下一页]

 

2.4  定义新组件
　　有两种方法来定义新的组件类：继承和组合。

　　继承是面向对象的设计概念。派生类定义它的父类的一些内容，还可以提供一些其他的功能。在PRADO框架中，组件的属性和事件都是可以继承的。派生类也可以提供更多的属性和事件。所有的组件类都应该从TComponent 或者它的派生类继承。

　　所有父组件的属性和事件会被派生组件类继承。

　　组合是用于基于组件的框架的。在PRADO中，主要对控件使用。一个新的控件类可以被定义为几个其他几个控件的组合。新的类负责协调这些控件之间的通信，并代表它们和外界通信。比如可以定义一个LabeledTextBox 控件类（继承TControl ），它由TLabel 一个控件和一个TLabel
控件组成。新的类负责配置这两个组成控件的属性和方法。

　　一般的约定（并不强求），控件的ID和属性的首字母应该大写，比如HomePage, NavigateUrl,
LogoPict；事件以On开头，比如onClick 。ID和属性的名字命名和变量命名一样，必须是以字母开头的，仅包括字母数字和下划线的字符串。

　　要定义一个新的组件通常需要写一个组件类文件，一个规格文件和一个模板文件。有些时候后面两个文件可以不要的。

　　2.4.1  定义属性

　　组件的属性在组件类的规格文件中定义，规格文件的语法如下：

 <?xml version="1.0" encoding="UTF-8"?> <component>    ......    <property name="<property name>"              get="<getter method>"              set="<setter method>"              type="<property type>"              default="<default value>" />    ...... </component>

　　在这里，name 用来唯一标识属性；get 定义了一个类方法来读取属性，set 定义了一个类方法来写属性，type 定义了属性的类型(string, integer, float, boolean, array 和object)，default 标识了属性的缺省值。其中name 属性是必须的。getter方法的语法如下： 

 function getterMethodName() {    ....    return $value. }

　　如果一个属性是不可读的，那么不要设置get 属性。setter方法的语法如下：

 function setterMethodName($value) {    // set some variable with $value }

　　如果一个属性是不可写的，那么不要设置set 属性。如果这个属性的类型是string，那么也可以不指明。类型的属性用来自动转换配置在规格文件或者模板文件中的属性初始值。default
属性一般用来作为引用的目的，也是可选的。如果一个属性是可读的而且之前没有被设置，那么getter方法应该返回一个缺省值。

　　可以用下面的语法定义组件的组件属性：

 <?xml version="1.0" encoding="UTF-8"?> <component>    ......    <component type="component type" ID="component ID">        <property name="property name" value="property value"/>        ....        <event name="event name" handler="function name"/>        ....    </component>    ...... </component>

　　这里type 属性指明了组件类的名称，IDID 属性指明了属性名称。property 元素和event 元素指明了对应的初值。

　　当组件被创建的时候，它的组件类型属性会自动被实例化。

　　2.4.2  定义事件

　　组件事件在规格文件中定义，而其内在的实现机制在类文件中定义。在规格文件中定义事件的语法如下：

 <?xml version="1.0" encoding="UTF-8"?> <component>    ......    <event name="..." />    ...... </component>

　　事件的name应该是一个合法的变量名。

　　在类文件中，通常会实现这么一个对应的方法（假定事件的名称叫 onClick）：

 function onClick($param) {    $this->raiseEvent(''onClick'',$this,$param); }

　　当这个事件实际发生的时候，这个 onClick 方法应该确实被调用了（参考框架的TButton.php
文件）。raiseEvent 方法在TComponent 类中实现，它调用了所有对应onClick 的事件响应函数，并把参数$param 传递给它们。

　　2.4.3  编写模板文件

　　在这一节里，会讲一些关于如何编写模板文件。模板是用于控件的，当时也不是所有的控件都需要模板。比如TTextBox, TButton 这些控件因为没有内容，因此就不需要模板。模板文件一般用于页面或者基于组合定义的控件。

　　模板中的注释，比如 <!-- ... --> 被作为静态文本处理。

　　可以在组件标签之外通过属性标签<prop:...>来配置组件的属性。比如可以用以下的代码配置模板中TTextBox 控件的Text 属性。

 ... <com:TTextBox ID="profile">   <prop:Text>     ...   </prop:Text> </com:TTextBox> ...

　　在一对属性标签中间的内容作为对应的组件属性的值。如果一些属性的值需要很大的数据，这样就很方便。

　　在模板文件中可以使用3种特殊的标签：

<%include ... %> - 框架会在解析模板前在这个位置包含一个外部文件。比如，你可以用它在页面模板中包含一个公共头文件<%include header.tpl %> 。外部文件的路径应该是这个模板文件的相对路径。
<%= ... %> -会直接在这个位置上输出一个PHP表达式的值，比如<%= date(''Y-M-d'',time())
%>。注意，表达式后面不需要输入分号。这个表达式的上下文环境是这个模板对应的组件，可以使用$this 变量来在表达式中使用组件。表达式的值在组件的绘制状态时计算。
<% ... %> - 代表了一系列PHP的语句。如果它们当中有echo或者print，那么其结果会显示在标签对应的位置。注意，这里PHP语句需要使用分号隔开，和标准的PHP语法是一样的。同样，这里的上下文环境依然是拥有此模板文件的组件。（译者注：很多地方都提到了上下文环境，这个词在有些面向对象的书籍中是这么翻译的，而有时候也被翻译成其他文字。它所指的是当前代码中代表的$this是哪一个组件。因为一个组件中可能包含了其他组件，比如页面中就经常包含了很多组件，那么如果这个模板是这个页面类的，那么我们此时的上下文环境是这个页面。有些时候，比如我们给页面中的某一个组件进行数据绑定的时候，上下文环境就改变成了这个组件，这时候，$this代表了此组件，而不再是页面）。在模板文件中，除了在组件标签范围内，在其他以外的地方可以自由使用其他各种标签。

2.5  总结

　　这一节我们来总结一下如何基于PRADO来开发一个Web应用。

　　首先需要创建两个文件：应用的入口文件和应用的配置文件。这一部分请参考本手册前面的"Hellow,world!"这个例子。

　　对于一个完整的Web应用而言，你还需要创建一个或者多个页面。每一个页面都需要有一个页面类文件，另外可能还需要一个模板文件或者规格文件。在模板文件中，你可以把组件和其他静态文本根据最终需要显示给用户看的样子组织在一起。在规格文件中，可以定义页面的属性，事件和子控件，这些定义可以在模板文件和代码中使用。这两个中都可以设置组件的初始值和指定事件的响应函数。在页面类文件中编写事件响应函数和其他函数。

 

　　有些时候，为了重用代码，你可以定义新的组件。比如你可以定一个SideBar组件来显示用户能看到的菜单，这样在各个页面中就都可以直接使用这个SideBar 组件来显示菜单了。

　　PRADO引入了PHP5新的例外处理机制，能够显示堆栈中的错误信息。这样在调试的时候你可以精确的找到什么方法发生了什么错误。

　　发布 PRADO 应用则非常简单。框架建议使用相对路径，因此如果你是这么做的话，只需要把包含你的应用的代码拷贝到你想放置的目录中就可以了。

第三章 范例：the Hangman Game
　　这一章将会讲一下开发一个基于Web的Hangman Game（猜词游戏）。这里面会用到一些PRADO的组件。这个游戏说明了显示状态使PRADO页面具有很强的交互性。

　　这个游戏只包括了一个页面来实现以下的功能：当用户第一次访问的时候，允许用户选择三种不同难度来开始这个游戏，不同的难度对应着不同的可以猜错的次数。游戏开始后，页面的上半部分会显示要猜得单词，没有猜中的字母用下划线显示。页面的下半部分列出了26个字母，用户可以点击对应字母来选择要猜的字母。如果用户放弃游戏或者错误次数超过了难度限制，会显示失败信息；如果猜对了，会显示成功信息。任何时候用户都可以重新开始游戏。

 

　　范例中会使用的 PRADO 组件包括：

TRadioButton: 显示一个单选框。
TPanel: 显示 <div> 元素。
TLabel: 显示文本。
TButton: 显示一个提交按钮。
TLinkButton: 显示一个提交操作的超链接。
TForm: 显示 <form> 元素。
　　这些定义好的组件通过属性和事件已经封装好了很多功能。比如，可以设置TPanel 的Visible
属性来控制整个<div>元素是不是可见。可以给TButton 组件的onClick 事件指定一个响应函数，这样当用户点击按钮的时候就会自动调用响应函数。请参考PRADO API文档中关于这些组件更详细的信息。

　　游戏中的一些数据在游戏过程中需要一值保持着的。因为这里只用了一个页面，所以可以使用显示状态而不需要使用session来保存这些数据。下面这些数据需要保存在显示状态中：

Word:要猜得单词。
GuessWord: 正在猜的单词（没有猜中用下划线显示）。
Level:游戏的难度级别。
Misses: 猜错的次数。
　　他们都被定义在页面的属性中（当然也可以不这么做）。

　　我们需要创建6个文件。假定这个应用放在Web服务器的根目录下，这些文件是：

hangman.php : 应用的主入口；
WEB-INF/hangman.spec: 应用的配置文件；
WEB-INF/hangman/HomePage.php: 页面类文件；
WEB-INF/hangman/HomePage.spec: 页面规格文件；
WEB-INF/hangman/HomePage.tpl: 页面模板文件；
WEB-INF/data/hangman.txt: 包含要猜得单词的文本文件。
　　下面主要讲一下HomePage 类的三个文件，其他文件和"Hello，world!"例子是类似的。

　　3.1  HomePage.tpl

 

　　首先来说一些页面模板文件。这个过程也是PRADO应用开发的过程。首先在页面模板中组合PRADO组件，然后就可以测试一下这个页面的显示样子，最后编写页面类文件中需要的代码。这是一个典型的RAD（快速应用开发）的开发过程。

　　这个模板文件的位置是 examples/hangman/HomePage.tpl .

　　可以看到这个模板被分成4个组件startPanel, guessPanel, winPanel, 和losePanel ；他们将根据游戏的状态来决定是否可视。

　　在 startPanel中，使用了三个 TRadioButton 组件让用户可以选择游戏的难度。TButton 的onClick 事件指定了一个响应函数onSelectLevel ，当用户选择难度后点击了按钮就会被触发。如果用户没有选择难度，TLabel 组件会显示一个错误提示信息。

　　在 guessPanel中，三个表达式标签用于显示页面的 GuessWord, Misses,和 Level 属性。 同时还有一系列的TLinkButton 组件来显示字母A到Z，它们用于让用户点击选择猜哪一个字母。不管是猜对了还是猜错了，以后这个字母就不允许再被点击了。注意，所有的这些TLinkButton 组件都有同样的一个事件onClick 的响应函数onGuessWord 。

  winPanel 和 losePanel 会显示成功和错误的信息。如果用户点击了面板上的TLinkButton ，onClick 事件的响应函数onStartAgain 会被触发。

3.2  HomePage.spec

　　这个页面规格文件在  examples/hangman/HomePage.spec。它很简单，就是定义了4个页面的属性： Misses, Level, GuessWord 和 Word .

3.3  HomePage.php

　　这个页面类文件在 examples/hangman/HomePage.php .

　　页面类 HomePage 继承了框架提供的 TPage 类。

　　getter和setter函数用来定义页面属性。注意： getViewState() 和  setViewState() 函数被调用了，用来返回和保持属性的数据。这两个函数在TPage 的父类TComponent 中实现。它们是显示状态机制的主要代码。保存在显示状态中的数据在页面的postback中是一直保存着的。

　　接下来实现了4个事件响应函数： onSelectLevel(), onGuessWord(), onGiveUp() 和
onStartAgain()。它们对应着在页面模板中指定的onClick 事件响应函数。四个函数的具体内容就不再解释了，一看就明白。

　　现在你可以试试这个游戏，访问 URL:http://<Web-server-address>/examples/hangman.php。

 

[下一页]

第4章 高级主题 
4.1  显示状态的维护

　　组件的显示状态是指组件在一系列的postback中应该始终保存的数据。比如，用户在一个页面中更改了一个组件的字体颜色，他希望页面再一次提交显示的时候，依然看到的是已经修改过的颜色。在桌面GUI程序的开发中，这个非常简单。但是在Web编程中就不那么容易了，因为Web服务器并不会一直在内存中保持着页面状态。PRADO借鉴了ASP.NET的显示状态这个概念来解决这个问题。

　　如果要通过显示状态来保持一些数据，可以调用TComponent 类中的getViewState() 和  setViewState() 方法。可以在显示状态中保持很多类型的数据，但是不用把它用在资源句柄中，比如数据库联接。

PRADO

　　通过一个把限制状态保存在一个隐藏字段中来返回给用户。当用户提交页面并再一次显示页面的时候，显示状态中的数据会从被提交的隐藏域中读出来并用此恢复页面的状态。可以通过重载的方法来自己定制显示状态的存储方法。比如可以把显示状态保存在session中或者数据库中，避免通过隐藏字段要传输大量的数据。

4.2  Session

　　Session是用来在不同页面间保存状态的，这和页面的显示状态机制不同，显示状态只能保存本页面的状态。

　　如果要使用session, 那么首先在应用的配置文件中定义一个session类。session类必须实现ISession
接口。如果你不想自己写一个session类，那可以使用类System.Security.TSession ，它封装了$_SESSION 变量来实现了ISession 接口。你也可以自己写一个session类来使用不同的方法处理session（比如把session保存到数据库中）。

　　如果定义了session类，在请求的页面创建之前，对应的session对象就会被创建。TPage 页面类有一个Session 属性，可以方便的来访问session对象。

4.3  验证和授权

　　PRADO 提供了一个验证/授权的框架来支持验证页面的访问者，判断他们是否有权限来访问页面。

　　在验证框架中，一个用户类起到了主要作用。访问者如果通过了一定的身份验证（比如登录），并在服务器端获得了一个正确的身份，那么验证就通过了。用户对象代表了这么一个身份识别。除了身份检查外，一些页面也需要额外的权限检查来确保被验证的身份有足够的权限来访问。

　　验证框架支持基于角色的验证。一个页面如果在应用的配置页面中指名了需要验证（secured），框架将确保在访问页面前用户必须被验证。如果还指定的角色，那么框架还将确保用户是属于该角色的。最后，还可以定制页面的验证过程。如果验证或者授权失败了，onAuthenticationRequired 或onAuthorizationRequired 方法就会被触发，可以在此显示错误信息或者重定向到登录页面。

　　用户对象在不同的页面始终存在的，它使用了session。因此如果要使用验证框架则必须申明session类。由于用户对象保存在session中，因此你可以用它来保存一些需要在不同页面访问的数据。

 

　　如果要使用验证框架，需要在应用的配置文件中申明一个用户类。用户类必须实现了IUser接口。框架中已经提供了一个实现了该接口的类System.Security.TUser 。

　　phonebook 这个例子中说明了验证框架是如果使用的。

4.4  Form验证

　　PRADO提供了一种简单的方法来进行form的验证，而如果使用传统的PHP编程方式，这个过程是非常重复而且单调的。在PRADO中有一套验证组件。这些验证组件即允许在客户端也允许在服务器端对数据进行验证，下面我们将举一个例子来说明。

　　现在我们要创建一个用户注册页面。这个页面要求用户输入一个用户名和一个密码来创建新的帐号。密码要求是被输入两次以防止输入错误。另外用户名和密码都只能包含数字和数字，而且两者的长度分别要求不少于3位和6位。

　　要实现这个功能，可以创建这么一个模板：

 ...
<com:TForm>
...
Username:
<com:TTextBox ID="username" />
<com:TRequiredFieldValidator
      ControlToValidate="username"
      ErrorMessage="You must choose a username." />
<com:TRegularExpressionValidator
      ControlToValidate="username"
      RegularExpression="[\w]{3,}"
      ErrorMessage="Username must ...." />
<br/>
Password:
<com:TTextBox ID="password" TextMode="Password" />
<com:TRequiredFieldValidator
      ControlToValidate="password"
      ErrorMessage="You must choose a password." />
<com:TRegularExpressionValidator
      ControlToValidate="password"
      RegularExpression="[\w]{6,}"
      ErrorMessage="Password must ...." />
<br/>
Repeat Password:
<com:TTextBox ID="password2" TextMode="Password" />
<com:TRequiredFieldValidator
      ControlToValidate="password2"
ErrorMessage="Please re-type your password." />
<com:TCompareValidator
      ControlToValidate="password2"
      ControlToCompare="password"
      ErrorMessage="Your password entries did not match." />
<br/>
<com:TButton Text="Register" />
...
</com:TForm>
...

　　上面这个模板允许页面执行用户输入的客户端验证和服务器端验证（假定浏览器支持javascript）。不再需要额外的代码了。如果验证失败的话，form是不会被提交的，而同时会显示错误信息。

　　可以在模板文件中通过设置验证组件的EnableClientScript 属性来关掉客户端的验证。这时候，你可以在页面的OnLoad 事件中或者之后通过检查页面的IsValid 属性来判断验证是否通过。

4.5  缓存

　　PRADO框架提供了一个缓存机制来提高PRADO应用的运行效率。对于每一种组件类型，如果它之前曾经被实例化过，那么就会有一个对应的文件存在缓存目录中。这个文件包含了被序列化的的控件实例。以后一旦需要再创建同样的组件，那么就直接通过这个缓存文件来创建。这将会大大节省组件的创建时间，因为创建组件的过程需要解析好几个XML规格文件和模板文件。

　　如果要使用缓存，只需要在应用的配置文件中给的属性设置一个目录即可。这个目录必须是Web服务器可写的。使用的路径可以是绝对路径也可以是相对路径。

　　如果要关闭缓存，只需要给属性赋一个空字符串即可。

　　注意，如果你修改了组件的文件，那么应该包括所有的缓存文件都删掉或者移走。下一次组件创建的时候会自动重新创建的。因此在开发的时候，应该把缓存关掉。

4.6  定制 TApplication

　　TApplication 类是可以被扩充的。 TApplication 有好几个方法可以被重载。比如，你可以重载 beginRequest() 方法来实现对request数据的进行一些自己需要的预处理。如果想进一步了解这些内容，可以参考PRADO 的文档。

第5章 使用许可及用户支持
　　PRADO是一个完全免费的开源项目。它采用了如下的BSD使用许可。

Copyright (c) 2004, Qiang Xue (qiang.xue@gmail.com)
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
Neither the name of the developer nor the names of its contributors may be
used to endorse or promote products derived from this software without
specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ÄS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

　　如果你在使用过程中碰到问题，可以到xisc.com 的论坛上寻求帮助（有中文板块）。

 

　　我们也欢迎感兴趣的朋友一同参与PRADO的开发。