第三章 范例：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的开发。