The cfprogressbar tag has the following characteristics:
- Automatically runs the progress bar for a duration that you specify.
- Dynamically loads data using bind expressions
- Lets styling of the progress bar
- Uses callback and error handlers that give control to the users after the progress bar completes processing or if it encounters any exceptions.
- Lets programmatic control over progress bar using JavaScript APIs.
Progress bar modes
The progress bar supports the following two modes:
Dynamic mode
User specifies the bind expression to provide data for the progress bar to display. The bind attribute specifies a function that determines the indicator length.The following CFM code shows how to use a CFC bind expression:
<cfajaxproxy cfc="pbar" jsclassname="pbar">
<head>
<script>
var utils = new pbar();
var count = 0;
var init = function()
{
document.getElementById('cfpbLabel').style.display = 'block';
ColdFusion.ProgressBar.show('pBar');
ColdFusion.ProgressBar.start('pBar');
}
var hideProgessBar = function()
{
document.getElementById('cfpbLabel').style.display = 'none';
ColdFusion.ProgressBar.hide('pBar');
utils.resetStatus();
}
</script>
</head>
<cfform>
<div id="cfpbLabel" style="display:none">
Saving File:
</div>
<cfprogressbar
name="pBar"
autodisplay=false
bind="cfc:pbar.getProgessData()"
onComplete="hideProgessBar"
width="400" >
<cfset ajaxOnLoad('init')>
</cfform>
|
The following pb.cfc has the function that returns data for the progressbar:
<cfcomponent>
<cffunction name="resetStatus" access="remote">
<!---
Clear count from session so that next time the progress bar runs from the start time.
--->
<cfif session.count gte 10>
<cfset structdelete(session,"count")>
</cfif>
</cffunction>
<cffunction name="getProgessData" access="remote">
<!--- use a count to track progress --->
<cfif not isdefined('session.count')>
<cfset session.count = 1>
<cfelse>
<cfset session.count = session.count + 1 >
</cfif>
<!--- struct with status and message components of the progressbar --->
<cfset data = {status=session.count * 0.1,message=(session.count * 10) & "%"}>
<cfreturn data>
</cffunction>
</cfcomponent>
|
The following CFM code explains how to use the URL bind expression:
<head>
<script>
var init = function()
{
document.getElementById('cfpbLabel').style.display = 'block';
ColdFusion.ProgressBar.show('pBar');
ColdFusion.ProgressBar.start('pBar');
}
var hideProgessBar = function()
{
document.getElementById('cfpbLabel').style.display = 'none';
ColdFusion.ProgressBar.hide('pBar');
}
</script>
</head>
<cfform>
<div id="cfpbLabel" style="display:none">
Saving File:
</div>
<cfprogressbar
name="pBar"
autodisplay=false
bind="url:progressdata.cfm"
onComplete="hideProgessBar"
width="400" >
<cfset ajaxOnLoad('init')>
</cfform>
|
The following is the Progressdata.cfm:
<!--- use a count to indicate progress --->
<cfif not isdefined('session.count')>
<cfset session.count = 1>
<cfelse>
<cfset session.count = session.count + 1 >
</cfif>
<!--- the struct to be sent back; using the populate the status and message components of the progressbar --->
<cfset data = {status=session.count * 0.1,message=(session.count * 10) & "%"}>
<!--- clear count from session to start afresh the next time the program is run --->
<cfif session.count eq 10>
<cfset structdelete(session,"count")>
</cfif>
<!--- data sent back via URL binds must use SerializeJSON() --->
<cfoutput>#SerializeJSON(data)#</cfoutput>
|
The following CFM code has the JavaScript bind expression:
<head>
<script>
var count = 0;
var init = function()
{
document.getElementById('cfpbLabel').style.display = 'block';
ColdFusion.ProgressBar.show('pBar');
ColdFusion.ProgressBar.start('pBar');
}
var hideProgessBar = function()
{
document.getElementById('cfpbLabel').style.display = 'none';
ColdFusion.ProgressBar.hide('pBar');
}
var getProgessData = function()
{
count++;
if(count > 10)
return {STATUS:1,MESSAGE:"Done"}
else
return {STATUS:count*0.1,MESSAGE:(count * 10) + "%"}
}
</script>
</head>
<cfform>
<div id="cfpbLabel" style="display:none">
Saving File:
</div>
<cfprogressbar
name="pBar"
autodisplay=false
bind="javascript:getProgessData()"
onComplete="hideProgessBar"
width="400"
>
<cfset ajaxOnLoad('init')>
</cfform>
|
Manual mode
In the manual mode, you specify the duration the progress bar takes to complete the display of progress. In the following example, autodisplay is set to false as a result of which the progress bar is not shown when the page is first loaded. When the page is loaded, init function is invoked and the function displays and runs the progress bar. The default interval used in this mode is one second.
<head>
<script>
var init = function()
{
document.getElementById('cfpbLabel').style.display = 'block';
ColdFusion.ProgressBar.show('pBar');
ColdFusion.ProgressBar.start('pBar');
}
var hideProgessBar = function(){
document.getElementById('cfpbLabel').style.display = 'none';
ColdFusion.ProgressBar.hide('pBar');
}
</script>
</head>
<cfform>
<div id="cfpbLabel" style="display:none">
Saving File:
</div>
<cfprogressbar
name="pBar"
duration="10000"
autodisplay=false
onComplete="hideProgessBar"
width="400"
/>
<cfset ajaxOnLoad('init')>
</cfform>
|
Working with a progress bar at runtime
This section illustrates how to use the JavaScript API to update the progress bar status. The following CFM code loads a progress bar using the JavaScript API ColdFusion.ProgressBar.updatestatus.
On program load, intit function displays the progress bar and calls the getProgressData JavaScript function to manually update the progress bar. The getProgressData function assigns the status and message variables passed to the JavaScript API update status.
While working with a progress bar at runtime, ensure that you specify a dummy duration (for instance, duration=5000). Even though the custom JavaScript function decides the actual duration, duration is a mandatory attribute.
<cfajaxproxy cfc="pbar" jsclassname="pbar">
<head>
<script>
var utils = new pbar();
var init = function()
{
document.getElementById('cfpbLabel').style.display = 'block';
ColdFusion.ProgressBar.show('pBar');
getProgessData();
}
var hideProgessBar = function()
{
document.getElementById('cfpbLabel').style.display = 'none';
ColdFusion.ProgressBar.hide('pBar');
}
var getProgessData = function()
{
for(i=1;i <= 10;i++)
{
var status = parseFloat(i * 0.10);
var message = Math.round(status * 100) + "%";
ColdFusion.ProgressBar.updateStatus('pBar',status,message);
utils.sleep(1000);
}
hideProgessBar();
}
</script>
</head>
<cfform>
<div id="cfpbLabel" style="display:none">
Saving File:
</div>
<cfprogressbar
name="pBar"
autodisplay=false
duration=15000
onComplete="hideProgessBar"
width="400" >
<cfset ajaxOnLoad('init')>
</cfform>
|
The sleep function in the following CFC provides sleep functionality in the JavaScript code:
<cfcomponent>
<cffunction name="sleep" access="remote">
<cfargument name="timetosleep" default="1000">
<cfset sleep(timetosleep)>
</cffunction>
</cfcomponent>
|
Styling the progress bar
The cfprogressbar has style attribute that lets you decide:
- Background color of the progress bar
- Color of the progress message
- Color of the progress indicator
The following code illustrates styling: style="bgcolor:ADD8E6;progresscolor:6183A6;textcolor:191970"
