Namespace: fn

This plug-in may be used to draw a piechart with only one filled pie (rest empty). It is designed to be an alternative to a progress bar, since it simply depicts a single value (in percent). The plug-in assumes that values in percent are part of the document (either visible or as attribute value) and a small pie representing each value is to be dynamically inserted. This may be either a static display or the pie may be updated upon data changes.

Typical application: Append or prepend to visible percent value:
This mode assumes by default, that a value (integer number between 0 and 100 inclusive, floating point numbers are supported, but truncated) is the only text content of an HTML element, e.g. a span element, and the pie is to be prepended (or appended) to the same element. The pie will usually be auto-sized to fit into the text line. A separator String to be placed between the pie and the number may be configured. Defaults are to prepend the pie and use a non-breaking space as separator. E.g. say you have HTML code like <p>You have achieved 25 points out of 50 (<span class="pie">50</span>%)</p>, then you may insert a pie filled by 50% with $(.pie).progressPie();, resulting in a line like: <p>You have achieved 25 points out of 50 (<span class="pie"><svg>the pie chart</svg>&nbsp;50</span>%)</p>

Usage: Select the elements holding the percent number and to insert the pie into by a jQuery selector. On the jQuery result set call "progressPie(options)", where options is an optional object with configuration options. See Home (or README) for a documentation of supported options. The plugin is applied to any element in the result set, i.e. if the selector did not found any matching element, nothing will happen, while if the selector found several matching elements, the plugin will try to insert a corresponding pie into each of the found elements individually.

The progressPie method will return this, enabling chaining of method calls on the result set.

Stores options for the progressPie plug-in. If this plug-in function is called, any succeeding calls to the progressPie plug-in without argument will behave the same like when called with the options stored here. This is recommended, if the progressPie plug-in gets called repeatedly (to update its graphic due to changed values). Then, this setup provides the means to set the options only once and to keep update calls simple instead of calling the progressPie repeatedly with the same options argument over and over again.

The "update" option, if not specified in the options of this call, will default to true (regardless of the value defined in $.fn.progressPie.defaults.

Usage pattern:

$(selector).setupProgressPie({options}).progressPie();
update value;
$(selector).progresssPie(); //update the graphic using the same options.

Repeated calls of setupProgressPie are allowed and will update the options: The options of the subsequent call get merged into the existing setup. Example:

$(selector).setupProgressPie({color: "green", strokeWidth: 3});
...
$(selector).setupProgressPie({color: "navy"});

In this example the second call will change the color for any following call of progressPie(), but will leave the strokeWidth: 3 option untouched, i.e. will not reset it to the default.

Exception of this rule: You may add a second argument to the plugin call of type boolean. If you append , true, the options will not be merged into an existing setup, but will completely overwrite any existing setup like this was the first call of the setup method at all.

Suppose, in the example above, we change the second setup call to:

$(selector.setupProgressPie({color: "navy"}, true);

Then, this call will not only change the color from green to navy, but also reset the strokeWidth to default.