Namespace: contentPlugin

Default Options. This is a public (static) object in order to allow users to globally modify the defaults before using the checkComplete content plug-in.

Default Options. This is a public (static) object in order to allow users to globally modify the defaults before using the controlIcon content plug-ins.

Default options for the content plug-in "cross". Extends the jQuery.fn.progressPie.contentPlugin.errorIconsCommonDefaults with the following default option:

Common default options for all three plug-ins of the errorIcons plug-in package/file, i.e. this object defines default options for the plug-ins "cross", "exclamationMark" and "warning", but only those defaults all three of these plug-ins have in common. For each plug-in there is a separate defaults object extending this one with further plug-in specific defaults.

This is a public (static) object in order to allow users to globally modify the common defaults for all three plug-ins globally.

Default options for the content plug-in "exclamationMark". Extends the jQuery.fn.progressPie.contentPlugin.errorIconsCommonDefaults with the following default option:

Default Options for the content plug-in "image". This is a public (static) object in order to allow users to globally modify the defaults before using the image content plug-in.

Default Options. This is a public (static) object in order to allow users to globally modify the defaults before using the valueDisplay content plug-ins.

Default options for the content plug-in "warning". Extends the jQuery.fn.progressPie.contentPlugin.exclamationMarkDefaults with the following default option:

SVG Content Plug-in for jquery-progresspiesvg: Adds a square as background to a progress pie. The square's area is the area of the actual chart plus its padding (padding defaults to zero but can be set in the progress pie's options).

Use this plug-in by adding the option contentPlugin: "backgroundRect" (or contentPlugin: $.fn.progressPie.contentPlugin.backgroundRect) to your call of the progressPie plug-in.

Furthermore, also add the option contentPluginOptions to the progressPie plugin options. The following options are supported:

• stroke: string defining the stroke of the rectangle (a color code or 'none')
• fill: string defining the filling of the rectangle (a color code or 'none')
• strokeWidth: number, optional: Width of the stroke in pixels.

At least on of the options stroke or fill has to be specified. If you only want a filled square without a differently colored outline, only set the fill option and leave the stroke option undefined (no need to set it to 'none'). Or vice-versa: If you want to draw a non-filled square, just set stroke and optionally also strokeWidth.

Please note: This function is called internally by the progressPie jQuery plug-in! Don't call this function directly, but use it as described above!

SVG Content Plug-in for jquery-progresspiesvg: Does nothing for values less than 100%, but draws a check mark / tick onto the fully filled pie resp. inside the full ring for a value of 100%. Use by adding the option contentPlugin: "checkComplete" (or contentPlugin: $.fn.progressPie.contentPlugin.checkComplete) to your call of the progresspie plug-in.

Additional arguments may be supplied by adding the option contentPluginOptions to the progressPie plugin options. This is to be an object which may hold the following properties:

