使用Ajax评级组件

在本教程中，您将使用评级组件使用户能够对某一项评定级别。本教程提供了 RatingData 类的实现，它可以维护用户的评定级别、投票数以及项的平均评定级别。默认情况下，评级组件显示为一排五个星，但是您可以自定义该组件的外观和文本，如本教程中所述。

您在本教程中构建的应用程序模拟实际的应用程序，用户可以在该应用程序中对某一项进行评级。该应用程序的第一页显示可供用户浏览和评级的书籍。第二页显示该用户在第一页上所选书籍的详细信息。

 

目录

 

l      向项目中添加 RatingData 类

l      向会话 Bean 中添加属性

l      创建主页

l      使用评级组件

l      测试应用程序

l      执行更多操作：添加第二个要评级的项

l      执行更多操作：分离平均评定级别和用户评定级别

 

本教程中使用的文件

l      RatingData.java

l      fieldguide.png

l      corejsfbook.png

 

本教程将使用以下技术和资源

JavaServer Faces 组件/ Java EE 平台	1.2 with Java EE 5* 1.1 with J2EE 1.4
Travel 数据库	必需的
BluePrints AJAX 组件库	不是必需的

* 本教程发布时，只有 Sun Java System Application Server 支持 Java EE 5。

本教程与 Sun Java Application Server PE 9.0 Update Release 1 和 Tomcat 5.5.17 配合使用。如果正在使用其他服务器，有关已发现的问题和解决办法，请参见发行说明和常见问题解答。有关支持的服务器和 Java EE 平台的详细信息，请参见发行说明。

向项目中添加 RatingData 类

首先，将一个 RatingData 类的实现添加到项目中。该类包含用于修改评级组件中与文本相关的属性的逻辑。完成本教程后，您可以自定义 RatingData 类文件，以便在自己的应用程序中使用。

1.       将 RatingData.java 下载到您的文件系统。

2.       下载并导入 Ajax 组件（如果您尚未下载）。

3.       创建一个新的可视 Web 应用程序项目并将其命名为 RatingExample。

4.       在 Projects 窗口中，右键单击 RatingExample > Component Libraries 节点，然后从弹出菜单中选择 Add Component Library。选择 BluePrints AJAX Components 并单击 Add Component Library。

IDE 将该组件库复制到该项目中并将组件和支持 bean 添加到调色板中。

5.       从主菜单中，选择 File > Add Existing Item > Java Source。在 Add Existing Item 对话框中，导航到并选择 RatingData.java，然后单击 Add。

IDE 将 RatingData 类添加到 ratingexample 包。

6.       从主菜单中，选择 Build > Build Main Project 以编译 RatingData 类。

7.       关闭并重新打开 RatingExample 项目，以便设计时可以使用 RatingData。

如果不执行此步骤，则在本教程最后一部分将评级组件的属性绑定到 currentRatingData 时会出现错误。

8.       如果该项目尚不是主项目，则右键单击 Projects 窗口中的 RatingExample，然后选择 Set Main Project。

向会话 Bean 中添加属性

接下来，将四个属性添加到会话 bean。这些属性用于存储应用程序中每项的评级数据和其他数据。由于该应用程序包含多个要评级的项，因此使用 Map 对象保存数据。

1.       如有必要，请在 Visual Designer 中打开 Page1。

2.       在 Outline 窗口中，右键单击 SessionBean1 节点，然后选择 Add > Property。

3.       在 New Property Pattern 对话框的 Name 字段中，键入 ratingMap，在 Type 字段中键入 HashMap。将 Mode 设置为 Read Only 并单击 OK。

ratingMap 属性用于存储每项的评级数据。

4.       在 Outline 窗口中，双击 SessionBean1 节点以便在 Java Editor 中打开 SessionBean1.java。将光标放在编辑器中，按 Alt-Shift-F 可自动添加以下 import 语句并修复“找不到 HashMap”错误：

import java.util.HashMap;
   
   

5.       返回到 Visual Designer 中的 Page1，以使 Outline 窗口可见。添加名为 currentRatingData、类型为 RatingData的第二个会话 Bean 属性。使用默认模式 Read/Write，单击 OK。

该属性用于存储当前项的评级数据。该应用程序是一个有两个页面的应用程序，当前项是指第二页上显示的项。

6.       添加名为 itemMap、类型为 HashMap 的第三个 SessionBean 属性。将 Mode 设置为 Read Only，然后单击 OK。

itemMap 属性用于存储每项中与评级无关的数据，在本例中它存储图像 URL 和项描述。

