Standalone library for working with spreadsheets and CSV in CFML (Lucee and Adobe ColdFusion), supporting all of ColdFusion's native spreadsheet functionality and much more besides.
- Java 8 or higher
- Lucee 5.x or higher
- Adobe ColdFusion 2021 or higher
Note that this is not an extension or package, so does not need to be installed. To use it, simply copy the files/folders to a location where Spreadsheet.cfc can be called by your application code.
The following are the essential files/folders you will need depending on which CFML engine you are using:
helpers/
objects/
lib-osgi.jar
osgiLoader.cfc
Spreadsheet.cfc
helpers/
javaLoader/
lib/
objects/
Spreadsheet.cfc
The following example assumes the file containing the script is in the same directory as the folder containing the spreadsheet library files, i.e.:
- root/
- spreadsheetCFML/
- Spreadsheet.cfc
- etc.
- script.cfm
- spreadsheetCFML/
<cfscript>
spreadsheet = New spreadsheetCFML.Spreadsheet();
data = QueryNew( "First,Last", "VarChar, VarChar", [ [ "Susi", "Sorglos" ], [ "Frumpo", "McNugget" ] ] );
workbook = spreadsheet.new();
spreadsheet.addRows( workbook, data );
spreadsheet.write( workbook, "c:/temp/data.xls" );
</cfscript>
When instantiating the library, the init() method must be called. This will happen automatically if you use the New keyword:
spreadsheet = New spreadsheetCFML.Spreadsheet();
If using CreateObject() then you must call init() explicitly:
spreadsheet = CreateObject( "component", "spreadsheetCFML.Spreadsheet" ).init();
You may wish to place the spreadsheet library files in a central location with an application mapping, and instantiate the component using its dot path (e.g. New myLibrary.spreadsheetCFML.Spreadsheet();).
How to create mappings (StackOverflow).
The library supports all of Adobe ColdFusion's spreadsheet functionality with a similar syntax. It can be run alongside existing ColdFusion spreadsheet code you don't wish to modify.
From version 3, multiple calls can be chained together, simplifying your code into a more expressive syntax.
spreadsheet.newChainable( "xlsx" )
.addRows( data )
.formatRow( { bold: true }, 1 )
.write( filepath );
From version 2.14.0, Lucee loads the POI and other required java libraries using OSGi. This is not yet supported with Adobe ColdFusion which by default uses an included version of Mark Mandel's JavaLoader.
For more details and options see: Loading the POI java libraries
You can also download this library through CommandBox/Forgebox.
box install spreadsheet-cfml
It will download the files into a modules directory and can be used just the same as downloading the files manually.
If using ColdBox you can use either of the WireBox bindings like so:
spreadsheet = wirebox.getInstance( "Spreadsheet@spreadsheet-cfml" );
spreadsheet = wirebox.getInstance( "Spreadsheet CFML" );
The automated tests require TestBox 5.0 or later. You will need to create an application mapping for /testbox
The code was originally adapted from the work of TeamCfAdvance. Ben Nadel's POI Utility was also used as a basis for parts of the read functionality. Header/Footer image functionality is based on code by Axel Richter.
JavaLoader is by Mark Mandel.
Copyright (c) 2015-2025 Julian Halliwell
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.