• strokeWidth: Defaults to 2. Width of the stroke for the check mark (not equal to the strokeWidth option of the pie chart (outer circle)
• lineCap: Defaults to "round", may take any value allowed for the SVG line-cap style, like "square".
• color: draw the check mark in a specific color (defaults to the color of the surrounding ring chart resp. to white on a pie chart).
• backgroundColor: Defaults to undefined. If undefined, the check icon is drawn directly onto the fully filled pie resp. onto the blank space inside a fully filled ring. Especially if combined with a ring, you may optionally set this option do draw a filled circle inside the ring and to draw the check mark onto this circle.
• fullSize: Only for progress rings (and only meant for combination with a backgroundColor): Setting this to true causes the filled background circle of the check icon to fully cover the whole ring chart instead of being drawn inside the free space of the ring. Defaults to false.
• inBackground: boolean, defaults to false. If set to true, the icon will be drawn behind the chart instead of on top of it. In that case, the chart has to provide some kind of transparency in order for the check icon to be at least partly visible, e.g. by using a foreground color with alpha channel (rgba) or by drawing a ring chart with free/transparent room in the middle.
• margin: number, defaults to undefined: Only used if the backgroundColor option is set. In that case, it defines the margin in pixels left free around the filled background circle. For a progress pie or if the fullSize option is truthy, this value (if the property is not set) defaults to zero, which means the background completely covers the pie graph. Increasing the value will reduce the icon in size, leaving some of the pie chart visible around it.
  For a progress ring without fullSize option, the default margin value (if the property is not set) is 1, meaning a gap of 1 pixel width is left free between the ring and the filled background. Set this to zero in order for the background to "touch" the ring, or to a negative value in order to (partially) overlap the ring.
• iconSizeFactor: Defines the ration between the background radius and the radius of the circumcircle of the check's stroke. I.e. if set to 1.0, the check's stroke ends will touch the edge of the background circle, smaller values will leave a margin between the background and the check. This defaults to 0.6 if the check is drawn onto a pie or if the backgroundColor option is set. If the check is drawn directly into the inner space of a ring graph without background color, this defaults to 0.8.
• animate: boolean or string with duration (number and time unit): If true or string, an animation drawing the check (from left to right) will be added. If the value is a string, it has to be a valid duration value defining the speed of the animation. If "true", the default duration (1s) will be applied.
• contentPlugin and contentPluginOptions: These options are ignored vor a value of 100%, i.e. in case the check mark gets drawn as content for the progress pie. But if set, this content plug-in will delegate to the alternative content plug-in stated here-in for any percent value less than 100%. I.e.: This plug-in will decide if the percent value is 100 or less, in the first case drawing the check mark as content, while in the second case, i.e. for any percent value in 0..99, the content of this "secondary" plug-in will be added to the pie/ring chart.

Please note: This function is called internally by the progressPie jQuery plug-in! Don't call this function directly, but use it as desrcibed above!

SVG Content Plug-in for jquery-progresspiesvg: Draws a cross icon on top of a pie or ring chart.

By default this is a white cross (X) on red background, an icon commonly used to indicate, that an error occurred. Therefore, this plug-in is intended to be used whenever a process, whose progress you were monitoring with a pie or ring chart, terminates abruptly due to an error.

You may choose whether the progress indicator should still remain visible (thus showing an error icon along with the percentual progress value of the state when the error occurred) or should be completely occluded by the error icon:

Drawn onto a pie chart, the icon is drawn on top of the whole pie, by default covering the pie completely by the opaque background color. In order for the progress to remain visible, you may change the background color to a semi transparent background or turn it off completely, simply drawing a cross on top of the pie.

Drawn onto a ring chart, the icon is by default fitted inside the ring, so the ring itself is not occluded. You may customize the gap between the error icon and the ring as well as set a fullsize option in order to completely cover the whole graph, if you prefer to.

See the content plug-in examples page for various demonstrations.

Use this plug-in by adding the option contentPlugin: "cross" (or contentPlugin: $.fn.progressPie.contentPlugin.cross) to your call of the progresspie plug-in.

Additional arguments may be supplied by adding the option contentPluginOptions to the progressPie plugin options. This is to be an object which may hold the following properties:

• strokeWidth: number, defaults to 2. Width of the stroke for the cross (not equal to the strokeWidth option of the pie chart (outer circle)
• lineCap: string, defaults to "round", may take any value allowed for the SVG line-cap style, like "square".
• iconColor: string, color code, defaults to "white": The stroke color for the actual cross icon.
• withBackground: boolean, defaults to true. I.e. by default a filled background circle will be drawn and the error icon will be drawn on top of that. Set to false to omit this circle and solely draw the error icon.
• backgroundColor: string, color code, defaults to "red": Sets the fill color for the background circle (if withBackground is not set to false).
• fullSize: boolean, defaults to false. Only affects drawing on a ring chart (i.e. option ringWidth was set): In this case, the value true causes the background to cover the whole ring graph and not just the free space inside the ring.
• inBackground: boolean, defaults to false. If false, the content is drawn on top of the pie or ring chart, if true, the pie or ring chart is drawn on top of the error icon. This only makes a difference if both overlap, i.e. if you draw a pie or if the cross icon is larger than the free space inside the ring graph.
• margin: number, defaults to undefined: Only used if the backgroundColor option is set. In that case, it defines the margin in pixels left free around the filled background circle. For a progress pie or if the fullSize option is truthy, this value (if the property is not set) defaults to zero, which means the background completely covers the pie graph. Increasing the value will reduce the icon in size, leaving some of the pie chart visible around it.
  For a progress ring without fullSize option, the default margin value (if the property is not set) is 1, meaning a gap of 1 pixel width is left free between the ring and the filled background. Set this to zero in order for the background to "touch" the ring, or to a negative value in order to (partially) overlap the ring.
• iconSizeFactor: number, defaults to 0.6. This defines the ratio between the while error icons size (i.e. the diameter of the circle filled with the backgroundColor and the cross icon itself (i.e. the diameter of the imaginative circle closest surrounding the X icon). In other words: The closer to 1, the larger the cross icon will be and the less margin will remain between the cross and the outer edge of the filled background circle.
• animate: boolean or string with duration (number and time unit): If true or string, an animation drawing the check (from left to right) will be added. If the value is a string, it has to be a valid duration value defining the speed of the animation. If "true", the default duration (1s) will be applied.
• cssClass: String, defaults to "progresspie-erroricon". Defines the CSS class of the actual cross icon (path).
• cssClassBackgroundCircle: String, defaults to "progresspie-erroricon-background". Defines the CSS class of the background circle

Please note: This function is called internally by the progressPie jQuery plug-in! Don't call this function directly, but use it as desrcibed above!

SVG Content Plug-in for jquery-progresspiesvg: Draws an exclamation mark icon on top of a pie or ring chart.

By default this is a white exclamation mark (!) on yellow background, an icon commonly used to indicate a warning.

Other than drawing an exclamation mark instead of a cross and of using a different default background color, this plug-in is practically identical to the "cross" plug-in, so please refer to jQuery.fn.progressPie.contentPlugin.cross for more documentation.

SVG Content Plug-in for jquery-progresspiesvg: Add an image to a progress pie chart, by default in background, alternatively in foreground. The image has to be available as external file in a web compatible format such as SVG, JPEG or PNG. This plug-in needs at least one argument (option href) specifying the URL from which to load the image. It will insert an image element into the SVG containing this reference URL. When rendering the pie's SVG code, the browser will then resolve this URL and lazily load the actual image resource, just like browsers load image files specified by img tags with href attributes in HTML.

The images, at least background images, used should usually be square (i.e. width == height). Non-square images are shrunk to fully fit into the square target area, vertically resp. horizontally centered.

The target area, in which the image is fitted, is by default a square. You may set the clipCircle option in order to clip this square to a circle (with the square's width as diameter). Non-circular images fitted into that square will then be circularly clipped.

When drawing a pie, the target square is the full area covered by the pie chart plus the padding around it (which defaults to 0 but may be specified via the progressPie's padding option).

When drawing a ring (i.e. progressPie's ringWidth option is defined), then, by default, this target area is fitted into the ring such that its width (and height) is the width of the free space inside the ring minus twice the margin which may optionally be set in the contentPluginOptions, see below. Yet this square area will still overlap the ring (except if the clipCircle option is true, see above).

In ring mode you may set the fullSize option to true. In this case the image's target area is equivalent to that in pie mode.

Via the inBackground option you may specify whether the image is to be positioned on top of the chart or behind it.

A background image may also be used to fill the pie chart (instead of the background behind it). To achieve this, the pie has to be drawn in MASK mode, and the image has to be drawn as its first background (i.e. option inBackground has to be true (default) and no other content plug-in also draw into the background must be inserted before the image). See examples.

To use this content plug-in add the option contentPlugin: "image" (or contentPlugin: $.fn.progressPie.contentPlugin.image) to your call of the progresspie plug-in.

Furthermore, also add the option contentPluginOptions to the progressPie plugin options. This is to be an object which must hold at least an href option. The following options are supported:

• href: string, mandatory, holding the URL from which to load the image file.
• clipCircle: boolean, defaults to false. If true, the target area (square) is reduced to a circle. The image is clipped by this circle, i.e. all areas of the image outside the circle will be invisible.
• fullSize: boolean, defaults to false. Only affects drawing on a ring chart (i.e. with option ringWidth set): In this case, the value true causes the image to cover the whole ring graph (plus optional padding) instead of just the free space inside the ring.
• inBackground: boolean, defaults to true. If false, the content is drawn on top of the pie or ring chart, if true, the pie or ring chart is drawn on top of the image. This only makes a difference if both overlap or if the MASK mode is used.
• margin: number, defaults to undefined: Defines the margin in pixels left free around the image inside its target area. For a progress pie or if the fullSize option is truthy, this value (if the property is not set) defaults to zero. For a progress ring without fullSize option, the default margin value (if the property is not set) is 1.

Please note: This function is called internally by the progressPie jQuery plug-in! Don't call this function directly, but use it as desrcibed above!

SVG Content Plug-in for jquery-progresspiesvg: Draw a pause control icon (2 vertical bars) into the ring graph. Usage: See jQuery.fn.progressPie.contentPlugin.stop

SVG Content Plug-in for jquery-progresspiesvg: Draw a play control icon (triangle pointing to the right) into the ring graph. Usage: See jQuery.fn.progressPie.contentPlugin.stop
Note that the size (height and width) of the play icon is always a bit larger that of the stop or pause icon, because overall the area filled by the triangle is much smaller than that of the square (stop icon). The optional maxSize option specifies the maximum height and with for "stop" and "pause", while the maximum width and height of this "play" symbol are a bit larger than maxSize (currently 20% larger).

SVG Content Plug-in for jquery-progresspiesvg: Display the percent value (rounded to integer) with a "%" label inside a ring graph rendered by the progressPie component.

Use by adding the option contentPlugin: "percent" (or contentPlugin: $.fn.progressPie.contentPlugin.percent) to your call of the progresspie plug-in.

Additional arguments may be supplied by adding the option contentPluginOptions to the progressPie plugin options. This is to be an object which may hold the following properties:

• singleLine: Default is "undefinied". If truthy, the unit label ("%" in this case) is displayed in the same line behind the percent value, otherwise in a new line below the value.
• fontSizeFactor: Number, Default is 1.0 (0.9 in singleLine mode). The font-size for the percent number inside the ring is the inner radius of the ring multiplied by this factor. E.g. to shrink the text by 10%, set fontSizeFactor to 0.9. A factor larger than 1.0 is not recommended, because the text (especially a "100") might not fit into the graphic!
• unitFontSizeFactor: Number, Default is 0.35. Defines the font size for the unit label ("%"), see fontSizeFactor.
• color: color code (string). Defaults to the color of the ring graph (except in CSS mode, where color defaults to undefined, in which case no font color will be set in the SVG itself as long as this property is not set, leaving the font color subject to CSS stylesheets). Override this option in order to draw content in different color than the surrounding ring.
• cssClass: String. Value for the class attribute. Especially in CSS mode the class enables you to style the font color via CSS. This option can be used to override the default class name ("progresspie-valuedisplay").
• cssClassUnit: String. If the value display contains a unit label (as sub-element of the text element), this unit is fitted with a class name, too. So you can style the unit string differently from the value display itself. Use this option to override the default class name ("progresspie-unit").

Please note: This function is called internally by the progressPie jQuery plug-in! Don't call this function directly, but use it as desrcibed above!

SVG Content Plug-in for jquery-progresspiesvg: Display the the raw value of a ring graph (before translation to a percent value via a valueAdapter function) inside the ring graph, optionally combined with a second string, intended as a unit label for the value.

Use by adding the option contentPlugin: "rawValue" (or contentPlugin: $.fn.progressPie.contentPlugin.rawValue) to your call of the progresspie plug-in.

Additional arguments may be supplied by adding the option contentPluginOptions to the progressPie plugin options. This is to be an object which may hold the following properties:

• unit: String, default is "undefined". If defined (typeof unit === "string"), this string will be displayed behind or below the value. It should be a very short string holding a unit label like "s" or "sec.". If not of type string (especially if left undefined), the value will be the sole content.
• singleLine: Default is "undefinied". If truthy, the unit label (see above) is displayed in the same line behind the percent value, otherwise in a new line below the value.
• fontSizeFactor: Number, Default is 1.0 (0.9 in singleLine mode). The font-size for the percent number inside the ring is the inner radius of the ring multiplied by this factor. E.g. to shrink the text by 10%, set fontSizeFactor to 0.9. A factor larger than 1.0 is not recommended, because the text (especially a "100") might not fit into the graphic!
• unitFontSizeFactor: Number, Default is 0.35. Defines the font size for the unit label, see fontSizeFactor.
• color: color code (string). Defaults to the color of the ring graph. Overwrite to draw content in different color than the surrounding ring.

Please note: This function is called internally by the progressPie jQuery plug-in! Don't call this function directly, but use it as desrcibed above!

SVG Content Plug-in for jquery-progresspiesvg: Draw a stop control icon (square) into the ring graph. Use by adding the option contentPlugin: "stop" (or contentPlugin: $.fn.progressPie.contentPlugin.stop) to your call of the progresspie plug-in.

Additional arguments may be supplied by adding the option contentPluginOptions to the progressPie plugin options. This is to be an object which may hold the following properties:

• maxSize: maximum size in pixels for the square (width/height of the square)
• color: draw the icon in a specific color (defaults to the color of the surrounding ring chart). If you omit this option and the chart also has no script-defined color (in CSS mode), this plug-in won't add any inline color styles, but will leave the styling to an external stylesheet (just like the chart itself does in CSS mode).
• cssClass: custom value for the class attribute to be added to the icon shapes. Defaults to "progresspie-control-icon". The class is specifically useful to define CSS selectors for styling in CSS mode, see above (and see examples).

Please note: This function is called internally by the progressPie jQuery plug-in! Don't call this function directly, but use it as desrcibed above!

SVG Content Plug-in for jquery-progresspiesvg: Draws triangular warning sign icon on top of a pie or ring chart.

This resembles the jQuery.fn.progressPie.contentPlugin.exclamationMark plug-in, but it does not fill a complete circle with the background color (by default: yellow), but will fit a triangular sign (optionally with rounded corners) into the circle and draw an exclamation mark (!) onto that triangle. (See examples)

The contentPluginOptions supported by this plug-in are largely identical to those of jQuery.fn.progressPie.contentPlugin.exclamationMark or jQuery.fn.progressPie.contentPlugin.cross, only one option specific to this plug-in has been introduced:

• borderRadius: number, defaults to 0. Set to a positive value in order for the triangle to be drawn with rounded corners.
• hideChart: boolean, defaults to false. Set to true in order to draw only the warning sign and suppress the actual chart instead of drawing the warning sign on top of the latter.