Join Daniel Short for an in-depth discussion in this video Using the cfprogressbar tag, part of ColdFusion 9: AJAX Controls and Techniques.
So to get started, we'll create a new ColdFusion page. We'll just call it cfprogressbar.cfm. I am just going to add a little bit of styling to make sure that the elements that we are going to be building in this video don't all bump right up against the edge of our browser. So I am just going to add a little bit of margin and padding to our paragraph and body tags. So with that let's get started. To use a cfprogressbar you first need to have a cfform on your page, and then within that cfform, I am going to add a paragraph tag and then a cfprogressbar tag.
Now our progressbar we need to give a name. The first one we are going to do is a progressbar that just runs for a set duration. So I'll call that durationBar, and then we specify how long we want that to run, and this is done in milliseconds. So for the duration I am going to do 10,000 milliseconds, which should run for 10 seconds. Then I specify the interval that I want that progressbar to be updated, also in milliseconds. So we'll set that to update every one second, and then I can specify a width for my bar.
So we show our progress bar and then we start it. So now let's create a button to actually kick that off. So we'll say type=button and we've got to give it a name. We'll give it a value, Start the Duration Bar, and then onclick I am going to run startProgress, and make sure I pass it the name of the progress bar we want to start. All right, let's go back to our browser and give that a try.
So on our cfprogressbar tag, I can tell it to run a function when it's completed. So oncomplete I am going to run a function called onFinish. So now I just need to create that function. So function onFinish, and I am just going to alert the fact that it's done. All right, so we'll go back to our browser and we'll reload, we'll click Start, and then we'll patiently wait for our long running task to finish, and when it hits the end, I should get an alert that says Done.
And there we go, so I know that that progress bar has finished. So that's the simplest progress bar you can create. It just runs for a set number of seconds and updates at a set interval. But usually when you are using a progress bar you are going to be performing some long-running task on the server. So next we are going to build a progress bar that actually checks to get its status from a CFC. So I am going to go ahead and duplicate this one and I am going to change its name, so we'll call this one cfcBar, and we'll say startCFCbar. Go and change all of our labels first and then next I am going to get rid of the duration, and instead I am going to use a bind expression.
And I am going to bind the status of this progress bar to a cfc called progress, and we are going to check the method called getStatus. So I already have this CFC created so let's go into the finished folder. I am going to copy this out and put it in our Chapter 3 folder and just take a look at it. So what this component does is it has one method as you can see called getStatus and it creates a structure with a message.
The message start as Saving Data and then it checks to see if I have a session value called STATUS. If I don't, it's going to set the initial status to 0.1 and then it's going to sit and wait for 200 milliseconds. If I do have a status but it's less than 0.9 then it's going to increase that status by 0.1 and then Sleep again. Otherwise my STATUS is greater than 0.9. So I am going to say that I am all done and my STATUS is set at a value of 1.
And then next I am going to make sure I return that status. So what's happening is these point value show that this status bar is 10% finished as it loops through here. It's then set to 20%, 30%, 40%, etcetera, until it gets to 90% and then it's finally set to Done. So this message is actually going to display in our status bar, and this value is going to determine how much of that bar should be filled. So the next thing we need to do is on our cfprogressbar.cfm page, I need to make sure that every time this page loads, my session.status value is blank.
So we are going to do StructDelete (Session, "Status") so every time this page loads, I am going to make sure there is not status value, and then when that bar first starts running, it's going to set my status value. And I know that's a lot to take in, but let's go ahead and see how it works in the browser. Reload and you see my status bar showing by default here. On the cfprogressbar, I can set a value to autodisplay, and set that to false.
So let's take a closer look at what happened. On the first request, it made a request here to say getstatus and it wants the json value returned, and then in the response it will turn the message saving Saving Data and my STATUS was 0.1. Go ahead and collapse that one, and on the second request my response say Saving Data and the STATUS was 0.2. As we go along, the STATUS gets updated, 0.3, some kind of goofy rounding error converting the value to json, but that's okay, then 0.4, and then at the very end here, we can see the response was almost 0.1 and the very last one was 1.0.
I tell it how far along I want the progress bar to be, and then I tell it what I want displayed inside of that progress bar. So then we'll say "Perform Step 1" and we'll just put a pipe in between there, and then I am going to create three more links. This one will update it to 0.5, that one to 0.75, and this one to 1, then we'll say "Perform Step 2, 3 and 4." 2, 3, and 4.
All right, let's go back to Firefox, we'll reload our page, and I'll click Perform Step 1. You will notice it's filled up a quarter of the way and it says "Doing Step 1." Perform Step 2, 3. I can go back to Step 2, back to Step 1. I can jump back-and-forth all I'd like and when I click Perform Step 4, then the bar fills up completely. So hopefully your mind is turning with ideas of where you are going to place a progress bar in your application. I have shown you how to build one that just updates at a set interval.
I have shown you another one that actually pulls it status directly from a CFC, and I have shown you how to manually update a progress bar on demand.
- Manipulating and securing container contents
- Debugging AJAX behaviors
- Building UI elements such as accordions and border layouts
- Using rich prompts with cfmessagebox
- Understanding advanced cffileupload
- Sorting and grouping data in grids
- Binding data to form fields
- Creating a map with markers