5 使用样例

5.1 设置样例

1. 把文件解压到一个新目录中。
2. 在执行报表时要使用 bmp 和 png 图像。把 bmp 和 png 文件复制到 webcontentsamplesimages 目录中。
3. gif 文件用于在 Report Studio 工具箱中创建图标。把 gif 文件复制到 webcontectpatimages 目录中。
4. 把 toolbox.xml 的内容插入 ../c8/webcontent/pat/res 目录中的 Toolbox.xml 文件中。应该插入在 Toolbox_PageView 部分中以下代码后面：

   <listView id="Toolbox_PageView" classPrefix="clsListItem_tb"> <listItems>

5. 把 toolboxControls.xml 的内容插入 ../c8/webcontent/pat/res 目录中的 toolboxControls 文件中。应该添加在以下代码后面：

   <resources>

   <xmlFragment id="ToolboxControls">

6. 把 reportstudio_en.xml 合并到 webcontent/pat/res 中同名的文件中，放在 RSB UI 部分中以下代码后面：

   <section name="RSB" type="UI">

7. 把 customPromptControls.js 文件复制到 webcontentprompting 。

定制控件的代码在 customPromptControls.js 文件中。 toolboxControls.xml 中的 HTML/JavaScript 是在 Report Studio 中显示提示控件所需的基本代码。

对 customPromptControls.js 中的 JavaScript 代码使用外部引用，这样就可以更新代码并把修改传播到所有报表。尽管可以在 ToolboxControls.xml 文件中定义 JavaScript 代码，但是这么做就会导致在每个报表规范中嵌入静态的 JavaScript 代码。如果要更新报表中嵌入的代码，报表创建者就必须分别修改每个报表。

5.2 定制的提示按钮

定制的提示按钮实际上与默认的提示按钮一样，只是用图像替代了文本。下面解释使用这些新对象的步骤。

创建新的列表报表：

• Sales (query)ProductProduct line

选择 Product line 并按 Build Prompt Page 工具栏按钮。

创建一个提示页面，其中包含默认的提示按钮：

图 15. 创建一个提示页面

图 16. 包含默认的提示按钮

选择并删除每个提示按钮。

把 Prompt Button Set 拖到页脚中。

运行报表：

图 17. 把 Prompt Button Set 拖到页脚中

图 18. 运行报表

出现了一组更漂亮的提示按钮。

Prompt Button Set 实际上是一个标准的报表 Block 对象，其中有四个提示按钮。每个提示按钮的 <contents> 是用表格、图像和一些文本定制的。下面是标准 Cancel 按钮的规范：

 <promptButton type="cancel"> 
	 <contents/> 
	 <style> 
	 <defaultStyles> 
	 <defaultStyle refStyle="bp"/> </defaultStyles> 
	 </style> 
	 </promptButton>

下面是定制的 Cancel 按钮：

	 <promptButton type="cancel"> 
	 <contents> 
	 <table> 
		 <style> 
		 <defaultStyles> 
		 <defaultStyle refStyle="tb"/> 
		 </defaultStyles> 
		 <CSS value="border-collapse: collapse;width: 100%"/> </style> 
		 <tab leRows> 
		 <tab leRow> 
		 <tableCe lls> 
			 <tableCe ll> 
			 <contents> 
				 <image> 
				 <dataSource> 
 <staticValue>. . /samples/images/cancel.bmp 
	 </staticValue> 
				 </dataSource> </image> 
			 </contents> 
			 </tableCell> 
			 <tableCe ll> 
			 <contents> 
				 <textItem> 
				 <dataSource> 
				 <staticValue>Cancel< /staticValue> </dataSource> 
				 </textItem> 
			 </contents> 
			 </tableCell> 
		 </tableCells> 
		 </tableRow> 
		 </tableRows> 
	 </table> 
	 </contents> 
	 <style> 
	 <defaultStyles> 
	 <defaultStyle refStyle="bp"/> </defaultStyles> 
	 </style> 
	 </promptButton>

每个按钮的定义都属于标准的 XML 报表规范，而不是定制的 HTML 或 JavaScript 。每个按钮的内容是用一个包含两个单元格的单行表格定义的。一个单元格包含图像，例如在启用和禁用时按钮应该怎么样，所以不需要通过定制编程实现按钮操作。在运行时，提示按钮仅仅是报表的一部分，使用标准的 IBM Cognos 8 功能执行它们。

5.3 Beer Glass

Beer Glass 控件是一个定制的 HTML/JavaScript 控件，用户可以使用它调整啤酒杯中的液面高度，从而选择参数值。下面解释使用这个定制的提示控件创建报表的过程。

打开 Report Studio 和 GO Sales (query) 模型。

按 Quantity 升序排序。

向下滚动页面，可以看到 Quantity 值从 1 开始增加到更高的值。

创建筛选 [Quantity] >= ?pQty? 。

注意，参数名是 pQty 。

在报表中添加一个提示页面。

把 Beer Glass Prompt 拖到新的提示页面中。

会在报表中看到下面的 HTML 对象：

图 19. 在报表中添加一个提示页面

请记住，这个定制的提示控件是用 HTML/JavaScript 编写的，在运行报表时浏览器执行这些代码。

双击 HTML 对象，可以看到 HTML 源代码。

这个提示控件的代码实际上不在 Beer Glass Prompt 工具箱对象中。它通过调用 customPromptsControls.js 文件中的函数来创建提示。

查看代表这个定制提示控件的 HTML 对象的 HTML 定义。提示控件定义中的元素如下：

Beer Glass Prompt 使用的默认参数是 [BeerGlassParameter1] 。因为筛选中使用的参数是 pQty ，应该把它改为“ pQty ”。

图 20. Beer Glass Prompt

注意，参数名是区分大小写的，必须放在双引号中； pQTY 是无效的。

运行报表：

图 21. 运行报表

把鼠标移动到 Drink 或 Fill 按钮上，把值改为 85 。按 Finish 按钮，会看到 Quantity 值被筛选，在报表输出中只显示大于 85 的值。

图 22. 在报表输出中只显示大于 85 的值

报表现在完成了。报表创建者可以使用定制的提示调整报表，满足企业和客户的需要。

Beer Glass Prompt 的 JavaScript 代码实现清空和装满杯子这样有趣的效果。从提示的角度来看，最有意思的是它修改表单字段变量 p_pQty 的值。在 JavaScript 代码中，前面的一行代码获取提供的变量名并在它前面加上 p_ ：

 var sFullParameterName = 'p_'+ sParameterName;

在用 Drink 和 Fill 按钮修改提示值时，设置表单字段变量 p_pQty 的值。在用 Finish 按钮提交提示页面时，把这个表单变量传递给报表。

应用 drink 和 fill 函数修改与提示控件相关联的数字值， JavaScript 代码的其他部分定义啤酒杯图像的外观。

5.4 Dynamic Picklist Prompt

这个定制的提示控件看起来像一般的选择列表，但是有一个较大的差异 —— 只有当用户单击控件本身时，才会填充它。不需要在显示提示页面之前执行提示查询和相关的处理，所以可以非常快地显示提示页面。这非常适合那些不常用的提示。

按 Product number 升序排序：

图 23. 按 Product number 升序排序

用 Product number 创建一个新的筛选： [Product number] >= ? ProdNum?

注意，参数名是 ProdNum 。

添加提示页面。

把 Dynamic Picklist Prompt 拖到提示页面中。

报表中出现用于定义定制 Dynamic Picklist 控件的 HTML 对象：

图 24. 添加提示页面

请记住，这个定制的提示控件是用 HTML/JavaScript 编写的，在运行报表时由客户机 web 浏览器处理这些代码。

这里的代码实际上不是提示。它通过调用 customPromptsControls.js 文件中的函数来创建提示。

把参数名改为 "ProdNum" 。

把标签改为 "Product name" 。

为了设置 UseValue 和 DisplayValue ，必须确定 Product number 和 Product name 数据项的模型路径。

在 Report Studio 数据树（左面板中的模型树）中，找到 Product 查询主题：

图 25. 找到 Product 查询主题

右键单击 Product number 并选择 Properties 。

把 Ref 值复制到 Windows 剪贴板。

图 26. 把 Ref 值复制到 Windows 剪贴板

关闭属性表。

双击 HTML 对象，把“ [UseValue] ”替换为 Ref 值：

	"[Sales (query)] .[ Product] .[ Product number]"

重复这个过程，查明 Product name 的模型路径，使用这个路径作为 Display 值：

图 27. 查明 Product name 的模型路径

显示提示，其中显示 Label 值：

图 28. 显示 Label 值

目前，还没有填充提示内容。也没有执行提示查询。

单击向下箭头。提示得到填充，列表展开，报表用户可以选择提示控件的值。可能必须向下滚动，才能找到提示按钮。

5.4.1 Dynamic Picklist Prompt 的工作方式

这是本文中最复杂的示例。动态地获取提示值的代码非常巧妙。

在单击它时， Dynamic Picklist Prompt 控件的 JavaScript 代码执行以下步骤：

1. 获取 Use 和 Display 数据项的路径。
2. 通过 Use 和 Display 项创建简单的 XML 报表规范，其中含有提示页面、提示和查询。
3. 运行报表规范，将提示页面的值作为 HTML 片段返回。

   —— 换句话说，一个 JavaScript 变量现在包含提示页面的 HTML 。

4. 通过识别 <selectOptions> 和 </selectOptions> 标记之间的数据找到 HTML 中的提示控件。
5. 删除多余的字符，把 HTML 元素转换为定制提示控件的值。
6. 把这些值插入下拉列表。

然后，浏览器显示提示，用户选择一个值，设置 p_ProdNum 表单字段变量。

5.5 Tab Control Prompt

报表创建者可以使用 Tab Control Prompt 创建选项卡式提示界面。如果有不常用的提示，可以使用这个控件从主提示界面中去移除它们。选项卡式界面把提示隐藏起来，但是将其保持在报表用户可以轻易接触到的范围之内。对于第二个及后面的选项卡，直到用户选择选项卡时才会处理其中的提示。由于推迟了提示查询的执行，生成提示页面所需的资源减少了，所以性能也提高了。

Tab Control 使用一个由选项卡选择操作驱动的条件块。下面将创建一个报表来阐明选项卡式提示界面。

如下所示：

图 29. 创建新的列表报表

创建两个筛选：

图 30. 创建两个筛选

注意 Order method 筛选是可选的。

创建提示页面。

把 Tab Control Prompt 拖到提示页面中。

编辑 HTML ：

把选项卡名称设置为 Product line 和 Order method ：

'<script src=". ./prompting/customPromptControls.js">
</script>' + '<div id="[ tabContainer1] "></div>' + 

"<script>tabControl ( '[ tabContainer1] ','[ tabParameter1] ',['Product line','Order method'],'" + (IF (ParamCount('[ tabParameter1] ') = 0) 
THEN ('0') ELSE (ParamDisplayValue ('[ tabParameter1] '))) + 
"') ;</script>"

一定不要删除包围选项卡名称的 [ ] ，因为这些字符表示 JavaScript 数组。

选项卡现在创建好了。当用户单击一个选项卡时，设置 [tabParameter1] 参数的值。

下一步是使用选项卡参数创建一个变量，把条件块与这个参数关联起来。

在 Report Studio 中打开 Condition Explorer ：

图 31. 打开 Condition Explorer

使用以下表达式创建一个新的 String 变量 SelectedTab ：

	 ParamValue('[ tabParameter1] ')

这会将这个变量与选项卡式提示控件用来切换选项卡的参数关联起来。当用户单击一个选项卡时，会设置选项卡参数值，然后更新变量，改变条件块以反映新的选项卡参数值。

在 Values 列表中添加值 1 ：

图 32.在 Values 列表中添加值 1

这实际上定义两个变量值： 1 和 Other 。通过在变量的 Values 列表中添加选项卡编号，就可以定义更多选项卡。

进入提示页面。

选择条件块并把 Block Variable 属性设置为 SelectedTab 。

把 Current Block 属性设置为 Other 。

把 Value 提示拖到 Conditional Block 中。

在向导启动时，把参数设置为使用现有的 ProdLine 参数。

单击 Next 。

单击 Finish （接受默认的查询设置）。

把 Current Block 属性设置为 1 。

在向导启动时，把参数设置为 OrderMethod 。

运行报表：

图 33. 运行报表

用户可以通过单击“ Product line ”或“ Order method ”切换选项卡。

除非用户切换选项卡，否则不处理 Order method 提示（包括运行提示查?
询）。这可以同时节省资源并提高性能。

定制工具箱对象中添加的 Tab Header Control Prompt 对象采用相同的工作方式，但是报表创建者必须从头创建条件块，而不能使用 Tab Control Prompt 工具箱对象已经定义好的条件块。