birt作为一款功能强大的开源报表工具,其版本的升级更新速度也非常快,从1.0到2.0,一直到最新的 2.2.1版本,无论从功能上还是性能上都得到了极大的提高和扩充。birt也提供了一个标准的j2ee实现组件,可以发布到支持j2ee应用的web server服务器上,可以对生成的报表进行预览等操作。在大家使用birt viewer的时候,可能会对它日益纷繁的参数设置如云里雾里,在网上论坛里也有很多人碰到这样哪样的问题,同时官方的文档也不细致不全。所以我就对这些 参数进行了一个简单系统的总结,希望能对大家的birt开发有所帮助。这些参数以2.2.1版本为准,请大家特别注意。
1. servlet模式说明
查看birt viewer自带的web.xml文件,可以看到有以下几个pattern:
frameset ----
采用ajax框架,可以显示工具条,导航条和toc面板,实现复杂的操作,如分页处理,导出数据,导出报表,打印等等。该模式下会自动生成report document文件(预览report design文件)到特定的目录(用户可以用参数指定,也可以定义在web.xml里)。采用ajax,速度较慢。
run ----
也采用ajax框架,但不实现frameset的复杂功能,不会生成临时的report document文件(预览report design文件),也不支持分页,这个主要是应用在birt designer里的preview tab里,可以支持cancel操作,其它不怎么常用。采用ajax,速度较慢。
preview --- 没有用到ajax框架,直接调用底层engine
api对报表进行render,把生成的报表内容直接输出到浏览器。这种模式和run模式调用的是相同的engine
api,唯一区别在于run采用ajax获取报表内容,而preview直接输出到浏览器。如果要支持分页,用户需要在url上定义__page和
__pagerange参数,这两个参数也会在后面详细说明。需要特别说明的是,在这几种预览模式中,preview的速度是最快的。
document ---
该模式主要是为了从report design文件生成report
document文件。用户可以在url上提定document文件生成存放的路径(存放在server端),如果未指定,会直接生成
rptdocument发送到客户端浏览器,用户可以下载到客户端。
output --- 该模式类似于frameset,会自动生成report
document文件(预览report design文件),区别在于output不采用ajax,而是将生成的报表内容直接输出到浏览器。
parameter
--- 该模式主要用于生成一个参数对话框,一般用户不常用,用户可以直接通过提供的jsp
tag--parameterpage去实现参数对话框,不需要直接调用。
download ---
用于导出报表数据为csv格式,当你使用frameset工具条里的导出数据功能时,会用到这个模式。
2. web.xml里的参数设置
web.xml文件里有许多参数,用户应该根据自已的需求出发对这些参数有一个深入的了解。下面我会对这些参数一一做以说明。
[birt_viewer_locale]
设置默认的locale信息,暂时没有太大意义。因为locale的信息,首先以url上定义的__locale为准,如果没有定义,会找到当前浏览器的locale信息,最后才会用到这里定义的信息。
[birt_viewer_working_folder]
设置birt
viewer的工作目录。用户可以把report design或是report
document文件存放在这个目录下,这样就可以在url上采用相对路径去预览这些报表文件了。默认是当前根目录。
当前支持三种形式:
相对路径 ---
这个相对当前的web应用的context root.
绝对路径
java系统变量 --- 可以在启动服务器时,定义jvm的系统变量,如java
�cdmyworkingfolder=d:/reports。这样就可以在web.xml中用${myworkingfolder}进行引用了。
[birt_viewer_document_folder]
设置生成的document文件的存放路径。默认是documents目录。路径设置同上。
[working_folder_access_only]
简单的报表访问限制控制实现,如果设为true,哪就只能预览存放在工作目录下的报表文件。默认值是false。
[birt_viewer_image_dir]
设置生成的临时图片的存放路径。默认是report/images目录。路径设置同工作目录设置。
[birt_viewer_log_dir]
设置生成的日志文件存放路径。默认是logs目录。路径设置同工作目录设置。
[birt_viewer_log_level]
设置日志的level,可选的值有:all|severe|warning|info|config|fine|finer|finest|off。级别由高到低。
[birt_viewer_scriptlib_dir]
设置用户script
lib文件的存放目录( 在报表中用到的java event handler class
)。默认值是scriptlib。路径设置同工作目录设置。
[birt_resource_path]
设置用户资源存放路径,这些资源包括library文件,image文件等。默认是当前根目录。路径设置同工作目录设置。
[birt_viewer_max_rows]
设置获取dataset的最大记录数。主要应用于设计报表的时候,预览报表如果记录数太多,会花费很多的时间,也可能会引起out
of
memory问题。默认是不限制。
[birt_viewer_max_cube_levels]
设置cube查询的最大级数。和前面的参数作用类似。默认是不限制。
[birt_viewer_cube_memory_size]
设置在生成cube时,可以写在memory中的最大值,单位是mb。可以提高效率,写在内存会比直接写在硬盘快很多。但同时也要注意内存占用的问题。
[birt_overwrite_document]
该参数主要用于frameset/output模式,它们会生成临时的document文件上。如果设为true,则每次刷新页面时,都会重新去生成document文件,如果为false,则不会重新生成,只会用原来的document文件去生成报表内容。
[birt_viewer_config_file]
定义properties文件的路径,不可以修改。
[birt_viewer_print_serverside]
在frameset工具条上,提供有后台服务器打印的功能,该参数可以设置是打开还是关闭后台打印的功能。默认是打开。可选值为:
on 和
off。
[html_enable_agentstyle_engine]
这个参数是会传递给engine的,主要用于一些css的兼容性方面的问题。默认值是true。
3. viewer.properties参数设置
viewer.properties文件主要是定义一些扩展的参数。
# configurable variable for jsp base
href. please uncomment the below line.
#base_url=
http://127.0.0.1:8080
该设置主要应用于代理服务器的情况下,在使用代理服务器后,从request里获取的uri并非真正的uri,需要在这里定义。
#
[extension
setting]
viewer.extension.html=html
viewer.extension.
pdf=pdf
viewer.extension.postscript=ps
viewer.extension.doc=doc
viewer.extension.xls=xls
viewer.extension.ppt=ppt
定义输出的报表文件的后缀名,和format相关联。
#
[output format label
name]
viewer.label.html=html
viewer.label.pdf=pdf
viewer.label.postscript=postscript
viewer.label.doc=word
viewer.label.xls=excel
viewer.label.ppt=powerpoint
定义导出报表对话框里的报表格式列表,和format相关联,这样名字会更有意义。
#
[csv
separator]
viewer.sep.0=,
viewer.sep.1=;
viewer.sep.2=:
viewer.sep.3=|
viewer.sep.4=\t
支持多种csv分隔符,用户也可以增加新的分隔符(只支持char,而不是string)。但同时需要修改jsp文件和messages.properties文件。
#
[loggers]
# "logger."+class=level
# if no level is specified or the text
"default",
# then the default level from the web.xml will be
used
logger.org.eclipse.datatools.connectivity.oda=default
logger.org.eclipse.datatools.enablement.oda=default
当前的日志都是通过engine输出的,如果需要其它组件的日志输出,可以在这里定义。注意格式必须为logger.org……。而且该组件必须实现了java的logger。
可以单独为该组件设置日志级别,如果设为default,就会使用web.xml里的设置。
4. url参数
下面是一些主要用到的url参数。
“__report”
定义要预览的rptdesign文件路径,支持相对路径和绝对路径,相对路径是相对于web.xml中定义的工作目录。
“__document”
定义要预览的rptdocument文件路径,同样支持相对和绝对路径。相对路径是相对于web.xml中定义的工作目录。在同时定义了__report
和__document参数时,以__document为优先,如未找到相应的document文件,才会从design文件生成document文件
(frameset/output)或是直接去render这个design文件(preview/run)。
“__title”
定义报表显示的标题。
“__showtitle”
是否显示frameset模式下上方的标题部分。true
| false
“__toolbar”
是否显示frameset模式下的工具条。true |
false
“__navigationbar”
是否显示frameset模式下的导航条。true |
false
“__parameterpage”
是否强制弹出或不弹出报表参数对话框。true |
false
“__format”
输出报表的格式,默认为html。现在支持:pdf | doc | xls | postscript |
ppt
“__locale”
设置locale信息,如 __locale=zh_cn,
注意必须是国家加语言。
“__svg”
设置chart输出是否以svg格式输出。true |
false
frameset和run模式下,会采用javascript判断客户端浏览器是否支持svg,但并非对所有浏览器有效。
“__bookmark”
设置页面要定位的书签名字。
“__istoc”
指定定位的书签是不是一个toc名字。如为true,就会根据__bookmark参数值去获取一个真正的书签名,从而实现正常的跳转。这个主要用于定位到一个toc上。
“__rtl”
指定html页面输出是否需要right
to left。支持不同国家的阅读习惯,如阿拉伯国家是从右到左的。
“__page”
指定要输出的报表页数,这个依赖于报表的分页设计(page
break)。
“__pagerange”
指定要输出的报表页数范围。如1,3,5-9。
“__resourcefolder”
定义资源目录路径。同web.xml中的birt_resource_path设置。
“__asattachment”
是否以附件方式下载报表,如生成pdf或是其它格式里。默认是inline。
“__masterpage”
是否要显示master
page。true | false
“__designer”
该参数主要是应用在birt
designer环境下,如会读取cache的报表参数等等,一般不用。true |
false
“__overwrite”
该参数同web.xml定义的参数,不过web.xml里是全局设置,在url上通过参数可以定义本次操作的设置。
“__imageid”
内部参数,用于image的引用,一般不用。
“__maxrows”
设置dataset查询的最大记录数,要注意这个设置是全局的,会影响后面所有的请求。主要用于birt
designer下,提高报表设计效率。同web.xml中的birt_viewer_max_rows设置。
“__maxlevels”
设置查询获取cube的最大级数。同上面的__maxrows,也主要用于birt
designer设计环境。
同web.xml中的birt_viewer_max_cube_levels设置。
“__cubememsize”
同web.xml中的birt_viewer_cube_memory_size参数设置。
“__instanceid”
如果查看birt输出的html代码,你就可以看到一些html
element会有一个iid的属性(如table),这个就是instanceid。这个是engine动态生成的,不可提前预知。所以你需要从
html代码中得到这个值。该参数主要是为了获取reportlet(报表片断,如只输出报表中的一个table或是一个chart)。需要配合
__isreportlet参数。
“__isreportlet”
指定当前输出是不是一个reportlet。true | false
特别说明:为了输出一个reportlet,birt现在提供两种方式。
1.
为要输出的对象(表格或是chart)定义一个bookmark,然后可以用下面的url输出reportlet.
http://localhost:8080/birt/frameset?__report=test.rptdesign&__bookmark=bk&__isreportlet=true
2.
采用instanceid,但这个值事先是无法预知的,需要预览一次后从html代码中得到。然后用下面的url输出reportlet.
http://localhost:8080/birt/output?__report=test.rptdesign&__instanceid=iid&__isreportlet=true
还有就是要注意,reportlet只支持document文档。如果是预览design文档去输出reportlet,就必须要使用frameset/output(自动生成document文档)。
“__clean”
birt里临时生成的一些文件都是和session相关的,比如临时document文件,还有image文件。这些文件也可以通过session进行管理,这个参数就是指定是否需要在session
timeout的时候清除这些临时文件。默认值是true。
true |
false
“__dpi”
可以设置输出chart的dpi数值。
“__fittopage”
暂时这个参数只对pdf和postscript格式报表有效,指定是否调整至适合页面。
“__pagebreakonly”
暂时这个参数只对pdf和postscript格式报表有效,指定是否只采用birt报表内定的分页设置。这个参数一般需要和__fittopage联合使用。
“__agentstyle”
同web.xml中的html_enable_agentstyle_engine参数设置。
==========================
后台server端打印相关参数
==========================
“__action”
定义执行的指令名称。当前只支持print指令,用于后台服务器打印。
“__printer”
后台打印机名称。
“__printer_copies”
对应打印机的打印份数参数。
“__printer_collate”
对应打印机的双面打印参数。
“__printer_duplex”
对应打印机的duplex参数。
“__printer_mode”
对应打印机的模式参数。是单色还是彩色。
“__printer_pagesize”
对应打印机的纸型参数。比如a4。
===============================================================================
==========================
jsp tag相关参数
===================================
“__id”
viewer的id号,这个参数一般不常用,主要用于jsp
tag中,如在一个页面插入两个birt
viewer,而且预览同一个报表文件,这时候因为在一个session下面,所以需要用不同的id去生成单独的document文件。不至于都生成同一
个document文件上,从而引发冲突。
“__pattern”
在jsp tag中用于指定要提交的servlet
pattern名字,如frameset/output/run/preview等。主要用于采用parameter模式生成parameter
dialog对话框时。
“__target”
可以指定提交到的窗口名称。如_blank,_self等。
“__nocache”
指定是否会用到cache的报表参数值,这些cache的值一般保存在rptconfig文件里。在设计报表并预览的时候,可以保存输入的报表参数值。这个在runtime的时候不常用。
===============================================================================
==========================
报表参数相关
===================================
“__isnull”
指定当前的报表参数为null值,后面是报表的参数名。
“__islocale”
指定当前的报表参数值是和locale/format相关的,必须用特定的locale/format转化参数值(从string转化为object)。格式为__islocale=paramname。
“__isdisplay__”
指定报表参数的displaytext值,格式为__isdisplay__paramname=displaytext。可以在报表中引用displaytext值,如params[“p1”].displaytext。
在url上传displaytext时如下(报表参数名为p1):
&__isdisplay__p1=hello
“__islocale__”
指定该报表参数值是locale/format相关的,同时给定了参数值。格式为__islocale__paramname=paramvalue。
===============================================================================
==========================
export data参数
===================================
“__exportencoding”
该参数应用于导出数据为csv中,可以指定导出的文件编码,如gbk或是gb2312等。
“__sep”
该参数应用于导出数据为csv中,可以指定数据分隔符,如逗号,冒号等。
“__exportdatatype”
该参数应用于导出数据为csv中,可以指定是否输出数据类型。true
|
false
“resultsetname”
要导出数据的记录集名字。
“selectedcolumnnumber”
要导出的栏位数。
“selectedcolumn”
要导出的数据栏位名称。
具体可以查看birtsimpleexportdatadialog.js文件。
===============================================================================
5.
其它参数设置
在birt viewer里还有一个比较特殊的参数应用,就是用户可以自定义自已的servlet,然后传递对象到application
context中,在报表中就可以从全局的application
context去获取到这个对象。
这里相关的有两个内定的参数,appcontextkey和appcontextvalue。下面是一个简单的示例。
public
void service( httpservletrequest request,
httpservletresponse response )
throws servletexception,
ioexception, birtexception
{
string
mykeyname = "mykey";
list values = new arraylist();
values.add(
"hello" );
values.add( new date() );
request.setattribute(
"appcontextkey", mykeyname );
request.setattribute( "appcontextvalue",
values );
requestdispatcher rd = request.getrequestdispatcher( "/frameset"
);
rd.include( request, response );
}