Actuate JS库简要说明.doc

Birt JS库简要说明JS库是actuate 针对流行的WEB2.0开发的,它可以在任何WEB程序中集成Birt报表。类库提供了基本的远程通信，权限和报表展现功能。iPortaliportaljsapi上面为JS库的存放路径，如果要查看类库，可以到此目录查阅。另Actuate给出的API可到文件夹help下查看引入JS库；有两种方式：1、 通过在服务器中的实际路径访问。如：2、 通过Birt定义的Servlet访问:与Birt服务建立会话在Birt JS的使用中，最重要的两个基础类是：actuate和viewer；Actuate是构建报表最重要的一个类.负责远程连接的基本设置和Birt类库的加载。在Actuate类中，有两个方法在调用Birt服务时，都得用到：Load()：这个方法必须首先调用，用于加载程序中要用到的模块。initialize() ：加载资源和认证。示例：function init()actuate.load(viewer);actuate.initialize( http:/localhost:8900/iportal, null, null, null, runReport);说明：actuate.load(moduleName);加载指定的API模块的名称；此方法必须在initialize()方法前执行。而有效的模块名称有如下几个：Dataservice：数据服务组件；加载 actuate.dataService包和actuate.Dataservice 类；Viewer：视图服务组件，加载actuate.viewer 包和 actuate.Viewer 类；Parameter：参数服务组件，加载actuate.parameter 包和 actuate.Parameter类.initialize(iportalUrl, requestOptions, userId, password, callback, errorCallback) 初始化Actute类库,认证用户信息,然后提供了一个回调函数和一个错误处理函数.参数:String iportalUrl加载资源的服务地址;actuate.RequestOptions requestOptionsactuate.RequestOptions.实例，请求连接中存一些参数，如果为Null则采用默认配置。 String userIduserId, 为空则采用单点登陆（SSO）String passwordpassword, 为空则采用单点登陆（SSO）Function callback加载API完成后的回调函数，其传入参数如下：o iportalUrl: 同initialize的iportalUrlo userId: 同initialize的UserIDo iserverUrl: iserverUrl服务地址；o volume: 域Function errorCallback当出现错误时的回调操作， 其可能出现的异常包括： o actuate.ConnectionException: 资源加载失败, 无效的iportalUrl.o actuate.AuthenticationException: 认证失败o actuate.Exception: 其它一些异常。展现报表 actuate.Viewer 类主要负责加载和展现报表。要使用它，必须首先按如下方式加载该组件：actuate.load(viewer);在加载该组件后，可能调用.actuate.Viewer类提供的方法来配置报表的展现方式，然后调用submit （）方法将报表展现在指定的里面. 示例:Viewer Pagefunction init()actuate.load(viewer);actuate.initialize( http:/localhost:8900/iportal, null,null, null, runReport);function runReport() var viewer = new actuate.Viewer(viewerpane);viewer.setReportName(/Public/Examples.rptdesign);viewer.submit();在上面示例中,首先实例化了Viewer对象（Viewer是一个报表展现容器，此处必须指定一个DIV容器来装载欲展现的报表实例）。然后指定要展现的报表设计文件。最后提交请求，报表自动展现。使用报表参数在一般的Birt报表设计中，总会带有很多参数，在这里JS库提供了actuate.Parameter 类来处理参数和参数值。示例： actuate.load(parameter); actuate.initialize( http:/localhost:8900/iportal, null, null, null, createForm ); function createForm() myParameters = new actuate.Parameter( param1 ); myParameters.setReportName(/Public/customerlist.rptdesign); myParameters.submit(processParameters);function processParameters() 上面actuate.load(parameter)首先加载参数组件。new actuate.Parameter( param1 )指定与参数展现容器相关联的DIV容器。 myParameters.setReportName（）指定参数展现容器相关联的报表设计文件。myParameters.submit（callback）提交参数，在服务响应后执行回调函数。上面做到了报表参数的展现。下一步我们要做到报表展现（Viewer）与参数（Paramer）的关联， actuate.Viewer.setParameterValues 方法功能是添加参数集到Viewer组件，此方法中传入的参数是对象，但必须等同格式：Var param=parameterName：ParameterValue；parameterName：ParameterValue；不过，在这里，Acuate提供了 actuate.Parameter.downloadParameterValues() 方法来返回这种形式的参数对象。The following code example shows a custom web page that displays parameters and then shows the report in a viewer using those parameters:下面的示例展现了下面的示例展现了参数组件与报表组件的关联。Viewer With Parameters Pagefunction init()actuate.load(viewer);actuate.load(parameter);actuate.initialize( http:/localhost:8900/iportal, null,null, null, displayParams);function displayParams() param = new actuate.Parameter(parampane);param.setReportName(/Public/Examples.rptdesign);param.submit(function () this.run.style.visibility = visible;);function processParameters() param.downloadParameterValues(runReport);function runReport(paramvalues) var viewer = new actuate.Viewer(viewerpane);viewer.setReportName(/Public/Examples.rptdesign);viewer.setParameterValues(paramvalues);viewer.submit();定制用户界面如果上面的程序你都跑过了，你一定会看见一个这样的界面：这是Viewer众多界面元素中的一个：工具条面板。在Viewer中如果想要控制这样的一些界面元素，须借助类actuate.viewer.UIOptions。Viewer对象为整个报表展现的核心，它负责把报表报表数据展现在HTML文件中，同时提供了很多实用的方法来完成一些交互（如过滤，排序，隐藏列等）。而UIOptions完全是一些Viewer展现样式定制信息了。对actuate.viewer.UIOptions的调用设置，具体可参考下面的代码：Function customFace()var viewer = new actuate.Viewer(viewerpane);viewer.setReportName(/Public/Examples.rptdesign);viewer.enableIV();var uioptions = new actuate.viewer.UIOptions();uioptions.enableScrollControl(false);/关闭滚动控制.uioptions.enableScroll(false);uioptions.enableToolBar(true);/启动工具条uioptions.enableMainMenu(false);uioptions.enableParameterPage(true)/启用参数页面uioptions.enableAdvancedSort(true)/启用排序uioptions.enableHideShowItems(true)uioptions.enableExportReport(false)/关闭输出,(PDF输出,XSL输出)viewer.setUIOptions(uioptions);viewer.submit();上面的注释描述了对一些基本控制的配置，具体的可以参考Actuate给出的API。上面的代码中有一句:viewer.enableIV();此方法启用交互。在交互模式开启后，可以完成很多交互操作。针对表格形式的报表交互有： Filtering（过滤)， Sorting(排序)， Grouping (分组) Aggregation (聚合) Hide/show columns (隐藏/展现列)。 Formatting (格式化)数据服务组件依据官方给出的解释，数据服务组件主要用于从远程服务中下载报表文件中的部分数据，还能针对报表数据做一些简单的操作（如：排序、过滤），其主要用到的JS类有： actuate.data.Request ：与服务的连接。此处有一个重要的概念：书签（Bookmark）。这是有点类似于HTML元素的ID的概念（在最终的HTML展现中，也的确是通过ID来实现的），在报表输出元素中用于互相区别的一个标识。其需要在制作报表文件时指定。其构造函数如下：actuate.data.Request(bookmark, startRow, maxRows) actuate.DataService：报表数据服务，主要是从服务中获得数据（以ResultSet的形式）构造函数：actuate.DataService(iportalUrl) actuate.data.ResultSet 数据集的具体装载形式，通过DataService的downloadResultSet注入回调函数（callback）中：downloadResultSet(data, request, callback, errorCallback),上面是官方给出数据服务的概念.不过在我的调试中发现这一块有很多问题.上面三个对象的API里提供的方法都不存在.像downloadResultSet方法在Firefox中运行时报错:dataService.downloadResultSet is not a function*不过像pdf,xls等文件格式的报表下载。可以通过Viewer对象的downloadReport方法中完成事件监听在Viewer对象中还有一个非常好的功能，事件监听( 在交互模式下可用)；a