itsadok / play-excel

A Play! framework plugin to help generate Excel file (using predefined Excel file as template)

Excel module

The Excel module allows you to render Excel document. It is rather simple to use as it only requires to import a static file.

The tool uses the jxls library.

In order to use the Excel module, you need to create an Excel based template – see http://jxls.sourceforge.net for details instruction.

What’s New in v1.2.3

• Fix bug: Plugin.beforeActionInvocation does not work with IE8
• Fix bug: NPE at Plugin.onActionInvocationResult (line 104) in rare case (http.request is null)
• Document updates

What’s New in v1.2.2

• @With(ExcelControllerHelper.class) no longer required for Controller rendering Excel/CSV reports

What’s New in v1.2.1

• Transparent async rendering
  • define "excel.async=true’ in application.conf file or do renderArgs.set(RenderExcel.RA_ASYNC, true) to enable asynchronous Excel generation

What’s New in v1.2

• Update with Play!Framework v1.2
• Transparent Excel Render
  • now not need to bother with renderExcel, instead use Controller.render(…) or Controller.renderTemplate(…) as usual. Excel plugin will handle Excel rendering if request.format is ‘xls’ or ‘xlsx’ automatically
• API changes
  • renderExcel() call removed
  • previously use “fileName” renderArg to denote filename of the Excel file generated, now please use RenderExcel.RA_FILENAME instead

Note,

• for version 1.2 and 1.2.1, you will need to add @With(ExcelControllerHelper.class) annotation to your controller class where you want to generate Excel report
• start from v1.2.2, @With(ExcelControllerHelper.class) is NO longer needed for report generating

What’s New in v1.0a

• support Play 1.1-RC1
• jxls update to 1.0-RC1 along with it’s dependencies
  • POI 3.6
  • Jexl 2.0

Enable the Excel module for the application

In the /conf/application.conf file, enable the Excel module by adding this line:

# The Excel module
module.Excel=${play.path}/modules/Excel
excel.template.root=app/views

note:

• (before v1.2)Please change the excel.template.root from app/views to some where else when you use excel module with Play version 1.02 or before. Otherwise your application will not be able to startup on product mode.-
• start from v1.2, excel.template.root is no longer needed. You put your excel templates directly into app/views folder, following the same convention as your html templates.

Using the Excel module

-The renderExcel() method- (only apply for versions before v1.2):

import static play.modules.excel.Excel.*;

And then use the renderExcel() method as you would use the render() method.

The renderExcel() behavior is almost the same as that of render() except the following differences:

1. the template should be an excel file with “.xls” suffix rather than a text file with “.html”
2. You can use renderArgs.put(“fileName”, “your-file.xls”) to indicate the name of the excel file to be generated

Set request.format New in v1.2

Set request.format to ‘xls’ or ‘xlsx’ to render user Excel template. The excel template should be put in the same dir as normal html template, the file suffix shall comply with request.format setting. An easy way to set request.format is via route configuration. Please refer to http://www.playframework.org/documentation/1.2.1/routes#content-types for detail.

For v1.2 and v1.2.1 please make sure you have @With(ExcelControllerHelper.class) annotation on your controller class if you want to generate Excel report. This is no longer needed for v1.2.2

Please refer to the sample for an example.