7.       添加第四个 SessionBean 属性。该属性名为 currentItemData，并使其成为一个字符串数组 (String[])，使用默认模式 Read/Write。单击 OK。

该属性是一个用于存储当前项的图像 URL 和描述的字符串数组。

8.       打开 SessionBean1.java 并将以下以粗体显示的代码附加到 SessionBean1.init 方法中。

代码示例 1：SessionBean1 init

public void init() {         // Perform initializations inherited from our superclass         super.init();         // Perform application initialization that must complete         // *before* managed components are initialized         // TODO - add your own initialiation code here           ratingMap = new HashMap();         itemMap = new HashMap();         String[] itemIds = {"fieldGuide", "coreFaces"};         String[] hoverTexts = {"I hate it", "I dislike it", "It's OK",             "I like it", "I love it"};         for (int i = 0; i < itemIds.length; i++) {             RatingData ratingData = new RatingData(hoverTexts);             ratingMap.put(itemIds[i], ratingData);             if (i == 0) {                 currentRatingData = ratingData;             }         }         currentItemData = new String[]{"/resources/fieldguide.png",            "The definitive guide to NetBeans IDE."};         itemMap.put(itemIds[0], currentItemData);         itemMap.put(itemIds[1], new String[] {"/resources/corejsfbook.png",            "The one book you need to master this time-saving technology."});         }

 

此代码将填充 Session Bean 属性。它首先初始化 ratingMap 和 itemMap。然后通过 for 循环创建 RatingData 实例并将其放到 ratingMap 中，同时将第一个 RatingData 实例设置为当前评级数据。

请注意，RatingData 实例是使用悬停文本构造的，即，当用户将鼠标悬停在组件中的星形符号上时显示这些文本。for 循环之后，该代码创建了一个字符串数组以保存项数据（图像 URL 和描述），并将第一个字符串数组设置为当前项数据 (currentItemData)。

创建主页

接下来，将创建主页并添加评级组件和其他基本组件，如下图所示。通过该页面，用户可以为书籍评定级别，然后查看该级别，以及该书的平均评定级别。

1.       如果尚未下载 fieldguide.png，请将其下载到您的文件系统。

2.       单击 Page1 选项卡返回到 Visual Designer。

3.       从调色板的 Basic 部分，将一个 Label 组件拖动到页面上，键入 Browse Books，然后按 Enter。在 Properties 窗口中，将 Label 的 id 属性设置为 headerLabel，将 labelLevel 设置为 Strong(1)。

4.       将一个 Image Hyperlink 组件拖动到页面上。将 id 属性设置为 fieldGuideLink 并从 text 属性中删除 Image Hyperlink 字样。

5.       右键单击 Image Hyperlink 并从弹出菜单中选择 Set Image。导航到并选择 fieldguide.png，然后单击 OK。

NetBeans IDE Field Guide 的图像将出现在该页面上。该文件也被复制到项目的 web/resources 子目录中。

6.       从调色板的 BluePrints AJAX Components 部分，将一个 Rating 组件拖动到页面上。将该组件的 id 属性设置为 fieldGuideRating。

默认情况下，Rating 组件显示为一排五个星形的符号，如上面的图 1 所示。

7.       双击 fieldGuideLink Image Hyperlink 并用以下以粗体显示的代码替换 fieldGuideLink_action() 方法的主体。

请确保删除了 return null;，因为它将被替换为 return "Detail";

代码示例 2：fieldGuideLink_action 方法

public String fieldGuideLink_action() {         SessionBean1 sessionBean = getSessionBean1();         sessionBean.setCurrentItemData                 ((String[])sessionBean.getItemMap().get("fieldGuide"));         sessionBean.setCurrentRatingData                 ((RatingData)sessionBean.getRatingMap().get("fieldGuide"));         return "Detail";          }

此代码将 fieldGuide 设置为当前项。具体地说，就是此代码设置会话 Bean 的 currentItemData 和 currentRatingData 属性。当用户单击 Image Hyperlink 时，该方法返回结果 Detail，这会打开第二页并显示当前项的数据。稍后，本教程将介绍如何将 Detail 页添加到项目。

使用评级组件

评级组件的功能之一就是能够自定义组成该组件的控件和文本，如下面的步骤所述。

1.       单击 Design 按钮，在 Visual Designer 中重新打开 Page1。选择 Rating 组件，然后通过在 Properties 窗口的 Appearance 部分下设置以下属性来配置该组件。

Appearance Properties
includeClear	for True
includeModeToggle	for True
includeNotInterested	for True

  控件用于表示用户对某一项不感兴趣。

m         控件用于清除用户的评级。

m         控件是模式切换控件。评级组件可以在显示该项的用户评定级别和平均评定级别之间切换。

2.       在 Properties 窗口的 Data 部分下设置以下属性。在有些情况下，需要将组件属性绑定到 ratingMap 或 itemMap 中的条目。

您必须在 Properties 窗口中直接输入这些绑定表达式。由于 Property Bindings 对话框不显示 Map 对象中的条目，因此在该对话框中这些绑定是不可用的。

Data Properties
averageGrade	#{SessionBean1.ratingMap.fieldGuide.averageGrade}
averageModeHoverText	Show the average rating for this item
averageModeText	#{SessionBean1.ratingMap.fieldGuide.averageModeText}
clearHoverText	Clear my rating
grade	#{SessionBean1.ratingMap.fieldGuide.grade}
hoverTexts	#{SessionBean1.ratingMap.fieldGuide.hoverTexts}
inAverageMode	for True
normalModeHoverText	Show my rating for this item
normalModeText	#{SessionBean1.ratingMap.fieldGuide.normalModeText}
notInterestedHoverText	I'm not interested in this item

m         grade 属性就是用户为某项评定的级别（星数），而 averageGrade 属性是用户群体为该项评定的平均级别。

m         包含单词 Text 的属性用于设置当用户将鼠标悬停在组件的控件之上和之外时所看到的文本。请注意，用户（正常）模式和平均模式的文本属性不同。

m         inAverageMode 属性设置为 True 时将组件的初始显示设置为平均模式。

有关某个属性的详细信息，请将鼠标悬停在 Properties 窗口中该属性的名称上，IDE 将显示相应的工具提示。

测试应用程序

1.       运行该项目。该应用程序在 Web 浏览器中打开，评级组件显示平均评定级别，如 控件和下文所示：

Average rating:  0 (from 0 votes).
    
    

将鼠标放在该组件上，请注意随着控件的改变会显示出不同的文本。将鼠标从该组件移开时，则又返回到平均评定级别。

2.       将 Field Guide 评定为 4 星级。组件接受该级别并切换到用户（正常）模式，如 控件所示。

当鼠标从组件移开时，您将看到文本“Saved: I like it”，这表示您评定的级别已保存。

3.       如果您改变了注意，将 Field Guide 评定为 5 星级。则现在文本会变成“Saved: I love it”。

4.       将鼠标移动到 控件上，请注意它将变成 ，然后单击该控件。

将鼠标从该组件移开时，您将看到两次投票的平均评定级别为 4.5。

5.       通过单击清除和不感兴趣的控件继续了解组件。

此时，如果单击 Field Guide 图像，则什么也不会发生。稍后将在本教程中实现该链接的代码。

 

执行更多操作：添加第二个要评级的项

上述步骤中描述的项目很好地介绍了如何使用和自定义评级组件。实际的应用程序很可能包括多个要评级的项。在此，您需要将第二本书和评级组件添加到页面，

1.       如果尚未下载 corejsfbook.png，请将其下载到您的文件系统。

2.       将一个 Image Hyperlink 组件拖动到 Page1 上并将其放置在评级组件下面。将 id 属性设置为 coreFacesLink，并从 text 属性中删除 ImageHyperlink 字样。

3.       单击 imageURL 属性旁边的省略号按钮 (...)。在 corejsfbook.png - image URL 对话框中，导航到并选择 corejsfbook.png。单击 OK。

Core Faces 一书的图像应该出现在页面上。IDE 还会将该文件复制到项目的 web/resources 子目录中。

4.       复制 Field Guide 书的评级组件，并将副本粘贴到 Core JSF 图像的下面。将新评级组件的 id 属性设置为 coreFacesRating。

5.       在 Properties 窗口的 Data 部分中，编辑绑定属性的表达式，使属性包含 coreFaces 关键字，而不是 fieldGuide 关键字。

注意：如果属性的设置没有出现在 Properties 窗口中，请单击与该属性关联的省略号 (...) 按钮，然后在弹出窗口中单击 Cancel。相应的文本将出现在 Properties 窗口中。不要在该对话框中编辑该属性。

6.       双击 coreFacesLink Image Hyperlink 并用以下代码实现操作方法。

同样，请确保删除了 return null;，因为它将被替换为 return "Detail";

代码示例 3：coreFacesLink 方法

public String coreFacesLink_action() {         SessionBean1 sessionBean = getSessionBean1();         sessionBean.setCurrentItemData           ((String[])sessionBean.getItemMap().get("coreFaces"));         sessionBean.setCurrentRatingData           ((RatingData)sessionBean.getRatingMap().get("coreFaces"));         return "Detail";         }

7.       运行并测试该应用程序。

执行更多操作：分离平均评级和用户评级

评级组件可以在显示项的平均评定级别和用户评定级别之间切换。如果愿意，您还可以在组件的不同实例中显示平均评定级别和用户评定级别。在本部分中，将在项目中添加第二个页面。该页动态显示用户在第一页上所选项的信息（图像和描述）。它还在不同的实例中分别显示平均评定级别和用户评定级别。添加另一个页面的好处是可以跨页显示平均评定级别和用户评定级别。

1.       在 Projects 窗口中，右键单击 RatingExample > Web Pages，然后从弹出菜单中选择 New > Page。将新页命名为 Detail。

2.       将一个 Hyperlink 组件拖动到页面上，键入 Return to Browsing Books，然后按 Enter。在 Properties 窗口中，将 id 属性设置为 browseLink，将 url 属性设置为 /faces/Page1.jsp。

3.       将一个 Image 组件拖动到页面上。将 id 属性设置为 currentItemImage，将 url 属性设置为 #{SessionBean1.currentItemData[0]}。

4.       将一个 Static Text 组件拖动到页面上。将 id 属性设置为 currentItemText。将 text 属性设置为 #{SessionBean1.currentItemData[1]}。

5.       将一个 Rating 组件拖动到页面上。按如下方式设置属性：

Properties
General
id	averageRating
Data
averageGrade	#{SessionBean1.currentRatingData.averageGrade}
averageModeText	#{SessionBean1.currentRatingData.averageModeText}
inAverageMode	for True
Advanced
gradeReadOnly	for True

6.       将第二个 Rating 组件拖动到页面上。按如下方式设置属性：

Properties
General
id	myRating
Appearance
includeClear	for True
includeNotInterested	for True
Data
clearHoverText	Clear my rating
grade	#{SessionBean1.currentRatingData.grade}
hoverTexts	#{SessionBean1.currentRatingData.hoverTexts}
normalModeText	#{SessionBean1.currentRatingData.normalModeText}
notInterestedHoverText	I'm not interested in this item

7.       在 Visual Designer 中右键单击，然后从弹出菜单中选择 Page Navigation。

将在 IDE 中打开 Page Navigator 窗口。

8.       将一个连接器从 Page1.jsp 图标旁边的连接器端口拖动到 Detail.jsp 图标。将该连接器命名为 Detail，

9.       运行并测试应用程序。单击第一页上某本书的图像可打开显示该书详细信息的第二页。请注意，评级数据可以跨页显示。

注意：在 Detail 页对书籍进行评级时，必须刷新该页以更新平均评定级别。但是，返回到 Page1 时，将自动显示更新后的平均评定级别。这两个行为都模拟了实际的应用程序。在呈现页面时，您需要确保平均评定级别是准确的，但是没有必要在任何人对该项进行评级时都实时更新平均评定级别。

试试看。在本教程中，Detail 页面只显示在 Page1 上所选项的图像和描述。在实际的应用程序中，可能在 Detail 页上包含更多信息，如出版日期、ISBN 编号、出版商说明等。要实现这些功能，请首先将这些信息添加到字符串数组。然后，为每条新信息向 Detail 页上添加一个 Static Text 组件。最后，将 Detail 页上的新 Static Text 组件绑定到 currentItemData 字符串数组的新成员。

小结

以下是有关评级组件的要点：

l      默认情况下，评级组件显示为一排五个星形符号。您可以通过修改 maxGrade 属性的值来自定义星形符号的数量。

l      评级组件还具有用于包括清除和不感兴趣的控件的属性，以及用于自定义用户将鼠标悬停在这些控件上以及之外时出现的文本的属性。

l      该组件的模式切换控件允许您在组件的同一个实例中显示用户评定级别和平均评定级别。但是，如果愿意，还可以在两个独立的实例中显示用户评定级别和平均评定级别。该组件具有设置与每个模式关联的文本和悬停文本的属性。

l      可以跨页显示平均评定级别和用户评定级别。

l      由于应用程序通常包括多个要评级的项，因此最好创建一个映射来保存评级数据实例。

l      只有在用户更改评级时才发送 Ajax 请求。如果用户评定的级别与所保存的信息相同，则不发送 Ajax 请求。

l      可以在服务器上更新（并国际化）评级组件的正常模式文本和平均模式文本以响应 Ajax 请求。

 

当您将每个属性设置为 True 时， IDE 会为评级组件添加相应的控件.