Thursday, July 16, 2009

The CFPOI Project: CFSPREADSHEET (and Eventually More!) for Any CFML Engine

When I first heard about the addition of CFSPREADSHEET to ColdFusion 9 and confirmed my suspicion that it was based on the Apache POI Project, I decided to do a little work to see what would be involved with creating a CFSPREADSHEET solution that would not only work on any CFML engine (Open BlueDragon, Railo, or Adobe CF 6.1, 7, and 8), but one that would also offer more flexibility in terms of the code syntax, and would expose parts of the POI functionality that aren't available in CF 9.

Like so many seemingly little experiments this turned into a project with a life of its own, namely the CFPOI Project that is available now on Google Code, and there is also a related group/mailing list for the project on Google Groups. I looked around at some of the other CFML-based wrappers people had come up with, but partially because they were dated or incomplete, and partially just because I wanted to tackle this on my own to dig into POI, I started from scratch.

What I wound up with is this:

  • A single Spreadsheet CFC that exposes a great deal of POI's spreadsheet functionality through simple object.methodName() syntax. I personally vastly prefer this syntax to the way things are done in CF 9 (e.g. mySpreadsheet.addRows(myQuery) vs. SpreadsheetAddRows(mySpreadsheet, myQuery)), and this also allows for more flexibility in the case of some features. For example, unless I'm misunderstanding how this works in CF 9, you can't switch the active worksheet on the fly while the workbook object is in memory. I allow for that when the spreadsheet CFC is used.

  • A set of UDFs that mirror the syntax of the SpreadsheetXXX() functions in CF 9, so you can use that syntax if you prefer.

  • A set of custom tags that mirror the syntax of the <cfspreadsheet> tag in CF 9. The only difference is the underscore in the tag (<cf_spreadsheet>) since it's a custom tag. Other than that, all the attributes and functionality are identical to CF 9.

This has been a really fun little task to work on (I'm a nerd like that), and only took up some of my spare time for about a week, so it was pretty darn easy to build.

Limitations at this point:

  • As usual, check the bug list! (It's empty now but I'll get to it.) There are a couple of things yet to be implemented.

  • Supports XLS format only at this point, but it will be dead simple and quick to add XSLX. I'll do that once the XLS stuff is 100% done.

  • Does not support format; as with XLSX, I'll look into adding that very soon.

  • If you're on shared hosting, don't have access to add JAR files to your CFML engine, can't use CreateObject("java"), etc. then I'm sorry but you're out of luck. (Might I suggest getting a VPS? ;-)

  • No build process or self-contained download yet, so you'll have to grab the code from SVN.


  • Apache POI 3.5 beta 6 or better.

  • OpenBD, Railo, or Adobe CF 6.1, 7, or 8. Dropping this into OpenBD or Railo is simple since neither engine (at least last I looked) includes POI. On Adobe CF you may run into conflicts with existing POI JAR files that are rolled into CF. (CF 8 for example has a very old version of POI included.) See here for an overview of how to load the newer Java classes into CF 8 on the fly.


  • Grab the Apache POI JAR files and drop them into your CFML engine's lib directory (or if you're on Adobe CF and this will cause conflicts, see the link above).

  • Grab the code from the CFPOI Project Google Code site and put this in the top level of the project on which you want to use this functionality. (Specifically CreateObject("component", "org.cfpoi.spreadsheet.Spreadsheet") needs to work!)

  • Start using it! Start with <cfset mySpreadsheet = CreateObject("component", "org.cfpoi.spreadsheet.Spreadsheet").init() /> and go from there.

What's next? Rounding out the spreadsheet functionality, and then moving on to presentation and word processing documents. I'm hoping CFPOI can grow to be a full-blown, easy-to-use solution that mirrors the core functionality of Apache POI itself, but makes it more accessible for CFML developers regardless of their choice of CFML engine.

If you want to get involved with the project, PLEASE contact me! Building this stuff out isn't terribly time consuming, but the more help I have with code, documentation, testing, etc. the faster things will get done, and I think this is something from which all CFML developers can benefit. Even if you don't need POI functionality, I think it will serve as a good project to learn from if you're needing to incorporate other Java projects in your CFML applications. (It's easier than you think.)

If you want to see the code in action and learn more, I'll be presenting this on the ColdFusion Meetup on August 6 at noon Eastern time. Hope to see you there.


Have you looked @ Ben Nadel's POI Utility? Maybe that could be ported to work on all cfml engines

Yep, looked at it, but as I said for a few reasons I wanted to start from scratch.

Inability to use createObject(java) would be a tough one to get around but with JavaLoader folks on shared hosting could still possibly use it right?

I honestly don't know about JavaLoader on shared hosting--unfortunately (or fortunately I guess) I've never been in a situation where I've needed Java objects on shared hosting accounts. I guess it would just depend on how they're disabling CreateObject("java") because of course that's the bulk of what's going on in the spreadsheet CFC.

No comments: