circular-progress

A reactive, flexible, SVG-based circular progress bar for Meteor

Table of Contents

Overview

circular-progress is an SVG circular progress bar written specifically for Meteor. Besides the progress bar itself, you can also display text in the middle of the circle. It's meant to be usable out of the box; just drop {{> circularProgress}} anywhere in your templates and you're good to go!

See it in action at http://circular-progress.meteor.com

Getting Started

Install circular-progress via meteorite:

mrt add circular-progress

You interact with circular-progress via session variables, so if you don't care much about styling, animations or transitions, here's a quick way to start:

Instruction Outcome
Session.set('progressPercent', 30) Sets the progress bar to 30%
Session.set('progressText', "we're 30% there") Sets the text inside the circle

Note that progressPercent takes values from 0 - 100. You can, of course, pass 0.5 but that would be interpreted as 0.5%, not 50%.

Declaring Arguments

Since circularProgress is a regular template, you can pass arguments to it like you normally do.

You can set the data context directly into your template:

{{> circularProgress canvasSIze=250 arcWidth=30}}

You may prefer to pass along an object with the arguments, like so:

<template name="mainTemplate">
  {{#with circularOptions}}
    {{> circularProgress}}
  {{/with}}
</template>

Template.mainTemplate.circularOptions = function() {
    return {
        'canvasSize': 250,
        'arcWidth': 10,
        'sessionValueKey': 'progressValue',
        'tweenDuration': 300
    }
}

Customizing the Progress Bar

Layout

The HTML layout of the progress bar is designed to give you maximum flexibility on how you choose to use it. The SVG itself is nested within two <div> tags, and you can set a CSS class on each. For example:

{{> circularProgress outerDivClass="outer-div" innerDivClass="inner-div"}}

will render

<div class="outer-div">
    <div id="svg-progress-container" class="inner-div">
        <svg>...</svg>
    </div>
</div>

That should allow you to do most anything you want layout-wise, including, for example, centering via outer left: 50% and inner left: -50%.

Aspect

circular-progress is made of three visual components: an outer border, the progress bar and any optional text. You can apply your own CSS class to each of these elements, as follows:

Component Applying a custom CSS Class
Outer Border borderClass="outer-border"
Progress Bar progressClass="progress-circle"
Optional Text textClass="progress-text"

The radius, width and other parameters of the progress bar are set as follows:

Parameter Description
canvasSize Sets the height and width of the SVG element, in pixels
outerPadding Adds a padding between the edge of the rectangular SVG element and the border of the progress bar
spacer Determines the space between the border and the progress bar, in pixels
arcWidth Controls the width of the progress bar
tweenDuration Sets the duration of the transition between two points on the progress bar, in milliseconds

Check out the Options section for details and default values of these parameters.

Using the Reactive Data Sources

You can control the value of the progress bar and the text inside it via Session variables. By default, circular-progress looks for 'progressPercent' and 'progressText', but you can customize what Session keys it uses with the following options:

Parameter Description
sessionValueKey Sets the key used to monitor for progress value changes
sessionTextKey Sets the key used to monitor for text to display

For example, you can set the keys:

{{> circularProgress sessionValueKey="my-value-key" sessionTextKey="my-text-key"}}

Then, you can control circular-progress via these keys:

Session.set('my-value-key', 95);
Session.set('my-text-key', 'Almost there!');

Using Multiple Instances on One Page

You can use more than one progress bar per page, provided you give each a different ID. You probably want to set different session variables too.

Here's an example how to initialize three circular-progress templates on the same page:

{{> circularProgress containerId="svg-container-1" sessionValueKey="value-key-1" sessionTextKey="text-key-1"}}
{{> circularProgress containerId="svg-container-2" sessionValueKey="value-key-2" sessionTextKey="text-key-2"}}
{{> circularProgress containerId="svg-container-3" sessionValueKey="value-key-3" sessionTextKey="text-key-3"}}

Options

Parameter Description Default Value
canvasSize Sets the height and width of the SVG element, in pixels 300
outerPadding Adds a padding between the edge of the rectangular SVG element and the border of the progress bar, in pixels 20
textPadding Adds a padding to the inner text element. Expressed in number of characters 0
spacer Determines the space between the border and the progress bar, in pixels 5
arcWidth Controls the width of the progress bar, in pixels 10
tweenDuration Sets the duration of the transition between two points on the progress bar, in milliseconds 750
sessionValueKey Sets the session variable string used to monitor for progress value changes 'progressPercent'
sessionTextKey Sets the session variable string used to monitor for text to display 'progressText'
containerId Sets the id of the containing div 'svg-progress-container'
outerDivClass Applies the string as a CSS class to the outer <div> container null
innerDivCLass Applies the string as a CSS class to the inner <div> container null
borderClass Applies the string as a CSS class to the border outside the progress bar 'progress-border'
progressClass Applies the string as a CSS class to the progress bar 'progress-circular-bar'
textClass Applies the string as a CSS class to the text inside the progress bar 'progress-text'

Issues

circular-progress was tested with Meteor up to 0.8.1.2. If you encounter any issues, please open a ticket at https://github.com/rteslaru/meteor-circular-progress/issues

Contribute

Pull requests are more than welcome!

License

Released under the MIT license.