Namespace: progressPie

jQuery.fn. progressPie

Namespace for this jQuery plugin
Source:

Namespaces

contentPlugin

Members

(static, readonly) $.fn.progressPie.Mode

Enum defining possible values for the mode option.
Properties:
Name Type Description
GREY Object Default Mode: Pie is drawn in a shade of grey. The HTML color code is "#888" and may be changed by overwriting jQuery.fn.progressPie.Mode.GREY.color (of type string).
RED Object In mode RED the pie is drawn in red color regardless of the percentual value. jQuery.fn.progressPie.Mode.RED.value is a variable of type "number" with the default value of 200 and means the red color will be rgb(200, 0, 0). The variable RED.value is not only used in mode RED, but also in mode COLOR for calculating the color of any value between 0 and 50.
GREEN Object In mode GREEN the pie is drawn in green color regardless of the percentual value. jQuery.fn.progressPie.Mode.GREEN.value is a variable of type "number" with the default value of 200 and means the green color will be rgb(0, 200, 0). The variable GREEN.value is not only used in mode GREE, but also in mode COLOR for calculating the color of any value between 50 and 100.
COLOR Object In mode COLOR the color of the pie is depending on the percentual value. The color is calculated via $.fn.progressPie".colorByPercent. It's the same green color as in mode GREEN for a value of 100 percent, the same red color as in mode RED for a value of 0%. The colors may be altered by overwriting progressPie.Mode.RED.value or progressPie.Mode.GREEN.value.
CSS In mode CSS the color style properties {@code stroke} and {@code fill} of the background circle and the {@code stroke} property of the foreground (pie or ring) are not set at all and are required to be set via CSS rules by the user. (The {@code fill} style of the foreground is always set to 'none', even in CSS mode.)
MASK Object Mask Mode: Requires the use of a content plug-in which adds background content, otherwise your chart will stay completely invisible! If a chart calls one or more content plug-ins which add background content (the pie will be used as a mask applied to the topmost background layer (i.e. the output of the first background content plug-in). In the mask, the areas covered by the pie will be drawn in color jQuery.fn.progressPie.Mode.MASK.color which defaults to 'white', while all the areas not covered by the chart stay transparent. Effectively this default means that only those parts of the background layer that would normally be covered by the chart will stay visible while the rest of the background image will be clipped away.

MASK mode may be combined with options like color, strokeColor and backgroundColor in order to change the mask's transparency for the pie, it's background circle and the filling of the latter.

(See examples page for content plug-ins demonstrating the MASK mode with background images.)
IMASK Inverted Mask Mode: Very similar to MASK mode, only the mask is inverted: By default, the image areas covered by the pie will not show the background but all the rest of the image, the chart will be "cut out of" the background layer.

This is achieved by drawing the pie in a mask layer with color jQuery.fm.progressPie.Mode.IMASK.color, which defaults to 'black' on a background rectangle filled in color jQuery.fm.progressPie.Mode.MASK.color, which defaults to 'white'.

IMASK mode may be combined with options like color, strokeColor and backgroundColor, with color overriding the pie's mask color (defaulting to black) and background overriding the pie's fill color (defaulting to white) and the filling of the background rectangle. The latter makes the difference in comparison to just using MASK mode and switching the color and backgroundColor value: In MASK mode, backgroundColor only defines a fill color for the inside of the circular chart, in IMASK mode the whole rectangular chart area (including the padding, if set) will be filled!

Source:

(static, readonly) $.fn.progressPie.RingAlign

Enum defining possible valus for the ringAlign option.
Properties:
Name Type Description
OUTER Both strokes (background circle and ring graph) are drawn on the outer edge of the (circular) chart.
If the overlap option is set to false, the outer edge of the ring will be aligned with the inner edge of the background circle, i.e. the ring will be drawn inside of the background circle.
CENTER In this mode, the ring is drawn centered on top of background circle (provided, the overlap option is not turned off). If the ring is wider, it will overlap the background circle equally to the outside and to the inside of the circle, if it is slimmer, it will be centered "inside" the background circle.
INNER In this mode, both of the two stroke (background circle and ring graph) will align towards the center of the circle, i.e. share the same inner radius.
If the overlap option is set to false, the inner edge of the ring will be aligned with the outer edge of the background circle, i.e. the ring will be drawn around the background circle, the latter will be shrunk to fit into the ring.
Source:

(static) defaultAnimationAttributes

Default SMIL animation attributes for value transitions. keys and value syntax follow the SMIL language for SVG animation. Each property of this object will be turned into an attribute of the SMIL animation element, the property's key serving as attribute name, the property's value as attribute value.

If the plug-in is called with option animate: true, these options will be applied to the animation.
If the plug-in is called with option animate: {options}, the options enumerated by the user get added to these defaults. Each stated option will override the default option, while those properties of this defaults object that are not overridden by the user will be applied unchanged.
If the user, for example, adds the option animate: {dur: "2s"}, the default duration will be overriden, the animation will last 2 seconds, while the other animation properties (spline mode) will be applied exactly as defined in this defaults object.

Properties:
Name Type Description
dur string the duration of the animation (number with unit, e.g. "1s" or "700ms")
calcMode string mode for calculating the animation speed, defaults to "spline", see SMIL specification.
keySplines string see specification
keyTimes string see specification
Source:

(static) defaults

Default Options. This is a public (static) object in order to allow users to globally modify the defaults before using the plug-in.
Properties:
Name Type Description
mode Mode A value of the enum type Mode, defaults to $.fn.progressPie.Mode.GREY
margin number a single number or an array of up to four numbers, defaults to 0 (no margin at all). If this is a single number (or an array of length 1), this is the width of a region around the pie chart to be left blank (transparent), i.e. number 5 means that the image is going to be 10 pixels wider and higher because a 5 pixel wide margin is inserted all around the pie. If this is an array of length 4, the first value is the top margin, the second the right margin, the third is the bottom margin and the fourth is the left margin, i.e. the margins are specified "clockwise" starting at 12 o'clock, just like in CSS's shorthand margin syntax. If this option is an array of length 3, only the top, right and bottom margin are specified directly and the left margin will be the same as the right margin. If this is an array of length 2, the first value specifies top and bottom margin and the second right and left margin.
padding number a single number or an array of up to four numbers, defaults to 0 (no padding at all). A padding is an inner border left free between the margin and the pie chart. In most cases, margin and padding behave the same. If both are specified, they add up. A difference may only be seen when using certain content plug-ins (like the predefined image plug-in), which may for example add a background image or color not only covering the area of the pie chart itself, but the chart plus its padding (but not covering the margin).
strokeWidth number The default width of the background circle stroke, defaults to 2
overlap boolean if true (default), the foreground pie or ring fragment is drawn full size on top of the always visible background circle stroke, overlapping it. If set to false, the foreground pie/ring will be scaled down to fit into the background circle, not overlapping the latter's stroke. This is only advisable if the strokeWidth is small enough to leave free space inside the background circle. Also, this only makes any sense if the background circle's color differs from the foreground color (i.e. the strokeColor option is set) or if the foreground color is semi transparent.
ringAlign: RingAlign defaults to $.fn.progressPie.RingAlign.OUTER, defines the alignment of a ring chart (only defined if the ringWidth option is set and > 0) with the background circle (requires the strokeWidth option to be > 0).
prepend boolean true for prepending the SVG graph to the selected element's content, false for appending. Defaults to true.
separator string String to be inserted between prepended or appended SVG and target element's content. If the target element is empty, i.e. there's no content to append or prepend the graph to (example: <span class="pie" data-percent="10"></span>), the separator and prepend options will be ignored and only the SVG will be inserted into the element (starting with V2.0.0)
verticalAlign string CSS value for the verticalAlign style attribute of the inserted SVG node (defaults to "bottom", option is ignored in special CSS mode).
update boolean true will remove any SVG child from the selected target element before inserting a new image, false will only insert a new SVG if none exists yet. Defaults to false.
valueAdapter function Function takes a value (string or number) and returns a number in range (0..100), defaults to a function returning number values unchanged and applying parseFloat to string values. Note that this may parse percent numbers with decimal digits if the "dot" is used as decimal separator, while if any unknown character like a comma (european decimal separator) is found, the parsing stops and the rest of the string is ignored. I.e. a string like "23.5" is parsed as twenty-three and a half percent while "23,5" is parsed as exactly 23 percent, which usually should be exact enough if the pie chart is not very big.
valueInputEvents string space-separated list of event names, defaulting to "change". This property is only used in conjunction with the valueInput option (and only using the setupProgressPie() function). The valueInput option binds a progress pie/ring to an input element and automatically registers an event handler listening on the input element to these events. If any of these events (by default only the change event) fires, the pie will automatically be updated to the current input's value (.val()).
ringEndsRounded boolean If setting a ringWidth, this flag controls if the ends of the ring are simply cut (false) or if half a circle is appended to each end of the ring section (true). Defaults to false.
sizeFactor number Defaults to 1. The "original" diameter for the pie chart as either auto-sized or specified by the size option, is multiplied with this factor to get the final diameter before drawing the pie chart.
scale number Defaults to 1. The already rendered SVG graphic is finally scaled by this factor. In difference to sizeFactor this does not simply change the diameter/radius of the chart, but scales all other aspects such as the strokeWidth, too.
defaultContentPluginBackgroundMarginFullSize number Defaults to 0. Sets the default value for a content plug-in's margin property if that plug-in uses the API's getBackgroundRadius() function, if the contentPluginOptions object does not specify a margin property and if a pie chart is drawn (i.e. the ringWidth option is not set) or if (on a ring chart) the fullSize property of the contentPluginOption is set to true.
The value of 0 causes a filled background to cover the whole pie.
defaultContentPluginBackgroundMarginInsideRing number Defaults to 1. Sets the default value for a content plug-in's margin property if that plug-in uses the API's getBackgroundRadius() function, if the contentPluginOptions object does not specify a margin property and does not set fullSize and if a ring is drawn (i.e. the ringWidth option is set).
The default value of 1 leaves free circular gap of 1 pixel between the ring and the filled content plug-in's background inside the ring. With a value of zero, the content background would "touch" the ring.
cssClassBackgroundCircle string name of a CSS class assigned to the circle shape drawn as background behind the pie or ring segment. Defaults to progresspie-background.
cssClassForegroundPie string name of a CSS class assigned to the pie or ring segment (foreground). Defaults to progresspie-foreground.
cssClassOuter string If the inner option is used to draw a second value, this CSS class is assigned to the background circle as well as the foreground pie/ring segment of the outer/main value in addition to the respective cssClassBackgroundCircle or cssClassForegroundPie class. Defaults to progresspie-outer.
cssClassOuter string If the inner option is used to draw a second value, this CSS class as assigned to the background circle and the forground pie/ring segment of the inner value in addition to the respective cssClassBackgroundCircle or cssClassForegroundPie. Defaults to progresspie-inner. If the inner option contains a second inner option (third value), the background and foreground elements of the "inner inner" value get assigned this class with suffix "2", an "inner inner inner" value will be assigned this class with suffix "3" and so on.
Source:

(static) prevInnerValueDataName

Just like prevValueDataName, but used for double/multiple pies: The lastly drawn percent value for the inner pie will be stored in a data entry of this name. If even more than two values are drawn (by nested inner options), the value of a number will be appended to this name. So the lastly drawn value of the third pie (inner.inner) will be stored in a data entry named prevInnerValueDataName+"2".
Source:

(static) prevValueDataName

If a user enables animated state transitions via the animate option, the plug-in stores the last drawn value in jQuery's data map associated with the target element. If the user later first updates the value to be shown and then calls the progressPie() plug-in again on the target element, it will not only find the new value, but also the previous value in said data, which it needs to calculate the transition.

This option defines the name of the data entry which will be added to the target DOM node to hold the lastly draw percent value.

Source:

Methods

(static) colorByPercent(percent, alpha)

public static method to calculate a color for a percent value: green for 100%, red for 0%, yellow for 50%, gradients for values in between. This is used internally in mode progressPie.Mode.COLOR
Parameters:
Name Type Description
percent number a value between 0 and 100 (inclusive). 0 results in red color, 100 in green, 50 in yellow, any other value greater than 50 generates a gradient between green and yellow, values less than 50 a gradient between red and yellow.
alpha number optional second parameter. If defined, the calculated color will not be a fully opaque rgb(r,g,b) value, but instead rgba(r,g,b,alpha). Has to be a number between 0 and 1 inclusive and defines the transparency (0 for fully transparent, 1 for fully opaque).
Source: