Jun 18, 2011

Play-Excel v1.2.1 released with support to asynchronous Excel rendering

I am very glad to release play-excel-1.2.1 which support asynchronous report rendering. Here are changes compare to v1.1:

Render method call
v1.1: play.modules.excel.Excel.renderExcel(...)
v1.2: play.mvc.Controller.render(...), play.mvc.Controller.renderTemplate(...)

in other words, now you don't even aware that you are rendering a Excel report or normal HTML report. Everything is determined by request.format. Once your request.format set to 'xls' or 'xlsx', Excel module will take over the rendering process automatically. There are 2 ways to set request.format:
1. explicitly set request.format in controller methods
a. Set request.format in Action methods
b. Set request format in @Before methods based on http params for example
2. set request.format in route config file. Refer to http://www.playframework.org/documentation/1.2.1/routes#content-types for detail

Template location
v1.1 Excel template can not be put inside views folder, instead you will need to put the templates outside of views folder and set the template root in application.conf file, e.g. excel.template.root=app/excel_tmpl
v1.2 Just put Excel template in views folder along with your normal groovy template files. And of course "excel.template.root" shall not be used anymore

File name
v1.1 set download file name by set "fileName" in renderArgs
v1.2 use play.modules.excel.RenderExcel.RA_FILENAME instead of "fileName".

Async rendering (v1.2.1 only)
v1.1 does not support asynchronous rendering
v1.2.1 support transparent asynchronous rendering. You don't have to deal with Future, Promise, await, request.new etc and you get the power for nearly free (Yes, this is really cool! and thanks to the excellent play framework again!). The only place you need to touch is
1. add "excel.async=true" in application.conf, which enable async rendering globally
2. do renderArgs.set(play.modules.excel.RenderExcel.RA_ASYNC, true) in your action controller to enable async rendering for this controller action only

For those who don't yet see the power of async rendering, please refer to http://www.playframework.org/documentation/1.2.1/asynchronous, or think about the fact that a large Excel table rendering might take as long as 500ms and blocking request handling thread for half second is NOT acceptable in a high performance web server like play which use only limited thread (N+1) to handle web requests.

- Green