Quick Tip on Uploading a CSV file in ColdBox

So you know how to upload files using uploadify, jQuery, AJAX. But how do we do that in ColdBox? Well it’s actually not that hard. ColdBox has a file utility plugin that handles interacting with files. Let’s demonstrate by showing how to upload a csv file.

Here’s a broad overview of the steps:

  • Download the FileUtils plugin
  • Add a mime type definition in ConfigurationCFC
  • Create the view
  • Create the handler
  • Add the route
  • Test the upload


  • ColdBox 3.8
  • ColdFusion 10
  • BootStrap 3
  • Windows OS

Download FileUtils Plugin

In preparation for the file upload, we will first need to download the FileUtils plugins from ForgeBox. Once downloaded, unzip and place the filebrowser folder in the modules folder. Here’s what we should have now:


Add Mime Type Definition to ConfigurationCFC

Let’s place the csv mime type definition in the ConfigurationCFC (i.e. configs/ColdBox.cfc):

/* ColdBox.cfc */
// custom settings
settings = {
   validMimeTypes =  {
      'text/plain': {extension: 'csv'}

Please note this mime type will also pick up any other plain text files. So you will need to use other checks to ensure the uploaded file is a csv.

Create the View

We are going to create a simple view to upload the csv file. I will assume the layout is created. If not, check out this article on ColdBox Layouts. Then in the views folder, create the reports folder and the new file index.cfm, and then add the following code:

<!--- views/reports/index.cfm --->
<div class="panel panel-primary">
  <div class="panel-heading"><h3 class="panel-title"><span class="glyphicon glyphicon-bell" aria-hidden="true"></span> Upload Reports</h3></div>
  <div class="row">
    <div class="col-md-12">#getPlugin("MessageBox").renderit()#</div>
  <div class="panel-body table-responsive">
    <form name="reportForm" method="post" action="#event.buildLink('reports.upload')#" enctype="multipart/form-data">
      <div class="form-group">
        <div class="col-md-3">
          <label for="csvFile">Select csv file to upload</label>
          <input type="file" id="csvFile" name="csvFile" class="fillable" accept="text/csv">
      <div class="form-group">
        <div class="col-md-3">
          <button type="button" class="btn btn-default" onClick="location.href='#event.buildLink('main.index')#'">Cancel</button>
          <button type="submit" class="btn btn-primary">Upload</button>
  </div> <!--- panel-body --->
</div> <!--- panel --->

Important notes:

  • Must add the enctype attribute to the form element, i.e. enctype=”multipart/form-data”
  • Set the form’s action to reports.upload and ensure you create the upload action method in the Reports handler, i.e. public void function upload() in handlers/Reports.cfc

Create the Handler

In the handlers folder, create a new ColdFusion component and name it Reports.cfc. Edit this file and add the following skeleton code to start with:

component accessors="true" {
  /* handlers/Reports.cfc */
  property name="sessionStorage"    inject="coldbox:plugin:SessionStorage";
  function preHandler(event,action){


  public void function index(){

} //component

In the index function above we’re loading the upload form on line 9 by explicitly setting the view to use as index.cfm in the views/reports folder.

In the same file after the index function, create a new function upload and add the following code:

public void function upload(event){
  var rc = event.getCollection();
  var uploadResult = "";
  var actualMimeType = "";

  if( !isNull(rc.csvFile) ){
    actualMimeType = FileGetMimeType(rc.csvFile, true);
    if (StructKeyExists(getSetting('validMimeTypes'), actualMimeType)) {
      uploadResult = getPlugin("FileUtils").uploadFile(fileField="csvFile",destination=expandPath('includes\files'),nameConflict="Overwrite");

      if (!StructIsEmpty(uploadResult) && uploadResult.clientFileExt is 'csv'){
        getPlugin("messagebox").setMessage("info","File #uploadResult.clientFile# was successfully uploaded.");
      else {
        getPlugin("FileUtils").removeFile( expandPath('includes\files\' & uploadResult.serverFile) );
        getPlugin("messagebox").setMessage("error","Invalid file type. Only CSV files are allowed.");
    else {
      getPlugin("messagebox").setMessage("error","Invalid file type. Only CSV files are allowed.");
  else {
    getPlugin("messagebox").setMessage("error","No File was selected for uploading.");
} //save

Important notes:

  • On line 8 we use FileGetMimeType to determine the actual mime type of the uploaded file.
  • On line 9, we check it agains the defined mime type in ConfigurationCFC to ensure it matches before proceeding
  • On line 10, we use the ColdBox File Utility plugin’s uploadFile method to upload the file. This will return the cffile variable
  • On line 12, if upload was successful (i.e. uploadResult contains the results from the file upload), then we set a message to display to the user to indicate file was successfully uploaded
  • Otherwise on lines 16 and 17, we delete the file if didn’t match the expected mime type, and display a message to the user

Add the Route

Edit configs/Routes.cfm and add the following routes for the new view and handler for uploading the csv file:

// Your Application Routes
with(pattern="/reports", handler="reports")
  .addRoute(pattern="/upload", action="upload")

Test the Upload

OK. So we’re now ready to test what we have done. Let’s browse the main page and refresh the application so the new configurations in ConfigurationCFC and new route take effect, i.e. do this:


Now load the upload page, i.e.


You should see the form for uploading the csv file shown below, and the following after you’ve successfully uploaded the csv file:


That’s it! You’ve just created all the necessary bits to upload a file in ColdBox.

Further Learning and Info

To learn more about the File Utility plugin for the ColdBox platform, please check out the links below:



Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s