×
Namespaces

Variants
Actions
(Difference between revisions)

Progress Bar JavaScript component for Web Runtime

From Nokia Developer Wiki
Jump to: navigation, search
hamishwillee (Talk | contribs)
m (Hamishwillee - Bot update - Fix ArticleMetaData and RevieweApproval)
hamishwillee (Talk | contribs)
m (Hamishwillee - Bot update - Fix metadata etc)
 
(One intermediate revision by one user not shown)
Line 1: Line 1:
{{ArticleMetaData <!-- v1.1 -->
+
[[Category:Code Examples]][[Category:Symbian Web Runtime]][[Category:Mobile Design]]
|sourcecode= [[Media:Wrt_ProgressBar_component.zip]] [[Media:ProgressBarWidget.zip]] [[Media:Wrt_ProgressBar_component.zip]]
+
{{Abstract|This article explains how to create and use a Progress Bar component in Web Runtime widgets. A Progress Bar could be useful during long-running operations, to give a visual feedback to the user about the operation status. Two types of Progress Bars will be handled by this component: with definite and indefinite ranges.}}
 +
 
 +
{{ArticleMetaData <!-- v1.2 -->
 +
|sourcecode= [[Media:Wrt ProgressBar component.zip]] [[Media:ProgressBarWidget.zip]] [[Media:Wrt ProgressBar component.zip]]
 
|installfile= <!-- Link to installation file (e.g. [[Media:The Installation File.sis]]) -->
 
|installfile= <!-- Link to installation file (e.g. [[Media:The Installation File.sis]]) -->
 
|devices= <!-- Devices tested against - e.g. ''devices=Nokia 6131 NFC, Nokia C7-00'') -->
 
|devices= <!-- Devices tested against - e.g. ''devices=Nokia 6131 NFC, Nokia C7-00'') -->
Line 10: Line 13:
 
|capabilities= <!-- Capabilities required by the article/code example (e.g. Location, NetworkServices. -->
 
|capabilities= <!-- Capabilities required by the article/code example (e.g. Location, NetworkServices. -->
 
|keywords= <!-- APIs, classes and methods (e.g. QSystemScreenSaver, QList, CBase -->
 
|keywords= <!-- APIs, classes and methods (e.g. QSystemScreenSaver, QList, CBase -->
|id= <!-- Article Id (Knowledge base articles only) -->
 
 
|language= <!-- Language category code for non-English topics - e.g. Lang-Chinese -->
 
|language= <!-- Language category code for non-English topics - e.g. Lang-Chinese -->
 
|translated-by= <!-- [[User:XXXX]] -->
 
|translated-by= <!-- [[User:XXXX]] -->
Line 22: Line 24:
 
|author= [[User:Jappit]]
 
|author= [[User:Jappit]]
 
}}
 
}}
[[Category:Code Examples]][[Category:Symbian Web Runtime]][[Category:Mobile Design]]
+
[[File:Wrt progressbar widget.png]]
This article explains '''how to create and use a Progress Bar component''' in Web Runtime widgets. A Progress Bar could be useful during long-running operations, to give a visual feedback to the user about the operation status. Two types of Progress Bars will be handled by this component: with '''definite and indefinite ranges'''.
+
 
+
[[Image:Wrt_progressbar_widget.png]]
+
  
The '''Wait and Progress indicator design pattern''' is detailed described by this Nokia Developer Wiki article: [[Mobile Design Pattern: Progress and Wait Indicator]].
+
The "Wait and Progress indicator design pattern" is detailed described by this Nokia Developer Wiki article: [[Mobile Design Pattern: Progress and Wait Indicator]].
  
For more information about progress bars' usage, and '''guidelines about actions and visual feedback to the user''', check out the '''Actions and feedback''' section of the '''Design and User Experience Library''':  
+
For more information about progress bars' usage, and guidelines about actions and visual feedback to the user, check out the ''Actions and feedback'' section of the '''Design and User Experience Library''':  
  
 
[http://library.developer.nokia.com/index.jsp?topic=/Design_and_User_Experience_Library/GUID-A34281EC-A40A-403F-A3E1-74E7C9BD2784.html http://library.developer.nokia.com/index.jsp?topic=/Design_and_User_Experience_Library/GUID-A34281EC-A40A-403F-A3E1-74E7C9BD2784.html]
 
[http://library.developer.nokia.com/index.jsp?topic=/Design_and_User_Experience_Library/GUID-A34281EC-A40A-403F-A3E1-74E7C9BD2784.html http://library.developer.nokia.com/index.jsp?topic=/Design_and_User_Experience_Library/GUID-A34281EC-A40A-403F-A3E1-74E7C9BD2784.html]
Line 35: Line 34:
 
==ProgressBar component: how to use it==
 
==ProgressBar component: how to use it==
 
To use the Progress Bar component presented in this article, follow these steps:
 
To use the Progress Bar component presented in this article, follow these steps:
* '''Import the ProgressBar.js''' JavaScript file in your Widget (source code available here: [[Media:Wrt_ProgressBar_component.zip]]):
+
* '''Import the ProgressBar.js''' JavaScript file in your Widget (source code available here: [[Media:Wrt ProgressBar component.zip]]):
 
<code javascript>
 
<code javascript>
 
<script language="javascript" type="text/javascript" src="ProgressBar.js"></script>
 
<script language="javascript" type="text/javascript" src="ProgressBar.js"></script>
 
</code>
 
</code>
 
* Include in your project '''2 images, of the same size''', for the '''empty and full progress bar''', respectively. Sample images, used in this article, are the following:
 
* Include in your project '''2 images, of the same size''', for the '''empty and full progress bar''', respectively. Sample images, used in this article, are the following:
[[Image:Wrt_progressbar_empty.png]]
+
[[File:Wrt progressbar empty.png]]
[[Image:Wrt_progressbar_full.png]]
+
[[File:Wrt progressbar full.png]]
 
* Define a '''parent HTML node''' for the component in your Widget HTML code:
 
* Define a '''parent HTML node''' for the component in your Widget HTML code:
 
<code javascript>
 
<code javascript>
Line 195: Line 194:
 
The following files, used in this article, are available for download:
 
The following files, used in this article, are available for download:
 
* A sample WRT widget using the ProgressBar component: [[Media:ProgressBarWidget.zip]]
 
* A sample WRT widget using the ProgressBar component: [[Media:ProgressBarWidget.zip]]
* The ProgressBar component source code: [[Media:Wrt_ProgressBar_component.zip]]
+
* The ProgressBar component source code: [[Media:Wrt ProgressBar component.zip]]

Latest revision as of 08:44, 7 May 2012

This article explains how to create and use a Progress Bar component in Web Runtime widgets. A Progress Bar could be useful during long-running operations, to give a visual feedback to the user about the operation status. Two types of Progress Bars will be handled by this component: with definite and indefinite ranges.

Article Metadata
Code ExampleArticle
Created: jappit (08 Jun 2009)
Last edited: hamishwillee (07 May 2012)

Wrt progressbar widget.png

The "Wait and Progress indicator design pattern" is detailed described by this Nokia Developer Wiki article: Mobile Design Pattern: Progress and Wait Indicator.

For more information about progress bars' usage, and guidelines about actions and visual feedback to the user, check out the Actions and feedback section of the Design and User Experience Library:

http://library.developer.nokia.com/index.jsp?topic=/Design_and_User_Experience_Library/GUID-A34281EC-A40A-403F-A3E1-74E7C9BD2784.html

Contents

[edit] ProgressBar component: how to use it

To use the Progress Bar component presented in this article, follow these steps:

<script language="javascript" type="text/javascript" src="ProgressBar.js"></script>
  • Include in your project 2 images, of the same size, for the empty and full progress bar, respectively. Sample images, used in this article, are the following:

Wrt progressbar empty.png Wrt progressbar full.png

  • Define a parent HTML node for the component in your Widget HTML code:
<html>
[...]
<div id="loading_bar"></div>
[...]
</html>
  • Finally, create a ProgressBar instance, passing these arguments to its constructor:
    • the empty bar image path
    • the full bar image path
    • the progress bar width
    • the progress bar height

And then append the newly created instance to the HTML parent node defined above:

progressBar = new ProgressBar('images/progress_empty.png', 'images/progress_full.png', 200, 28);
 
progressBar.appendTo(document.getElementById('loading_bar'));

[edit] ProgressBar component implementation

This part of the articles shows how the ProgressBar JavaScript component is actually implemented.

[edit] ProgressBar constuctor

The first part to implement is the ProgressBar constructor, whose arguments were already shown in the usage part.

function ProgressBar(baseImagePath, fullImagePath, barWidth, barHeight)
{
/* DOM elements */
this.fullImageElement = null;
this.domElement = null;
 
/* Progress Bar size */
this.barWidth = barWidth;
this.barHeight = barHeight;
 
/* loading progress */
this.progressValue = 0;
 
this.init(baseImagePath, fullImagePath, barWidth, barHeight);
}

The costructor initializes the size-related properties of the ProgressBar, sets the initial progress status to zero, and then calls the init() method that will builds up the component DOM structure.

[edit] Building and using component's DOM structure

The whole component DOM structure will be built by the init() instance method, that is implemented as follows:

ProgressBar.prototype.init = function(baseImagePath, fullImagePath, barWidth, barHeight)
{
var container = document.createElement('div');
container.style.position = 'relative';
this.domElement = container;
 
var baseImage = document.createElement('img');
baseImage.src = baseImagePath;
baseImage.style.position = 'absolute';
container.appendChild(baseImage);
 
var fullImageContainer = document.createElement('div');
fullImageContainer.style.position = 'absolute';
fullImageContainer.style.overflow = 'hidden';
fullImageContainer.style.height = barHeight + 'px';
fullImageContainer.style.width = 0;
container.appendChild(fullImageContainer);
this.fullImageElement = fullImageContainer;
 
var fullImage = document.createElement('img');
fullImage.src = fullImagePath;
fullImage.style.position = 'absolute';
fullImageContainer.appendChild(fullImage);
}

The component is structured as follows:

  • an outer DIV element, that contains all the component
  • the empty bar image, completely shown
  • an inner DIV, containing the full bar image, that initially has width equal to zero. Having the 'overflow' CSS property set to 'hidden', the full bar image will be initially hidden, and will be partially or totally shown proportionally to the progress status.

To append the component main DOM element to a parent element defined in a widget, the following appendTo() method is defined:

ProgressBar.prototype.appendTo = function(parentElement)
{
parentElement.appendChild(this.domElement);
}

[edit] Updating the progress status

The following setLoadingProgress() method manages the updates of the progress bar. It accepts as argument the new progress value, that can be any numeric value between 0 and 100, and then updates both the progressValue property, and the UI status of the component.

ProgressBar.prototype.setLoadingProgress = function(value)
{
if(value < 0)
value = 0;
else if(value > 100)
value = 100;
 
this.progressValue = value;
 
this.fullImageElement.style.width = (this.barWidth * value / 100) + 'px';
}

To update the component UI status, the width of the fullImageElement (the DOM element containing the full bar image) is changed proportionally to the new progress value.

[edit] Indefinite progress bars

The setLoadingProgress() is useful if you want to show the exact progress status to the user. But, there are situations where the exact progress status is not known, and the only thing available information is that the long running operation is still running. In these cases, it is useful to show a progress bar that is always animated, so restarting when it reaches the full status.

First, let's define two ProgressBar properties that will be used to handle the indefinite progress bars:

function ProgressBar(baseImagePath, fullImagePath, barWidth, barHeight)
{
[...]
 
/* progressbar type */
this.indefiniteProgress = false;
this.indefiniteInterval = null;
}

Then, the functionality is implemented through the following setIndefinite() method:

ProgressBar.prototype.setIndefinite = function(isIndefinite)
{
if(this.indefiniteProgress != isIndefinite)
{
this.indefiniteProgress = isIndefinite;
 
if(!this.indefiniteProgress)
{
clearInterval(this.indefiniteInterval);
 
this.indefiniteInterval = null;
}
else
{
var self = this;
 
this.indefiniteInterval = setInterval(
function()
{
var nextValue = self.progressValue + 2;
 
if(nextValue > 100)
nextValue -= 100;
 
self.setLoadingProgress(nextValue);
},
100
);
}
}
}

If the isIndefinite argument is true, then the progress bar is treated as indefinite, and an always running animation is started. Otherwise, if it is false, the animation, if running, is stopped.

[edit] Downloads

The following files, used in this article, are available for download:

This page was last modified on 7 May 2012, at 08:44.
123 page views in the last 30 days.