Getting started - Isg-Software

Prerequisites

This plug-in is designed to add graphics to an HTML document to visualize values already part of said document. So one prerequisite is that the numbers (usually percent numbers) are already part of your document, either as visible document text or alternatively invisible as an attribute value of some HTML element. Each element holding such value must be selectable, for example by an id or class attribute. The value (number) itself must be either the sole content of the selectable element, of one of its attributes or of a sub-element. The graphic will then be appended or prepended to the content of that selected element.
The graphics are rendered as in-line SVG. The displaying browser must be capable of rendering SVG (old Browsers aren't), and the plug-in offers no fallback for old browsers, i.e. in those antique browsers the images simply won't be added. The same goes for browsers with disabled JavaScript.
Since this software is a jQuery-plugin, naturally you need to load a recent version of the jQuery library, either loading it from a CDN or downloading and hosting a jQuery lib with your web project.

Simplified usage via Application Script

For a very simple way of using the plug-in, it comes bundled with a second JavaScript file which may optionally be loaded after the plug-in. It automatically applies the jQuery-plugin with some predefined option sets to predefined selectors. This usage does not require you to write JavaScript code yourself, but it does not provide all the possibilities and options of the plug-in.

To enable the application script, simply load the jQuery library, the progresspie plugin file and the application script file into your HTML document's head, which might look like this (loading jQuery from a CDN):

						
<html>
    <head>
        <script type="text/javascript" src="http://code.jquery.com/jquery-1.11.3.min.js"></script>
        <script type="text/javascript" src="/path/to/jquery-progresspiesvg-min.js"></script>
        <script type="text/javascript" src="/path/to/progresspiesvgAppl-min.js"></script>
        …
    </head>
    …

To each body element holding a value which should be added a pie, add the CSS class progresspie. Or alternatively use the class progressring for a ring instead of a pie.
```
						
    …
    <body>
        …
        <p>Progress: <span class="progresspie">33</span> %</p>
        …
    </body>
</html>
					
```
Add further predefined classes or predefined data-attributes to configure the looks of the pie.
See Examples »Appl« for code snippets and their results.

Using the plug-in directly

The “normal” usage of a jQuery plug-in is to write your own JavaScript code, select some elements with a jQuery query and apply the plug-in to the query's result set.

First, of course, your document's head has to load the jQuery library and the plug-in itself (after jQuery). (The Application Script file, see above, is not needed.)

Furthermore, add your own JavaScript code (either in a separate JavaScript file referenced from the HTML or directly in the content of a script element). To simply add SVG graphics once to (static) numbers inside elements of your (static) HTML file, just write an event handler for jQuery's “ready” event. In this event handler create your selection query and apply the plug-in. The simplest use looks something like this:

						
<html>
    <head>
        <script type="text/javascript" src="http://code.jquery.com/jquery-1.11.3.min.js"></script>
        <script type="text/javascript" src="/path/to/jquery-progresspiesvg-min.js"></script>
        <script type="text/javascript" >
            $(function() {
                $(".progress.percent").progresspie();
            });
        </script>
        …
    </head>
    <body>
        …
        <p>Progress: <span class="progress percent">33</span> %</p>
        …
    </body>
</html>

To customize the chart, you may call the plug-in function with an options object as argument, e.g.:

$(".ring.percent").progressPie({
    strokeWidth: 1,
    ringWidth: 3,
    mode: $.fn.progressPie.Mode.COLOR 
});

If a chart should be drawn more than once, i.e the plug-in should not only be called upon loading the page in order to visualize static page content, but later some JavaScript events should be able to update the percent value and the pie/ring chart, then you may use the new setup mechanism introduced in V1.3.0. Here, you specify the options only once with the setup function and then may call the progressPie() plug-in several times with no arguments in order to redraw the graphic with the same options applied:
```
$(".ring.percent").setupProgressPie({
    strokeWidth: 1,
    ringWidth: 3,
    mode: $.fn.progressPie.Mode.COLOR 
}).progressPie();
```
Following update calls (redraw graphic after having changed the percent value):
```
$(".ring.percent").progressPie();
```
Refer to the Examples page for further examples, demonstrating the various options you may pass to the plugin function.
Refer to the generated documentation (JSDoc) for detailed reference.