Progress Indicator

I wrote this plugin to allow more control over the progress indicator. To the right is an animated gif progress indicator. All you can do is show or hide this image. This plugin allows you to make a similar indicator that you can fully control. The plugin will animate both text (including bullets) or images, I guess you could also animate embedded objects, but I haven't tested this. The reason I call this progress indicator dynamic is you can modify or update the objects in the indicator at any time (e.g. replace images or text while the indicator is active). I'll make a demo of this when I have more time :)

In the demo below, you can start or stop the timer to make the progression indicator simulate the animated image or you can move the slider to animate the indicator.



Download: uncompressed | minified | zipped file | github
(zip includes demo; go to link, then download... I'm not sure why you can't download it directly)

Setup

• CSS (basic setup)
  

  .progress {
  position: relative;
  top: 0;
  left: 0;
  width: 200px;
  height: 200px;
  overflow: hidden;
  }
  .progress span {
  position: absolute;
  left: -50px; /* hide spans until initialized */
  top: 0;
  padding: 0;
  margin: 0;
  border: 0;
  }
  .display {
  position: absolute;
  top: 95px;
  left: 90px;
  }

• HTML
  

  <div class="progress">
  <!-- this displays the percent value, position in the middle with CSS -->
  <div class="display"></div>
  <!-- add as many <span>s as you want, add any text or image inside -->
  <span>&bull;</span>
  <span>&bull;</span>
  <span>&bull;</span>
  <span>&bull;</span>
  <span>&bull;</span>
  <span>&bull;</span>
  </div>

• Script - Initialization
  

  <script type="text/javascript" src="jquery.progressindicator.min.js"></script>
  <script type="text/javascript">
  $(document).ready(function(){
  // initialize: initialValue is uaually zero, and a full list of "options" can be found below.
  $(selector).progressIndicator( initialValue, options );
  })

List of Default Settings:

• Use these key : value pairs as follows; Note that the last key : value pair does not have a trailing comma and values that use true or false (Boolean values) should not be in quotes.
  

  $(selector).progressIndicator( initialValue, { key: value, key: value, key: value })

  Key	Value (default shown)	Description
  max	100	The circle is split into this max number of increments (default set to 100 to match a percentage going from 0-99).
  radius	50	Sets the radius of the circle in pixels measured from the centerX and centerY position (middle).
  centerX	100	Positions the center of the circle 100 pixels from the left edge of its container.
  centerY	100	Positions the center of the circle 100 pixels from the top edge of the container.
  clockwise	true	Sets the direction of the rotation. Clockwise if true and counter (or anti for you British folk) clockwise if false.
  startPosition	0.75	This may not make sense if you don't know the coordinate system, but basically zero is the far right side of the circle or the x-y coordinates of ( x=radius, y=0 ) . So if you want to have the indicator start with the "zero" at the top of the circle, you need to start from 75% or 3/4 of your way around the circle. So basically, set 0 to start on the right, .25 (25%) for bottom, .5 (50%) for left and .75 (75%) would be the top of the circle where ( x = 0 , y = radius ).
  sizeStart	80	Sets the starting size of the element to 80 pixels. This sets the font size, the height & width of any element inside the span (like an image)
  sizeDec	4	Sets how much to decrement the size of the next element from the starting size. Try to avoid making the decrement size that would cause the last element to be too small or negative (for example: these settings would not look good, 10 spans inside the progress indicator (in the HTML), sizeStart = 20, sizeDec = 2; this would make the last span element have a size of zero (20 - 2 * 10 = 0).
  showValue	true	Adds the progress indicator value to the "display" class inside the progress div. If you want to be tricky, add the display class to one of your spans to have the indicator move around with the other elements.
  timerActive	false	Initialize progression indicator start and stop functions allowing the indicator to move independent of the percent value.
  timerSpeed	20	Sets the setInterval time in milliseconds.
  timerIncrement	1	At each setInterval call, the progression indicator is incremented by this value. Make this number bigger to speed up the animation, but the bigger the number, the more choppy the animation.

Methods

• Get & Set Progression Value
  

  // Get current value (percentage)
  var value = $(selector).data('progressIndicator').getValue();
  
  // Set/Update current value
  $(selector).data('progressIndicator').update( value );

• Animation timer functions (the timerActive option must be true before these will work)
  

  // Start animation timer
  $(selector).data('progressIndicator').start();
  
  // Stop animation timer
  $(selector).data('progressIndicator').stop();
  
  // Reset animation timer (just resets position)
  $(selector).data('progressIndicator').reset();

Examples - Be sure to look at the demo source to see some other examples of what is possible!

• These examples should be wrapped inside of a:
  
  $(document).ready(function(){ ... })
  
  replace the ellipsis (...) with the script in the column below.
  

Action	Script	Notes:
Set up timer, so the start & stop methods are available. And adjust animation speed.	$('.progress').progressIndicator( 0, { timerActive : true, showValue : false, timerSpeed : 20, timerIncrement : 1 });	The zero in the first line sets the initial position of the indicator, it's not really that important for the animation timer mode, but necessary to include. "timerActive" enables the start and stop timer methods. "showValue" is set to false to hide the progression value. "timerSpeed" and "timerIncrement" were adjusted to make the progression animation fairly quick. In the demo they are set to 50 and 5 respectively so you can see how much faster you could make this animation without it being too choppy.
Rotate counter (anti) clockwise & other adjustments	$('.progress').progressIndicator({ clockwise : false, startPosition : .32, sizeStart : 5, sizeDec : -1 });	Setting the clockwise option to false with reverse the indicator rotation. Note that reversing the direction also effects the "startPosition" so you may need to adjust this value as well. This example is from progression3 in the demo and it needs a startPostion of .32 (32%) to move the images to the top... the reason it isn't 25% is because the sizeStart begins small (5 pixels) and the sizeDec is negative so this actually increases the image size as it progresses through the elements. You'll probably end up tweeking these numbers to get the look you want.
Max value	$('.progress').progressIndicator({ max : 200 });	By default, the progress indicator is set to work with percentages.. it really only goes from 0 to 99%, but by changing the max option, you can set a full rotation of the progress indicator to any value. Note, the value, set using the update method, and the max value can be fractions.