Beispiele Content-Plugins

Beispiele für die Nutzung von jquery-progresspiesvg.js zusammen mit den beiliegenden „Content-Plugins“, also Plugins zum Hinzufügen von Inhalten zur Torten- oder Ringgrafik.

Folgende ausgewählte Vorschaubilder von nachfolgend genauer beschriebenen Beispielen können einen ersten Eindruck der Anpassbarkeit und Vielseitigkeit der mitgelieferten Content-Plugins geben:

0 % 5 % 25 %

80 % 100 % 42 % 42 % 42 % 42 % 42 % 42 % 42 %

Content-Plugins: Control Icons (Steuerungs-Symbole)

Um diese Steuerungssymbol-Plugins zu verwenden, binden Sie in Ihrem HTML-Dokument neben jQuery und jquery-progresspiesvg-min.js noch zusätzlich die mitgelieferte Plugin-Datei jquery-progresspiesvg-controlIcons-min.js mit ein!

Steuerungssymbole innerhalb eines Rings mit Standardgröße und gleicher Farbe

$(".pr.icon").each(function(){
    var me = $(this);
    me.progressPie({
        color: "#00d",
        strokeWidth: 1,
        ringWidth: 3,
        contentPlugin: me.hasClass("play") ? "play" : me.hasClass("pause") ? "pause" : "stop"
    });
});

angewendet auf HTML-Elemente der Art:

<span class="pr icon stop">100</span> %

0 % 5 % 25 % 42 % 50 % 65 % 80 % 99 % 100 %

Manuelle Größenwahl und abweichende Farbe fürs Control Icon

Normalerweise wird das Steuerungssymbol in derselben Farbe gezeichnet wie die Ringgrafik, und seine Größe wird automatisch so gewählt, dass das Symbol in den Ring passt, mit noch etwas Abstand zum Ring selbst. Falls Sie das Icon im Verhältnis zum Ring kleiner haleb möchten (vor allem bei größeren Ringgrafiken), können Sie die Option maxSize zu den Content-Plugin-Optionen hinzufügen, um eine maximale Größe für das Symbol festzulegen, die nicht überschritten wird, auch wenn der Ring mehr Platz bietet. Soll das Symbol eine andere Farbe haben als der Ring, fügen Sie die Option color hinzu. Diese Optionsn fürs Content-Plugin werden gebündelt als Objekt, welches wiederum in der Option contentPluginOptions ans progressPie-Plugin übergeben wird:

$(".pr.silverback").progressPie({
    size: 30,
    strokeWidth: 15,
    ringWidth: 2,
    strokeColor: "#ddd",
    color: "#d00",
    valueData: "val",    
    contentPlugin: "pause",
    contentPluginOptions: {
        color: "navy",
        maxSize: 7
    }
});

Kombination mit Torten- statt Ringgrafik

Content-Plugins sind primär dafür gedacht, Inhalte im „leeren Raum“ innerhalb einer Ringgrafik einzufügen, lassen sich jedoch prinzipiell auch mit Tortengrafiken kombinieren. In diesem Fall werden sie als eigene Ebene über die Tortengrafik gezeichnet. Lassen Sie die Standardfarbe unverändert (also identisch zur Tortenfarbe), wird dadurch jedoch der das gefüllte Tortenstück überlappende Inhalt effektiv unsichtbar! Sie sollten in diesem Fall also unbedingt manuell ein Farbschema setzen, in welchem der Inhalt (Steuerungsicon) eine Farbe bekommt, sie sich sowohl vom Hintergrund (meist weiß) als auch von der Torte (z.B. hellgrau) kontrastreich abhebt.

$(".pp.icon").progressPie({
    color: "#ccc",
    valueData: "val",
    contentPlugin: "pause",
    contentPluginOptions: {color: "navy"}
});

Torten:

Verglichen mit den obigen Beispielen fällt Ihnen vielleicht auf, dass hier die Icons etwas größer ausfallen: Während sie in einer Ringgrafik anhand des Innenradius des Rings skaliert werden, basiert die Skalierung im Tortenmodus auf dem Außenradius.

Content-Plugin: checkComplete

Dieses Plugin zeichnet ein Häkchen in die Mitte eines Rings oder auf eine gefüllte Torte, sofern der dargestellte Wert exakt 100% erreicht hat, während Diagramme mit kleineren Werten unverändert bleiben. Im Falle eines Rings wird das Häkchen standardmäßig in derselben Farbe wie der Ring selbst gezeichnet, im Falle einer Tortengrafik dagegen standardmäßig in weiß. Sie können davon abweichend selbst eine Farbe für das Häkchen-Symbol einstellen, ebenso können Sie die Strichstärke (standardmäßig 2 Pixel) verstellen oder die Linienenden (standardmäßig abgerundet):

Styling per CSS

In obigen Beispielen wurde bereits gezeigt, dass Sie optional die Option color zu den contentPluginOptions hinzufügen können, und dass bei fehlen dieser Angabe das Icon in der Farbe des Diagramm-Vordergrundes (Ringfarbe) gezeichnet wird. Von dieser Regel gibt es eine Ausnahme: Im CSS-Modus legt das JavaScript überhaupt keine Diagrammfarbe fest, die das Icon erben könnte. Genau wie die Diagrammfarben muss im CSS-Modus auch die Farbe für das Control-Icon per CSS festgelegt werden (es sei denn, Sie geben die color-Option an).

Zu diesem Zweck, werden die Icon-Shapes mit einer CSS-Klasse versehen, über die sie im CSS-Stylesheet leicht selektiert werden können. Per Default heißt diese Klasse progresspie-control-icon.

Der folgende Beispielcode ist eine Variation des ersten Beispiels, aber er aktiviert den CSS-Modus und lässt dafür die color-Option weg:

$(".pr.icon-css").each(function() {
    var me = $(this);
    me.progressPie({
        mode: $.fn.progressPie.Mode.CSS,
        size: 30,
        strokeWidth: 1,
        ringWidth: 3,
        valueData: "val",
        contentPlugin: me.hasClass("play") ? "play" : me.hasClass("pause") ? "pause" : "stop"
    });
});

Nun können wir die Diagramme selbst sowie die Control-Icons darin per CSS-Regeln gestalten:

.pr.icon-css .progresspie-background {
    stroke: rgba(200, 50, 0, 0.8);
    fill: none;
}
.pr.icon-css .progresspie-foreground {
    stroke: rgba(200, 50, 0, 0.8);
}
.pr.icon-css.solid .progresspie-control-icon {
    fill: rgba(200, 50, 0, 0.8);
}
.pr.icon-css.outline .progresspie-control-icon {
    stroke: navy;
    stroke-width: 1px;
    fill: none;
}

Obiges CSS enthält zwei verschiedene Styling-Beispiele. Dar erste (Klasse solid) legt einfach nur eine Farbe über den fill-Style fest:

<span class="pr icon-css play solid" data-val="45"></span>
<span class="pr icon-css stop solid" data-val="45"></span>
<span class="pr icon-css pause solid" data-val="45"></span>

Die zweite Variante (Klasse outline) entfernt die Füllung und legt statt dessen einen stroke-Stil für den Umriss fest:

<span class="pr icon-css play outline" data-val="45"></span>
<span class="pr icon-css stop outline" data-val="45"></span>
<span class="pr icon-css pause outline" data-val="45"></span>

Eigene CSS-Klassennamen

Falls Sie nicht den Default-CSS-Klassennamen progresspie-control-icon verwenden möchten, können Sie in den contentPluginOptions über die Option cssClass einen eigenen Namen festlegen:

$(".pr.icon-css2").progressPie({
    mode: $.fn.progressPie.Mode.CSS,
    cssClassBackgroundCircle: "piebg",
    cssClassForegroundPie: "piefg",
    size: 30,
    strokeWidth: 1,
    ringWidth: 3,
    valueData: "val",
    contentPlugin: "pause",
    contentPluginOptions: {
        cssClass: "ctrlico"
    }
});

.pr.icon-css2 .piebg {
    stroke: silver;
    fill: none;
}
.pr.icon-css2 .piefg {
    stroke: navy;
}
.pr.icon-css2 .ctrlico {
    fill: maroon;
}

<span class="pr icon-css2" data-val="45"></span>

Content plug-in: checkComplete

This plug-in draws a check mark into a closed ring or onto a full pie, i.e. when the percent value equals 100%. Inside a ring, the default color of the check mark equals the color of the ring, while check marks drawn on top of a full pie are drawn in white by default. You may style the check by choosing your own color, changing the default stroke width (of 2px) or changing the line caps (i.e. from round to rectangular):

$(".pp.check1").setupProgressPie({contentPlugin:"checkComplete"}).progressPie();

0 % 5 % 25 % 42 % 50 % 65 % 80 % 99 % 100 %

$(".pp.check2").setupProgressPie({
    contentPlugin: "checkComplete",
    contentPluginOptions: {
        strokeWidth: 1
    },
    color: function(percent) {
        return percent === 100 ? $.fn.progressPie.colorByPercent(100) : $.fn.progressPie.Mode.GREY.color;
    }
}).progressPie();

0 % 5 % 25 % 42 % 50 % 65 % 80 % 99 % 100 %

$(".pr.check1").setupProgressPie({
    strokeWidth: 1,
    ringWidth: 3,
    mode: $.fn.progressPie.Mode.COLOR,
    contentPlugin:"checkComplete",
}).progressPie();

0 % 5 % 25 % 42 % 50 % 65 % 80 % 99 % 100 %

$(".pr.check2").setupProgressPie({
    sizeFactor: 1.5,
    strokeWidth: 1,
    ringWidth: 3,
    color: "navy",
    verticalAlign: "middle",
    contentPlugin:"checkComplete",
    contentPluginOptions: {
        strokeWidth: 4,
        lineCap: "square",
        color: "#0b0"
    }
}).progressPie();

0 % 5 % 25 % 42 % 50 % 65 % 80 % 99 % 100 %

Neu: Sie können nun optional auch einen farblich gefüllten Hintergrund einstellen:

$(".pr.check3").progressPie({
    sizeFactor: 1.5,
    strokeWidth: 1,
    ringWidth: 3,
    color: "navy",
    verticalAlign: "middle",
    contentPlugin:"checkComplete",
    contentPluginOptions: {
        backgroundColor: "#0a0",
        color: "white"
    }
});

0 % 5 % 25 % 42 % 50 % 65 % 80 % 99 % 100 %

Die backgroundColor-Option (Hinweis: Die Content-Plugin-spezifische „Suboption“ contentPluginOptions.backgroundColor ist nicht zu verwechseln mit der „Root-Option“ backgroundColor der eigentlichen ProgressPie-Function, welche eine Füllfarbe für den gesamten Hintergrundkreis des Diagramms festlegt!) kann kombiniert werden mit der Option fullSize, was bewirkt, dass der gefüllte Hintergrund den gesamten Ring verdeckt, statt in dessen Inneres eingepasst zu werden,…

$(".pr.check4").progressPie({
    sizeFactor: 1.5,
    strokeWidth: 1,
    ringWidth: 3,
    color: "navy",
    verticalAlign: "middle",
    contentPlugin:"checkComplete",
    contentPluginOptions: {
        backgroundColor: "#0a0",
        color: "white",
        fullSize: true
    }
});

0 % 5 % 25 % 42 % 50 % 65 % 80 % 99 % 100 %

… optional auch kombiniert mit der Option inBackground option, so dass das Check-Icon mit seinem gefüllten Hintergrund nicht über das, sondern hinter dem Diagramm gezeichnet wird,…

$(".pr.check4bg").progressPie({
    sizeFactor: 1.5,
    strokeWidth: 1,
    ringWidth: 3,
    color: "navy",
    verticalAlign: "middle",
    contentPlugin:"checkComplete",
    contentPluginOptions: {
        backgroundColor: "#0a0",
        color: "white",
        fullSize: true,
        inBackground: true
    }
});

0 % 5 % 25 % 42 % 50 % 65 % 80 % 99 % 100 %

…oder Sie können die Option margin verwenden, um den Rand zu beeinflussen, der zwischen dem Ring und dem darin eingefassten gefüllten Hintergrundkreis mit dem Check-Icon frei gelassen wird (Standardwert ist 1 Pixel). Die Option iconSizeFactor kann hinzugefügt werden, um das Größenverhältnis zwischen dem Umkreis des Häkchen-Symbols und dem Hintergrundkreis zu beeinflussen, d.h. Sie können damit das Häkchen vergrößern oder verkleinern.

Hinweis: Die beiden Optionen margin und iconSizeFactor werden weiter unten in der Beschreibung zum Error-Icon-Plugin noch genauer erläutert, siehe insb. auch: Details zu Größenverhältnissen und Maßen.

$(".pr.check5").progressPie({
    sizeFactor: 1.5,
    strokeWidth: 1,
    ringWidth: 3,
    color: "navy",
    verticalAlign: "middle",
    contentPlugin:"checkComplete",
    contentPluginOptions: {
        backgroundColor: "#0a0",
        color: "white",
        margin: 2,
        iconSizeFactor: 0.8
    }
});

0 % 5 % 25 % 42 % 50 % 65 % 80 % 99 % 100 %

Animation

$(".pp.checkanim").progressPie({
    contentPlugin: "checkComplete",
    contentPluginOptions: { animate: true }
});
$(".pr.checkanim").progressPie({
    strokeWidth: 1,
    ringWidth: 3,
    scale: 2,
    mode: $.fn.progressPie.Mode.COLOR,
    contentPlugin:"checkComplete",
    contentPluginOptions: {animate: "2s"}
});
$(".pp.checkanimSlow").progressPie({
    scale: 2,
    contentPlugin: "checkComplete",
    contentPluginOptions: {animate: "5s"}
});

Default: 100 %, 2s: 100 %, 5s: 100 %,

Zur Wiederholung der Animationen die Seite neu laden…

Sekundäres Content-Plugin, so lange nicht fertig (100%)

Da das Plugin checkComplete im Normalfall nur für den Wert 100% überhaupt einen Inhalt zur Grafik hinzufügt, bietet es eine Option, für andere Werte (0 bis 99%) statt dessen die Ausgabe an ein anderes Content-Plugin zu delegieren. Zu diesem Zweck können Sie auch innerhalb der contentPluginOptions des checkComplete-Plugins wieder die Option contentPlugin angeben. Und auch dieser können Sie erneut ein Objekt contentPluginOptions zur Seite stellen, dessen Eigenschaften die des umgebenden „Vater-Objekts“ überstimmen: Das sekundäre Plugin „erbt“ zunächst alle contentPluginOptions des checkComplete-Plugins, welche mit den hier optional anzugebenden „Kind-Optionen“ verschmolzen werden.
Im folgenden Beispiel wird das anhand der Farboption color demonstriert: Zunächst wird für das checkComplete-Plugin abweichend von der Farbe der Ringgrafik eine eigene color-Option festgelegt. Diese würde normalerweise auch für das sekundäre Plugin ("pause") übernommen, eine weitere color-Angabe in den Optionen zum sekundären Plugin überstimmt dies jedoch und legt für das Pause-Icon explizit eine dritte Farbe fest.

$(".pr.pauseCheck").progressPie({
    sizeFactor: 1.5,
    strokeWidth: 1,
    ringWidth: 3,
    color: "navy",
    contentPlugin: "checkComplete",
    contentPluginOptions: {
        animate: true,
        strokeWidth: 3,
        color: "green",
        contentPlugin: "pause",
        contentPluginOptions: { color: "maroon" }
    }
});

0 % 5 % 25 % 42 % 50 % 65 % 80 % 99 % 100 %

Styling per CSS

Wie das Control-Icons-Plugin oben unterstützt nun auch das checkComplete-Plugin den CSS-Modus:

Falls der CSS-Modus nicht aktiv ist (mode ≠ $.fn.progressPie.Mode.CSS), hat das Check-Icon per Default eine weiße Farbe, kann aber über die color-Option (in den contentPluginOptions) auch anders aingefärbt werden – wie bereits demonstriert. Ebenso wurde bereits gezeigt, dass über die backgroundColor-Option ein gefüllter Hintergrundkreis hinzugefügtw erden kann.
Im CSS-Modus haben Sie nun die Möglichkeit, das Check-Icon ebenso wie den optionalen Hintergrundkreis per CSS zu formatieren:
- Falls Sie ein Tortendiagramm zeichnen, wird das Häkchen weiterhin standardmäßig in weißer Farbe über die gefüllte Torte gezeichnet. Aber anders als in Nicht-CSS-Modi können Sie im CSS-Modus diese Default-Farbe (weiß) einfach per CSS überstimmen, ohne !important zur Regel hinzufügen zu müssen. (Das wird erreicht, indem die weiße Default-Farbe nicht als Inline-CSS festgelegt wird, was höhere Priorität als externe Styles hätte, sondern als SVG-Stroke-Attribut, welches geringere Priorität als jegliches CSS hat.)
- Falls Sie dagegen ein Ringdiagramm zeichnen, wird keine Default-Farbe per Script festgelegt. In diesem Fall müssen Sie einen stroke-Stil in Ihrem CSS festlegen.
- Ein fill-Style wird übrigens nicht unterstützt – er würde nur das Dreieck ausfüllen, das sich ergibt, wenn man die beiden offenen Enden des Häkchens mit einer Linie verbindet.
- Der Pfad des Häkchen-Icons wird mit der CSS-Klasse progresspie-check versehen, die Sie in CSS-Selektoren verwende können, um Ihre Styles zuzuweisen. Diesen Default-Klassennamen können Sie auch über die Option cssClass innerhalb der contentPluginOptions überstimmen.
- Falls Sie einen Hintergrundkreis einfügen möchten (wie auch schon in vorhergehenden Beispielen gezeigt), und dessen Farbe per CSS festgelegt werden soll statt per backgroundColor-Option, dann geben Sie statt dessen die Option cssClassBackgroundCircle in den contentPluginOptions an. Diese bewirkt ein Einfügen eines Hintergrundkreises, der den Wert dieser Option als CSS-Klasse (class-Attribut) trägt. (Einen Default-Klassennamen für den Hintergrundkreis gibt es nicht, da bei Weglassen dieser Option und der backgroundColor-Option überhaupt kein Hintergrundkreis gezeichnet wird.)

Der folgende Beispielcode demonstriert verschiedene Variationen der gerade genannten Optionen: Eine Torte im CSS-Modus, die die Default-Farbe (Weiß) für das Icon ausnutzt, eine zweite Torte, in der diese Farbe per CSS überstimmt wird. Dann drei Ring-Grafiken, die erste mit und die nächsten ohne Hintergrundkreis. Die letzten beiden legen nicht nur für den Hintergrundkreis, sondern auch für das Icon eigene CSS-Klassennamen fest. Sie unterscheiden sich nur dadurch, dass das letzte Beispiel die fullsize-Option aktiviert.

$(".pp.checkCss").progressPie({
    scale: 2,
    mode: $.fn.progressPie.Mode.CSS,
    valueData: "val",
    contentPlugin: "checkComplete"
});

$(".pr.checkCss.noBg").progressPie({
    scale: 2,
    strokeWidth: 3,
    ringWidth: 3,
    mode: $.fn.progressPie.Mode.CSS,
    valueData: "val",
    contentPlugin: "checkComplete"
});
$(".pr.checkCss.bg").progressPie({
    scale: 2,
    strokeWidth: 3,
    ringWidth: 3,
    mode: $.fn.progressPie.Mode.CSS,
    valueData: "val",
    contentPlugin: "checkComplete",
    contentPluginOptions: {
        cssClass: "tick",
        cssClassBackgroundCircle: "tickbg"
    }
});
$(".pr.checkCss.fs").progressPie({
    scale: 2,
    strokeWidth: 3,
    ringWidth: 3,
    mode: $.fn.progressPie.Mode.CSS,
    valueData: "val",
    contentPlugin: "checkComplete",
    contentPluginOptions: {
        cssClass: "tick",
        cssClassBackgroundCircle: "tickbg",
        fullSize: true
    }
});

.pp.checkCss .progresspie-background {
    fill: none;
}
.pp.checkCss .progresspie-foreground {
    stroke: #aaa;
}
.pp.checkCss.styled .progresspie-check {
    stroke: #0e0;
}
.pr.checkCss .progresspie-background {
    fill: none;
    stroke: silver;
}
.pr.checkCss .progresspie-foreground {
    stroke: #888;
}
.pr.checkCss .progresspie-check {
    stroke: green;
}
.pr.checkCss .tick {
    stroke: white;
}
.pr.checkCss .tickbg {
    fill: green;
}

<span class="pp checkCss defaultWhite" data-val="100"></span>
<span class="pp checkCss styled" data-val="100"></span>
<span class="pr checkCss noBg" data-val="100"></span>
<span class="pr checkCss bg" data-val="100"></span>
<span class="pr checkCss fs" data-val="100"></span>

Content-Plugins: Fehler- und Warnungs-Symbole

Als Ergänzung zum checkComplete-Plugin, das einen erfolgreichen Prozessabschluss visualisiert, können diese Plugins eingesetzt werden, um einen Prozess-Abbruch oder -Abschluss mit Fehlern oder Warnungsmeldungen darzustellen.

Anders als das checkComplete-Plugin, welches darauf ausgelegt ist, bereits vor Prozessstart statisch konfiguriert zu werden und sein Icon einfach bei Erreichen der 100% einzublenden, sind diese Plugins darauf ausgelegt, im Ausnahmefall nachträglich dynamisch „hinzukonfiguriert“ zu werden.
Ein typisches Anwendungsszenario sieht in etwa wie folgt aus:

Zunächst binden Sie die optionale Plugin-Datei jquery-progresspiesvg-errorIcons-min.js mit in Ihre HTML-Datei ein, um diese Plugins nutzen zu können.
Sie würden dann typischerweise eine Fortschrittsanzeige mittels der jQuery-Plugin-Funktion setupProgressPie() einrichten, ggf. gleich mit dem checkComplete-Content-Plugin für die „OK-Anzeige“ im regulären, fehlerfreien Prozessabschluss.
Mittels der parameterlosen progressPie()-Funktion zeichnen Sie die Grafik. Zum Aktualisieren würden Sie dann z.B. per JavaScript den anzuzeigenden Prozentwert aktualisieren und erneut progressPie() aufrufen (siehe Haupt-Beispielseite für ein Beispiel mit dynamischen Updates).
Sollte der Prozess fehlschlagen oder eine Warnung melden, können Sie nachträglich das Setup (die Einrichtung) für diese Grafik aktualisieren und ein Neuzeichnen auslösen:
- Rufen Sie erneut die setupProgressPie({…}) jQuery-Plugin-Funktion auf. Das übergebene Objekt muss lediglich die Optionen aufzählen, die Sie hinzufügen oder überschreiben wollen, alle Einstellungen, die gegenüber der initialen Einrichtung unverändert bleiben sollen, müssen nicht erneut aufgeführt werden.
- Insbesondere fügen Sie also die Option contentPlugin hinzu (oder überschreiben sie), und setzen diese auf "cross", "exclamationMark" oder "warning", um eines deser drei Fehler- oder Warn-Symbole hinzuzufügen.
- Fügen Sie i.d.R. außerdem die Option contentPluginOptions hinzu, um das gewählte Content-Plugin zu konfigurieren.
- Abschließend rufen Sie wieder progressPie() auf, um die Anzeige zu aktualisieren.

Die Datei jquery-progresspiesvg-errorIcons-min.js umfasst derzeit drei Content-Plugins: cross zeichnet ein X-Symbol (üblicherweise benutzt, um einen Fehler zu melden), exclamationMark zeichnet ein einfaches Ausrufezeichen (!) und warning zeichnet ein dreieckiges Warnschild mit Ausrufezeichen.

Alle drei Plugins werden im Folgenden demonstriert, und zwar in Kombination mit vorhergehenden Beispielen des checkComplete Plugins. D.h. die folgenden Beispiel-Listings zeigen wirklich nur die Einstellungen, die dem Setup des ursprünglichen checkComplete-Beispiels hinzugefügt werden sollen, also kein komplettes Setup für die gesamte Grafik. Werfen Sie einen Blick auf das jeweilige Originalsetup den den Klassen pp check1, pr check1 and pr check2.

cross und exclamationMark

Kombination mit Tortengrafiken

Kombination des cross- und des exclamationMark-Plugins mit dem vorhergehenden Beispiel zu Klasse .pp.check1:

$(".pp.cross1").setupProgressPie({
    contentPlugin: "cross"
}).progressPie();
$(".pp.excla1").setupProgressPie({
    contentPlugin: "exclamationMark"
}).progressPie();

angewandt auf:

<span class="pp check1">0</span> %
<span class="pp check1">5</span> %
<span class="pp check1">25</span> %
<span class="pp check1 cross1">42</span> %
<span class="pp check1 excla1">42</span> %

0 % 5 % 25 % 42 % 42 %

Wie Sie sehen, wird im Standarfall (Default-Optionen) die gesamte Torte überdeckt von einem gefüllten Kreis, auf welchen das X- oder !-Symbol gezeichnet wird. Standardfarbe für das Fehlericon ist rot, für das Warn-Icon gelblich. Durch Angabe von contentPluginOptions können Sie die Farben, Stichstärke, Linienenden etc. aber modifizieren.

Möchten Sie z.B. nicht, dass die Fortschrittsanzeige komplett verdeckt wird, sondern dass der Fortschritt (Wert zum Fehlerzeitpunkt) weiterhin erkennbar bleibt, haben Sie verschiedene Mögichkeiten:

Sie können den gefüllten Hintergrund komplett abschalten und einfach nur ein farbiges Symbol auf doe Torte zeichnen.
Sie können für die Hintergrundfarbe einen rgba-Wert mit Alpha-Kanal für eine halbtransparente Hintergrundfüllung angeben, so dass die Torte noch durchscheint.
Sie können über die margin-Option einen freibleibenden Rand um das Fehlersymbol einstellen, so dass dieses kleiner wird und der Außenrand der Torte sichtbar bleibt.
Oder Sie können per inBackground-Option das Fehler-Icon als Hintergrund hinter die Torte legen. In diesem Fall wird empfohlen, für die Torte eine halbtransparente Vordergrundfarbe zu verwenden, so dass sie (insbesondere für größere Prozentwerte) das Fehlersymbol nicht großteils verdeckt, sondern es immer durchscheint.

Die folgenden Beispiele demonstrieren diese vier Möglichkeiten:

$(".pp.cross2").setupProgressPie({
    contentPlugin: "cross",
    contentPluginOptions: {
        withBackground: false,
        iconColor: "red",
        strokeWidth: 3,
        lineCap: "square"
    }
}).progressPie();
$(".pp.cross3").setupProgressPie({
    contentPlugin: "cross",
    contentPluginOptions: {
        backgroundColor: "rgba(255,0,0,0.5)"
    }
}).progressPie();
$(".pp.cross4").setupProgressPie({
    contentPlugin: "cross",
    contentPluginOptions: {
        margin: 3,
        strokeWidth: 1,
        iconSizeFactor: 0.7
    }
}).progressPie();
$(".pp.crossbg").setupProgressPie({
    color: "rgba(0,0,0,0.4)",
    contentPlugin: "cross",
    contentPluginOptions: {
        inBackground: true
    }
}).progressPie();
$(".pp.excla2").setupProgressPie({
    contentPlugin: "exclamationMark",
    contentPluginOptions: {
        strokeWidth: 1
    }
}).progressPie();
$(".pp.excla3").setupProgressPie({
    contentPlugin: "exclamationMark",
    contentPluginOptions: {
        backgroundColor: null,
        iconColor: "red",
        strokeWidth: 3
    }
}).progressPie();
$(".pp.excla4").setupProgressPie({
    contentPlugin: "exclamationMark",
    contentPluginOptions: {
        backgroundColor: "rgba(255,230,0,0.6)",
        iconColor: "black"
    }
}).progressPie();
$(".pp.exclabg").setupProgressPie({
    color: "rgba(0,0,0,0.2)",
    contentPlugin: "exclamationMark",
    contentPluginOptions: {
        inBackground: true
    }
}).progressPie();

42 % 42 % 42 % 42 % 42 % 42 % 42 % 42 %

Kombination mit Ringgrafiken

Wenn Sie diese Content-Plugins mit einem Fortschritts-Ring statt einer gefüllten Torte verwenden, werden die Fehler-/Warnungsicons standardmäßig nicht über das gesamte Diagramm gelegt, sondern im freien Innenteil innerhalb des Rings angeordnet, so dass letzterer vollständig sichtbar bleibt:

$(".pr.cross1").setupProgressPie({
    contentPlugin: "cross",
    contentPluginOptions: {}
}).progressPie();
$(".pr.cross2").setupProgressPie({
    contentPlugin: "cross",
    contentPluginOptions: {
        backgroundColor: null,
        iconColor: "red"
    }
}).progressPie();
$(".pr.excla1").setupProgressPie({
    contentPlugin: "exclamationMark",
    contentPluginOptions: {}
}).progressPie();
$(".pr.excla2").setupProgressPie({
    contentPlugin: "exclamationMark",
    contentPluginOptions: {
        backgroundColor: null,
        iconColor: "red"
    }
}).progressPie();

angewandt auf:

<span class="pr check1">0</span> %
<span class="pr check1">5</span> %
<span class="pr check1">25</span> %
<span class="pr check1 cross1">42</span> %
<span class="pr check1 cross2">42</span> %
<span class="pr check1 excla1">42</span> %
<span class="pr check1 excla2">42</span> %

0 % 5 % 25 % 42 % 42 % 42 % 42 %

Alternativ können Sie auch hier das Icon in voller Größe zeichnen lassen (wie es der Standard bei Torten ist), indem Sie die fullSize-Option auf true setzen. Außerdem demonstrieren die folgenden Beispiele eine SMIL-Animation (vgl. Animations-Beispiele des checkComplete-Plugins). (Seite erneut laden, um die Animationen neu abzuspielen. SMIL-Animationen funktionieren nicht im IE oder Edge-Browser.)

$(".pr.crossFW").setupProgressPie({
    contentPlugin: "cross",
    contentPluginOptions: {
        fullSize: true,
        animate: true
    }
}).progressPie();
$(".pr.crossFsBg").setupProgressPie({
    color: "navy",
    contentPlugin: "cross",
    contentPluginOptions: {
        fullSize: true,
        inBackground: true,
        animate: true,
        iconSizeFactor: 0.5
    }
}).progressPie();
$(".pr.exclaFs").setupProgressPie({
    contentPlugin: "exclamationMark",
    contentPluginOptions: {
        fullSize: true,
        strokeWidth: 4,
        animate: true
    }
}).progressPie();
$(".pr.exclaFs2").setupProgressPie({
    contentPlugin: "exclamationMark",
    contentPluginOptions: {
        fullSize: true,
        backgroundColor: "#700",
        lineCap: "square",
        strokeWidth: 3,
        animate: "2s"
    }
}).progressPie();
$(".pr.exclaFsBg").setupProgressPie({
    color: "navy",
    contentPlugin: "exclamationMark",
    contentPluginOptions: {
        fullSize: true,
        inBackground: true,
        animate: true,
        iconSizeFactor: 0.5
    }
}).progressPie();

42 % 42 % 42 % 42 % 42 %

Beachten Sie, dass das Ausrufezeichen zu einem einfachen senkrechten Strich reduziert wird, wenn das Verhältnis von Icongröße (Höhe) zu Strichbreite zu klein wird, so dass sich in dieser Strichbreite kein gut proportioniertes Ausrufezeichen mehr zeichnen ließe.

Lassen Sie dagegen die Standardeinstellung fullSize === false, so wird, wie gesagt, das Symbol im Inneren des Rings gezeichnet – und zwar standardmäßig mit einem freien Rand/Abstand zwischen Ring und Symbol (gefülltem Hintergrund) von 1 Pixel. Auch diesen Rand können Sie konfigurieren, und zwar mit der margin-Option:

$(".pr.crossMargin0").setupProgressPie({
    contentPlugin: "cross",
    contentPluginOptions: {
        margin: 0
    }
}).progressPie();
$(".pr.crossMargin3").setupProgressPie({
    contentPlugin: "cross",
    contentPluginOptions: {
        margin: 3,
        strokeWidth: 1
    }
}).progressPie();

42 % 42 %

Abschließend wiederholen wir alle oben genannten Beispiele noch einmal, nur dieses Mal kombiniert mit einer anderen Basiskonfiguration .pr.check2, welche größere Ringgrafiken zeichnet (s.o.):

0 % 5 % 25 % 42 % 42 % 42 % 42 % 42 % 42 % 42 % 42 % 42 % 42 % 42 %

Details zu Größenverhältnissen und Maßen

Betrachten wir zum Ende dieses Abschnitts noch einmal genauer die Kreisgrößen/Radien: Die gesamte Torten- bzw. Ringgrafik ist kreisförmig und hat somit offensichtlich einen Gesamtradius (totalRadius). Es wurde bereits demonstriert, dass im Tortenmodus ein Fehler-/Warnungssymbol diesen Gesamtradius – ggf. abzüglich eines Randes (margin, standardmäßig = 0) – füllt, während es im Ringmodus ins Innere des Rings eingepasst wird (es sei denn, die fullSize-Option wurde gesetzt). Im letzteren Fall (Ringmodus, !fullSize) ist der Radius des Fehler-/Warnsymbols der Gesamtradius abzüglich der Ringbreite (ringWidth) abzüglich des Randes (margin, standardmäßig = 1). Dieser Symbol-Radius sei im Folgenden kurz mit r bezeichnet.

measurements

Obige Abbildung zeigt die verschiedenen Werte ringWidth (aus den progressPie-Plugin-Optionen), margin (aus den contentPluginOptions) und den verbleibenden Symbolradius r ebenso wie den Gesamtradius (totalRadius) und weitere abgeleitete Werte, auf die wir im Folgenden noch zu sprechen kommen. (Abgeleitete Werte, d.h. Werte, die Sie nicht direkt in den Optionen angeben können, sondern die sich aus anderen Optionen errechnen, sind in der Abbildung kursiv gesetzt.)

So lange Sie die Hintergrundfüllung nicht abschalten (also backgroundColor nicht auf null setzen), wird nun also ein mit der Hintergrundfarbe gefüllter Kreis mit Radius r in die Mitte des Rings gezeichnet. Das eigentliche Icon (Kreuz oder Ausrufezeichen) wiederum wird auf diesen Hintergrund gezeichnet, und zwar in einer Größe, die genau in einen noch kleineren Kreis eingepasst wird (vgl. grau gestrichelte Kreislinie in obiger Abildung). Dabei bleibt ein Innenrand (padding) zwischen dem Umkreis des Symbols und dem gefüllten Hintergrundkreis frei.

Der Radius dieses inneren Symbolumkreises (grau gestrichelt) ist r * iconSizeFactor. iconSizeFactor ist dabei eine Option, die Sie in den contentPluginOptions anpassen können. Der Defaultwert ist 0.6. Dabei handelt es sich um einen Faktor, der angibt, wie groß das eigentliche Icon (bzw. dessen Umkreis) im Verhältnis zum Gesamtsymbol (Hintergrundkreis) sein soll. Der Wert 0.6 beudetet, dass der Umkreis des eigentlichen Symbols 60% des Hintergrundkreises einnimmt, d.h. der Radius des Umkreises ist 0.6 * r, der Innenrand (padding) beträgt demnach 0.4 * r.
Beachten Sie, dass der Innenrand (padding) nicht absolut als Option angegeben werden kann, sondern nur indirekt und relativ über die Option iconSizeFactor. Je größer dieser Wert, desto kleiner das Padding. Falls Sie iconSizeFactor = 1.0 setzen (Maximum), ist das Padding = 0 und das eigentliche Icon (X oder !) wird den Rand des Hintergrundkreises berühren:

Falls Sie backgroundColor = null setzen, so wird die Option margin ignoriert! Das Symbol (X oder !) wird dann direkt ohne gefüllten Hintergrundkreis auf die Torte bzw. den Ring gezeichnet, und zwar in einen Kreis mit Radius totalRadius im Tortenmodus oder bei fullSize == true, bzw. ins Ring-Innere (Kreis mit Radius totalRadius - ringWidth). Wie gesagt entfällt der Außenrand margin mangels des gefüllten Hintergrunds, aber der Innenrand (padding) wird nach wie vor angewandt. D.h. im Torten- oder FullSize-Modus nimmt das X- oder !-Symbol den Anteil iconSizeFactor des Gesamtdiagramms ein, andernfalls den Anteil iconSizeFactor des leeren Ring-Inneren.

Im folgenden Beispiel fügen wir ein Fehler-Icon (cross) in eine deutlich größere Ring-Grafik ein als in den vorhergehenden Beispielen. (Dazu bedienen wir uns eines der im nachfolgenden Abschnitt erst eingeführten Beispiele für Wert-Anzeige im Ring.) Nehmen wir an, wir wollen aber das eigentliche X-Symbol nicht ganz so groß werden lassen, sondern es soll im Verhältnis zur Hintergrundfläche etwas kleiner werden. Wir wählen einen iconSizeFactor von 0.5, d.h. wir haben 50% Symbolgröße und somit auch 50% Innenrand (Padding). Weiterhin vergrößern wir auch den Außenrand (margin) zwischen Ring und gefülltem Hintergrund auf 3 Pixel:

$(".percent.smallerCross").setupProgressPie({
    contentPlugin: "cross",
    contentPluginOptions: {
        iconSizeFactor: 0.5,
        strokeWidth: 4,
        margin: 3
    }
}).progressPie();

applied to

<span class="percent default smallerCross" data-val="45"></span>

Styling per CSS

Ähnlich zum checkComplete-Plugin unterstützen auch diese Warnung- und Fehlericon-Plugins nun den CSS-Modus:

Ist der CSS-Modus nicht aktiv (mode ≠ $.fn.progressPie.Mode.CSS), werden die Farben für Icon und Hintergrundkreis über oben vorgestellte Optionen festgelegt und als Inline-Styles ins SVG mit aufgenommen, wodurch sie höhere Priorität als externe CSS-Styles haben und höchstens per !important-Regeln überstimmt werden könnten.
Im CSS-Modus dagegen können Sie diese einfach per CSS formatieren: Farben für Icon und ggf. Hintergrundkreis (sofern vorhanden) werden zwar nach wie vor ins SVG eingefügt (ggf. die Default-Farben, wenn Sie keine Farb-Optionen im Script festlegen), allerdings als SVG-Attribute, die sich durch CSS einfach überstimmen lassen.
In jedem Fall werden class-Attribute zu Icon und Hintergrundkreis (sofern vorhanden, abhängig von der Option withBackground) hinzugefügt, um diese in CSS-Stylesheets einfach selektieren zu können. Die Default-Klassennamen lauten progresspie-erroricon bzw. progresspie-erroricon-background, sie können überstimmt werden über Optionen cssClass bzw. cssClassBackgroundCircle in den contentPluginOptions.

Beispiele:

$(".pp.crossCss").setupProgressPie({
    mode: $.fn.progressPie.Mode.CSS,
    valueData: "val",
    contentPlugin: "cross",
    contentPluginOptions: {
        strokeWidth: 3,
        iconSizeFactor: 0.7
    }
}).progressPie();
$(".pr.crossCss.bg").setupProgressPie({
    mode: $.fn.progressPie.Mode.CSS,
    strokeWidth: 1,
    ringWidth: 3,
    valueData: "val",
    contentPlugin: "cross",
    contentPluginOptions: {
        margin: 1,
        iconSizeFactor: 0.8,
        cssClass: "crossFg",
        cssClassBackgroundCircle: "crossBg"
    }
}).progressPie();
$(".pr.crossCss.noBg").setupProgressPie({
    mode: $.fn.progressPie.Mode.CSS,
    strokeWidth: 1,
    ringWidth: 3,
    valueData: "val",
    contentPlugin: "cross",
    contentPluginOptions: {
        iconSizeFactor: 0.8,
        withBackground: false
    }
}).progressPie();
$(".pr.exclaCSS").setupProgressPie({
    mode: $.fn.progressPie.Mode.CSS,
    strokeWidth: 2,
    ringWidth: 2,
    valueData: "val",
    contentPlugin: "exclamationMark",
    contentPluginOptions: {
        fullSize: true,
        animate: true
    }
}).progressPie();

.pp.crossCss .progresspie-background {
    fill: none;
}
.pp.crossCss .progresspie-foreground {
    stroke: #aaa;
}
.pp.crossCss .progresspie-erroricon-background {
    opacity: 0.7;
}
.pr.crossCss .progresspie-background {
    fill: none;
    stroke: navy;
}
.pr.crossCss .progresspie-background {
    fill: none;
    stroke: navy;
}
.pr.crossCss .progresspie-foreground {
    stroke: navy;
}
.pr.crossCss .crossFg {
    stroke: red;
}
.pr.crossCss .crossBg {
    fill: silver;
    stroke: none;
}
.pr.crossCss.noBg .progresspie-erroricon {
    stroke-linecap: square;
    stroke-width: 3;
    stroke: rgb(150, 0, 0);
}
.pr.exclaCSS .progresspie-background {
    fill: #ddd;
    stroke: #ccc;
}
.pr.exclaCSS .progresspie-foreground {
    stroke: navy;
}
.pr.exclaCSS .progresspie-erroricon-background {
    fill: rgba(255, 255, 0, 0.6);
}
.pr.exclaCSS .progresspie-erroricon {
    stroke: #a00;
    fill: #a00;
}

<span class="pp crossCss" data-val="50"></span>
<span class="pr crossCss bg" data-val="50"></span>
<span class="pr crossCss noBg" data-val="50"></span>
<span class="pr exclaCSS" data-val="50"></span>

Das erste Beispiel demonstriert, was passiert, wenn trotz CSS-Modus keine Farb-Styles im CSS angegeben werden: Die Default-Farben werden verwendet (weißes X auf rotem Hintergrundkreis). Aber auch wenn das Beispiel keine Farbe festlegt, so zeigt es doch andere Styling-Möglichkeiten: Es reduziert die Opazität des Hintergrundkreises, so dass das Tortendiagramm dahinter noch leicht durchscheint. Das demonstriert auch, dass dieses Tortendiagramm, obwohl eigentlich vom Hintergrundkreis des Fehler-Icons vollständig verdeckt, im CSS-Modus dennoch immer gezeichnet wird. (Im Standard-Modus geht das Plug-in davon aus, dass die Torte ohnehin vollständig unsichtbar bleibt und zeichnet sie daher gar nicht erst.)

Das zweite Beispiel demonstriert eine Kombination aus Ring-Diagramm und CSS-Formatierung, außerdem legt es eigene CSS-Klassennamen für Icon und Hintergrundkreis fest.

Das dritte Beispiel ist ähnlich zum ersten, aber entfernt explizit den Hintergrundkreis. Außerdem verwendet es den Default-Klassennamen für das Icon.

Das vierte Beispiel zeigt CSS-Styling für das Ausrufezeichen-Plugin. Beachten Sie bei diesem Plugin, dass das Ausrufezeichen aus zwei SVG-Formen besteht: Die senkrechte Linie und ein Kreis darunter für den Punkt. Wenn Sie diese per CSS formatieren wollen, beachten Sie die entsprechenden Unterschiede zwischen Linie und Kreis: Eine Linie kann nicht gefüllt werden, sondern nur mit stroke-Eigenschaften gestaltet werden. Der Kreis dagegen sollte normalerweise ausschließlich gefüllt werden (fill). In diesem Beispiel wird für Klasse .progresspie-erroricon und somit für beide Formen sowohl eine fill- als auch eine stroke-Farbe festgelegt. Die Fill-Farbe für die Linie hat keinen Effekt, sie wirkt sich nur auf den Kreis aus. Die Stroke-Farbe für den Kreisumriss dagegen könnte (da normalerweise kein Stroke festgelegt ist) prinzipiell den Kreisumfang vergrößern. Damit das nicht passiert, ist im SVG die stroke-width für den Kreis auf den Defaultwert von 0 eingestellt.
Prinzipiell könnten Sie für den Kreis die Füllung abschalten, und die stroke-width> auf einen Wert > 0 (z.B. 0.5) einstellen, um nur einen ungefüllten Kreisumriss zu zeichnen. Empfehlen würde ich das aber nicht.

warning

Bevorzugen Sie als Warnsymbol an Stelle eines simplen Ausrufezeichens in einem Kreis ein dreieckiges Warnschild, so verwenden Sie statt exclamationMark das Content-Plugin warning. Es verhält sich ganz ähnlich zu ersterem, zeichnet aber keinen kreisförmigen Hintergrund, sondern einen dreieckigen über die Tortengrafik bzw. in den Ring:

$(".pp.warn1").setupProgressPie({
    contentPlugin: "warning"
}).progressPie();

$(".pr.warn1").setupProgressPie({
    contentPlugin: "warning",
    contentPluginOptions: {
        strokeWidth: 1
    }
}).progressPie();

42 % 42 % 42 %

Neben oben bereits vorgestellten Plugin-Optionen wie iconColor, backgroundColor oder strokeWidth führt dieses Plugin eine neue Option ein, mit der Sie wahlweise die Ecken des Dreiecks abrunden können: borderRadius. Der Standardwert dieser Option ist 0 (keine abgerundeten Ecken). Positive Werte (1, 2, 3…) sorgen für abgerundete Ecken, wobei der Wert den Radius des Kreises angibt, dessen Kreisbogenabschnitt die abgerundete Ecke darstellt. Mit größeren Werten werden nicht nur die Ecken „runder“, sondern auch das Dreieck und Ausrufezeichen etwas größer: Ein reines Beschneiden der Ecken würde ja einen Abstand zwischen dem Icon-Umkreis (vgl. Radius r in obiger Bemaßungsskizze) und dem Dreieck erzeugen, und um das zu verhindern, wird das Dreieck so weit vergrößert, bis die abgerundeten Ecken wieder genau den Umkreis berühren.

$(".pr.warn2").setupProgressPie({
    contentPlugin: "warning",
    contentPluginOptions: {
        borderRadius: 2,
        backgroundColor: "red"
    }
}).progressPie();

42 % 42 %

Alle anderen Plugin-Optionen von cross and exclamationMark sind ebenfalls auf dieses Plugin anwendbar. So können Sie beispielsweise für eine Ringgrafik die fullSize-Option auf true setzen. Allerdings wird das Warnschild dann zwar mit seinen Ecken den Ring überlappen, den Ring jedoch (anders als die beiden kreisförmigen Plugins) nicht den gesamten Ring verdecken:

$(".pr.warnFW").setupProgressPie({
    contentPlugin: "warning",
    contentPluginOptions: {
        fullSize: true, 
        borderRadius:1
    }
}).progressPie();

42 % 42 %

Wie bei den vorangehend betrachteten Plugins können Sie auch hier das Warndreieck optional im Hintergrund zeichnen lassen:

$(".pr.warnFsBg").setupProgressPie({
    contentPlugin: "warning",
    contentPluginOptions: {
        fullSize: true, 
        inBackground: true,
        borderRadius:1
    }
}).progressPie();

42 % 42 %

Im Unterschied zu den ggf. kreisförmig gefüllten Icons exclamationMark und cross kann dieses dreieckige Symbol warning niemals komplett das Torten-/Ringdiagramm verdecken. Normalerweise wird das also immer im Hintergrund sichtbar sein.
Möchten Sie dagegen bei Anzeige der Warnung die bisherige Fortschrittsanzeige komplett durch das Warnsymbol ersetzen (und möchten Sie dazu wirklich dieses dreieckige warning-Symbol und nicht einfach exclamationMark verwenden), dann können Sie die speziell von diesem Content-Plugin zusätzlich unterstützte Option hideChart verwenden: Setzen Sie diese auf true, und das eigentliche Kreisdiagramm im Hintergrund wird gar nicht erst gezeichnet:

$(".pr.warnOnly").setupProgressPie({
    contentPlugin: "warning",
    contentPluginOptions: {
        fullSize: true, 
        borderRadius: 2,
        hideChart: true
    }
}).progressPie();

42 % 42 %

Styling per CSS

Das Styling per CSS verläuft beim Warning-Plugin weitestgehend analog zu dem bei den anderen "error icons" (cross und exclamationMark). Ein Beispiel:

$(".pr.warnOnlyCss").setupProgressPie({
    size: 30,
    contentPlugin: "warning",
    mode: $.fn.progressPie.Mode.CSS,
    contentPluginOptions: {
        fullSize: true, 
        borderRadius: 2,
        hideChart: true
    }
}).progressPie();

.pr.warnOnlyCss svg {
    vertical-align: middle;
}
.pr.warnOnlyCss .progresspie-erroricon-background {
    stroke: #ddd;
    fill: #ddd;
}
.pr.warnOnlyCss .progresspie-erroricon {
    stroke: red;
    fill: red;
}

42 %

Kombinierendes Beispiel: Aktivitätsanzeiger ohne Fortschrittsmessung mit Zustandsrückmeldung nach Abschluss

Stellen Sie sich vor, Ihre Nutzer können einen Prozess anstoßen, und während der läuft, soll ihnen, da der Prozess über keine Fortschrittsmessung verfügt, einfach eine rotierende Warte-/Aktivitätsanzeige präsentiert werden. Aber nach Abschluss der Wartezeit soll das Jobergebnis (Erfolg, Fehler oder Warnung) als Icon angezeigt werden.

Das folgende Beispiel zeigt einen Realisierungsvorschlag für dieses Szenario. Zwei Punkte möchte ich dabei besonders erwähnen:

Da kein Fortschritt in Prozent gemessen wird, speichert dieses Beispiel als Rohwert im "Data" des Diagramms einfach einen den Zustand identifizierenden String: RUNNING, SUCCESS, ERROR oder WARNING. Über die Optionen valueAdapter und valueByRawValue werden Funktionen definiert, die jeweils einen dieser Strings als Rohwerte entgegennehmen und auf einen Prozentwert bzw. spezifische Optionsobjekte abbilden. Der vom Value-Adapter berechnete Prozentwert für RUNNING definiert dabei die Größe der „Lücke“ im rotierenden Ring. Der dem Wert SUCCESS zugeordnete Wert von 100% wiederum stellt sicher, dass das Content-Plugin checkComplete auch wirklich das Häkchen-Icon zeigt. Für die anderen Werte ist der berechnete Prozentwert irrelevant.
Über CSS-Transitions nach einem JavaScript-Timeout werden Ein- und Ausblendeffekte für das Diagramm realisiert.

var busyExampleCommonContentPluginOptions = {
    fullSize: true,
    animate: true
}
$("#busyExample").css("opacity", 0).setupProgressPie({
    valueData: "state",
    ringWidth: 2,
    strokeWidth: 0,
    verticalAlign: "middle",
    valueAdapter: function(state) {
        return  state === 'RUNNING' ? 80 : 100;
    },
    optionsByRawValue: function(state) {
        switch (state) {
            case 'RUNNING': return {
                    rotation: true
                };
            case 'SUCCESS': return {
                    contentPlugin: "checkComplete",
                    contentPluginOptions: $.extend({}, busyExampleCommonContentPluginOptions, {
                        color: "white",
                        backgroundColor: "#0a0"
                    })
                };
            case 'ERROR': return {
                    contentPlugin: "cross",
                    contentPluginOptions: busyExampleCommonContentPluginOptions
                };
            case 'WARNING': return {
                    contentPlugin: "warning",
                    contentPluginOptions: $.extend({}, busyExampleCommonContentPluginOptions, {
                        hideChart: true,
                        borderRadius: 3
                    })
                };
        }
    }
});

$(".btnBusyExample").click(function() {
    $(".btnBusyExample").prop("disabled", true);
    $("#busyExample").data("state", "RUNNING").css("opacity", 1).progressPie();
    var finalState = $(this).data("finalState");
    setTimeout(function() {
        $("#busyExample").data("state", finalState).progressPie();
        setTimeout(function() {
            $("#busyExample").css("opacity", 0);
            $(".btnBusyExample").prop("disabled", false);
        }, 5000);
    }, 3000);
});

#busyExample {
    transition: opacity 2s;
}

<p>
    <button class="btnBusyExample" data-final-state="SUCCESS">trigger demo -&gt; success</button>
    <button class="btnBusyExample" data-final-state="ERROR">trigger demo -&gt; error</button>
    <button class="btnBusyExample" data-final-state="WARNING">trigger demo -&gt; warning</button>
    <span id="busyExample"></span>
</p>

Content-Plugin: Wertanzeige im Ring

Um diese Plugins zu verwenden, binden Sie in Ihrem HTML-Dokument neben jQuery und jquery-progresspiesvg-min.js noch zusätzlich die mitgelieferte Plugin-Datei jquery-progresspiesvg-valueDisplay-min.js mit ein!

Default: Prozentwerte ind Standard-Schriftgröße mit Beschriftung "%" in zweiter Zeile

$(".percent.default:not(.singleLine)").setupProgressPie({
    verticalAlign: "middle",
    valueData: "val",
    size: 50,
    ringWidth: 3,
    strokeWidth: 3,
    strokeColor: "#ddd",
    color: "navy",
    contentPlugin: "percent"
}).progressPie();

Standardschrift des Dokuments: Helvetica:

Die Schriftart wird nicht als Teil der SVG-Grafik festgelegt, womit effektiv die Schrift des sie umgebenden Absatzes des HTML-Dokuments zum Einsatz kommt.

Kleiner (`size: 30`):

Ein dickerer Ring mit abgerundeten Enden und anderer Farbe für Ring und Inhalt:

$(".percent.rounded").progressPie({
    verticalAlign: "middle",
    valueData: "val",
    size: 50,
    ringWidth: 7,
    ringEndsRounded: true,
    strokeWidth: 7,
    strokeColor: "#eee",
    color: "#a00",
    contentPlugin: "percent",
    contentPluginOptions: {
        color: "navy"
    }
});

Dies demonstriert außerdem, dass die Schriftgröße sich am Innenradius der Ringgrafik orientiert. Ein dickerer Ring bei gleichem Außenradius / gleicher Gesamtgröße der Grafik lässt weniger Raum für Inhalt und bewirkt somit eine kleinere Schriftgröße.

Einzeiliger Modus

$(".percent.singleLine.default").progressPie({
    verticalAlign: "middle",
    valueData: "val",
    size: 50,
    ringWidth: 3,
    strokeWidth: 3,
    strokeColor: "#ddd",
    color: "navy",
    contentPlugin: "percent",
    contentPluginOptions: {
        singleLine: true
    }
});

Manipulierte Schriftgrößen: Einheit "%" größer, Zahl dafür kleiner

$(".percent.singleLine.resized").progressPie({
    verticalAlign: "middle",
    valueData: "val",
    size: 50,
    ringWidth: 3,
    strokeWidth: 3,
    strokeColor: "#ddd",
    color: "navy",
    contentPlugin: "percent",
    contentPluginOptions: {
        singleLine: true,
        fontSizeFactor: 0.8,
        unitFontSizeFactor: 0.5
    }
});

Anzeigen des Rohwertes statt des Prozentwertes

Falls Ihr Dokument keine Prozentwerte direkt enthält, sondern Rohwerte in anderer Einheit, die durch eine Wertadapter-Funktion (valueAdapter) dynamisch in Prozentwerte umgerechnet werden (siehe Dokumentation oder Beispiele für progressPieSVG), können Sie auch statt der daraus errechneten Prozentwerte direkt Ihre originalen Rohwerte im Innern der Grafik anzeigen lassen.

Die folgenden Beispiele verwenden einen Rohwert in Sekunden (1..60). Das erste Beispiel legt dazu eine Einheitsbeschriftung "sec." fest, während das zweite Beispiel nur die Zahl ganz ohne Einheit anzeigt. Beide Beispiele erhöhen die Schriftgröße ein wenig, da nur zweistellige Zahlen verwendet werden, die etwas weniger Breite beanspruchen als bis zu dreistellige Prozentwerte.

$(".secs.withUnit").progressPie({
    valueData: "val",
    valueAdapter: function(s) {return parseInt(s) * 10 / 6;},
    size: 50,
    ringWidth: 5,
    strokeWidth: 5,
    strokeColor: "#ddd",
    strokeDashes: {
        count: 12,
        length: 2,
        centered: true,
        inverted: true
    },
    mode: $.fn.progressPie.Mode.COLOR,
    contentPlugin: "rawValue",
    contentPluginOptions: {
        unit: "sec.",
        fontSizeFactor: 1.2
    }
});

$(".secs.noUnit").progressPie({
    valueData: "val",
    valueAdapter: function(s) {return parseInt(s) * 10 / 6;},
    size: 50,
    ringWidth: 5,
    strokeWidth: 5,
    strokeColor: "#ddd",
    strokeDashes: {
        count: 12,
        length: 2,
        centered: true
    },
    mode: $.fn.progressPie.Mode.COLOR,
    contentPlugin: "rawValue",
    contentPluginOptions: {
        fontSizeFactor: 1.4
    }
});

Styling per CSS

Wie alle zuvor vorgestellten Content-Plugins unterstützt auch dieses "valueDisplay"-Plugin nun den CSS-Modus:

Zunächst einmal wird der Textinhalt mit CSS-Klassen (name-Attribut) versehen, und zwar immer, unabhängig vom CSS-Modus:
- Der gesamte Textinhalt (angezeigter Wert sowie optional die Einheit) wird als ein einziges text-Element realisiert.
- Dessen Klasse ist standardmäßig progresspie-valuedisplay.
- Über die Option cssClass in den contentPluginOptions kann alternativ eine eigene Klassenbezeichnung festgelegt werden.
- Die optionale Anzeige der Einheit (z.B: "%") ist ein Kindelement des Textes (vom Typ tspan). Dieses hat zusätzlich eine eigene CSS-Klasse, standardmäßig: progresspie-unit.
- Über die Option cssClassUnit kann auch dafür ein eigener Klassenname gewählt werden.
- Als Kindelement des gesamten Textelements erbt die Einheitenanzeige aber auch die Stile der Wertanzeige, d.h. also alle Regeln zu .progresspie-valuedisplay wirken sich zunächst sowohl auf den angezeigten Wert als auch auf die angezeigte Einheit aus. Über die Klasse .progresspie-unit lassen sich für die Einheitenanzeige aber Abweichungen festlegen (z.B. wenn die Einheit in einer anderen Schriftart oder Farbe erscheinen soll).
In jedem Nicht-CSS-Modus wird ein fill-Stil zum SVG hinzugefügt, der die Schriftfarbe festlegt. Im CSS-Modus geschieht dies nicht, die Schrift ist also per Default schwarz, sofern Ihr CSS keine Farbe festlegt.

Die folgenden beiden Beispiele demonstrieren die Anwendung des CSS-Modus. Das erste legt überhaupt keine contentPluginOptions fest, das zweite demonstriert benutzergewählte Klassennamen. Während das zweite CSS ausschließlich zur Einfärbung verwendet – und zwar in unterschiedlichen Farben für Wert und Einheit –, demonstriert das erste Beispiel auch die Anwendung anderer CSS-Stile wie Schriftart und -stärke (Fettdruck).

$(".percent.css.style1").progressPie({
    mode: $.fn.progressPie.Mode.CSS,
    valueData: "val",
    size: 50,
    ringWidth: 3,
    strokeWidth: 3,
    contentPlugin: "percent"
});
$(".percent.css.style2").progressPie({
    mode: $.fn.progressPie.Mode.CSS,
    valueData: "val",
    size: 50,
    ringWidth: 3,
    strokeWidth: 3,
    contentPlugin: "percent",
    contentPluginOptions: {
        singleLine: true,
        cssClass: "percents",
        cssClassUnit: "unitlabel"
    }
});

.percent.css svg {
    vertical-align: middle;
}
.percent.css .progresspie-background {
    stroke: silver;
    fill: #eee;
}
.percent.css .progresspie-foreground {
    stroke: navy;
}
.percent.css.style1 .progresspie-valuedisplay {
    fill: #058;
    font-weight: bold;
    font-family: sans-serif;
}
.percent.css.style2 .percents {
    fill: maroon;
}
.percent.css.style2 .unitlabel {
    fill: green;
}

<span class="percent css style1" data-val="66"></span>
<span class="percent css style2" data-val="66"></span>

Ein letztes Beispiel soll noch demonstrieren, dass CSS-Formatierung nicht nur im CSS-Modus möglich ist. Das JavaScript in diesem Beispiel ist identisch zu einem früheren Beispiel. Die Schriftfarbe der Wertanzeige wird hier per JavaScript gesetzt (und zwar nicht statisch, weder über eine Option noch eine CSS-Regel, sondern es wird die von einer Farbfunktion vom Prozentwert abgeleitete Diagrammfarbe wiederverwendet.) Dieses Beispiel weicht von seinem „Vater“ aber dadurch ab, dass für die Einheit („min.“) per CSS eine konstante Schriftfarbe festgelegt wird. Außerdem wird per CSS für den gesamten Content die Schriftart eingestellt.

.secs.withUnit.cssOverride .progresspie-valuedisplay {
    font-family: sans-serif;
}
.secs.withUnit.cssOverride .progresspie-unit {
    fill: navy;
    font-weight: bold;
}

<span class="secs withUnit cssOverride" data-val="35"></span>

Content-Plugins: Bilddateien als Vorder- oder Hintergrund hinzufügen, Hintergrund-Rechteck

Um diese Content-Plugins zu verwenden, binden Sie in Ihrem HTML-Dokument neben jQuery und jquery-progresspiesvg-min.js noch zusätzlich die mitgelieferte Plugin-Datei jquery-progresspiesvg-image-min.js mit ein!

Hintergrundbilder

Das Content-Plugin image kann benutzt werden, um eine externe Bilddatei zu laden und zum Diagramm hinzuzufügen. (Genauer: In dem SVG-Code wird eine Referenz zu einem Bild-URL eingebunden, welche den Browser bei der Anzeige des SVGs anweist, das Bild nachzuladen.) Standardmäßig wird dieses Bild als Hintergrundbild geladen, d.h. das Diagramm über das Bild gezeichnet.

Das nachfolgende Beispiel lädt ein exakt kreisförmiges Bild als Hintergrund, welches also exakt die Fläche des Diagramms einnimmt. Die Vordergrundfarbe für die Torte wird halbtransparent eingestellt, so dass das Hintergrund auch durch die gefüllten Diagrammflächen durchscheint. Ansonsten benutzen wir dasselbe Farbschema wie im Standard-Modus COLOR, aber um die Transparenz hinzuzufügen, schreiben wir eine eigene Farbfunktion, welche die vordefinierte statische Funktion $.fn.progressPie.colorByPercent() verwendet. Das ist dieselbe Funktion, die auch intern vom COLOR-Modus verwendet wird, hat bei direktem Aufruf aber noch einen zweiten Parameter für den Alpha-Kanal. Weiterhin schalten wir den Hintergrundkreis ab, indem wir strokeWidth auf 0 setzen:

$(".pp.world").progressPie({
    color: function(percent) {
        return $.fn.progressPie.colorByPercent(percent, 0.7);
    },
    size: 120,
    strokeWidth: 0,
    valueData: "val",
    contentPlugin: "image",
    contentPluginOptions: {
        href: "images/earth-147591.svg"
    }
});

In diesem Beispiel stimmt die vom Hintergrundbild „bemalte“ Fläche genau mit der Diagrammfläche überein, da das Bild quadratisch ist und nur die größte kreisförmige Teilfläche darin gefüllt ist, bei transparentem Hintergrund. Aber nehmen wir z.B. ein JPEG-Foto als Hintergrund, das keine transparenten Regionen hat (und nicht perfekt quadratisch ist):

$(".pp.worldphoto.rect").progressPie({
    color: "rgba(0,150,250,0.6)",
    size: 120,
    strokeWidth: 0,
    valueData: "val",
    contentPlugin: "image",
    contentPluginOptions: {
        href: "images/world-photo.jpg"
    }
});

Man sieht zunächst, dass das gesamte Foto als Hintergrundbild verwendet wird, also auch Bereiche außerhalb des Kreises füllt. Optional kann das Bild auf den Kreis des Diagramms beschnitten werden, indem die Option clipCircle auf true gesetzt wird. Außerdem ist die abgebildete Weltkugel tatsächlich etwas kleiner als die Diagrammfläche, und auch die Bilddatei ist nicht exakt quadratisch, so dass oben und unten jeweils eine kleine, nicht mit dem Hintergrundbild gefüllte Lücke bleibt. Um das zu „kaschieren“, zeichnen wir im folgenden Beispiel einfach einen dunkelblauen Hintergrundkreis um das Tortendiagramm. Damit dieser nicht durch die halbtransparente Torte mit durchscheint, setzen wir noch overlap auf false, so dass die Torte außen den Kreis nicht überlappt, sondern nur in seinem Inneren gezeichnet wird:

$(".pp.worldphoto.clipped").progressPie({
    color: "rgba(0,150,250,0.6)",
    size: 120,
    strokeWidth: 3,
    strokeColor: "navy",
    overlap: false,
    valueData: "val",
    contentPlugin: "image",
    contentPluginOptions: {
        href: "images/world-photo.jpg",
        clipCircle: true
    }
});

Falls Sie statt einer Torte ein Ringdiagramm zeichnen (indem Sie die ringWidth-Option setzen), wird das geladene Bild standardmäßig in den Kreis eingepasst:

$(".pr.aroundworld").progressPie({
    scale: 2,
    color: "navy",
    size: 60,
    strokeWidth: 0,
    ringWidth: 6,
    valueData: "val",
    contentPlugin: "image",
    contentPluginOptions: {
        href: "images/earth-147591.svg", 
        margin: 0
    }
});

Um auch für ein Ringdiagramm ein Hintergrundbild in voller Größe zu erhalten (analog zur Torte), setzen Sie die Option fullSize (in den contentPluginOptions) auf true. Genau wie im Tortenmodus wird das Bild dann standardmäßig in den Hintergrund, der Ring also darüber gezeichnet.

Das folgende Beispiel demonstriert außerdem die Einbindung mehr als nur eines Content-Plugins: Wir binden nicht nur ein Hintergrundbild (fullSize) ein, sondern fügen als Vordergrund im Ring per Wertanzeige-Plugin auch eine Anzeige des Prozentwerts hinzu:

$(".pr.twoplugins").progressPie({
    scale: 2,
    color: "navy",
    size: 60,
    valueData: "val",
    strokeWidth: 2,
    ringWidth: 8,
    contentPlugin: ["image", "percent"],
    contentPluginOptions: [
        { // options for "image"
            href: "images/earth-147591.svg",
            fullSize: true
        },
        { // options for "percent"
            color: "white",
        }
    ]
});

Für eine bessere Lesbarkeit der Zahlen auf dem Hintergrundbild zeichnen wir die Prozentanzeige in fetter Schrift. Das erledigen wir einfach direkt per CSS-Stil auf dem Absatz-Element, in den wir die Grafiken einfügen:

<p style="font-weight: bold">
    <span class="pr twoplugins" data-val="15"></span>
    <span class="pr twoplugins" data-val="40"></span>
    <span class="pr twoplugins" data-val="70"></span>
    <span class="pr twoplugins" data-val="100"></span>
</p>

Bilder/Icons in einem Ring-Graph

Wie bereits gesagt, wird das image-Plugin ein geladenes Bild zu einem Ring-Graph standardmäßig im Ring-Inneren anordnen. Dieser Default-Modus ist typischerweise nicht für Hintergrundbilder (wie bisher betrachtet) vorgesehen, sondern eher für im Ring anzuzeigende Inhalte wie z.B. die von den weiter oben vorgestellten Steuerungs- oder Fehler-Plugins direkt gezeichneten Symbole, nur eben dass das Symbol nicht vom Plug-in generiert, sondern aus einer Datei geladen wird.

Das folgende Beispiel zeigt eine solche Bilddatei in einem Ring-Diagramm. Der Rest des Diagramms wird in diesem Beispiel per CSS „gestyled“.

$(".pr.car").progressPie({
    mode: $.fn.progressPie.Mode.CSS,
    size: 120,
    valueData: "val",
    strokeWidth: 10,
    ringWidth: 10,
    contentPlugin: "image",
    contentPluginOptions: {
        href: "images/car-160115.svg",
        inBackground: false,
        margin: 6
    }
});

.pr.car svg {
    vertical-align: bottom;
}
.pr.car .progresspie-background {
    fill: #eef;
    stroke: #dde;
}
.pr.car .progresspie-foreground {
    stroke: #55f;
}

Sofern – wie das Lenkrad oben – das geladene Bild überlappungsfrei in den Ring passt, macht es keinen Unterschied, ob es in den Vorder- oder Hintergrund gezeichnet wird. Da die geladenen Bilder aber in der Regel viereckig sind, können Überlappungen durchaus auftreten. Das folgende Beispiel enthält weitgehend kreisförmige Emojis, deren Augenbrauen jedoch aus dem Kreis herausragen und (bei den gewählten Ausmaßen) den Ring überlappen. In diesem Fall setzen wir die inBackground-Option auf false (Standardwert ist true), damit die Augenbrauen nicht vom Ring verdeckt werden, sondern darüber gezeichnet werden.

Außerdem demonstriert dieses Beispiel, wie abhängig vom Prozentwert des Diagramms unterschiedliche Bilder geladen werden können:

var smileyOptions = {
    inBackground: false,
    margin: -1
};
$(".pr.smiley").progressPie({
    mode: $.fn.progressPie.Mode.COLOR,
    size: 120,
    valueData: "val",
    strokeWidth: 6,
    ringWidth: 6,
    strokeColor: "#ddd",
    contentPlugin: "image",
    optionsByPercent: function(percent) {
        if (percent < 33) {
            return { contentPluginOptions: $.extend({href: "images/frowning-150840.svg"}, smileyOptions)};
        } else if (percent > 66) {
            return { contentPluginOptions: $.extend({href: "images/smiley-150841.svg"}, smileyOptions)};
        } else {
            return { contentPluginOptions: $.extend({href: "images/smiley-150837.svg"}, smileyOptions)};
        }
    }
});

Masken

Bisher wurde gezeigt, wie Sie ein Bild als weitere Ebene (im Vorder- oder Hintergrund) zusätzlich zum eigenen Torten- oder Ringdiagramm zeichnen können. Als weitere Alternative steht auch die Option bereit, das eigentliche Diagramm gar nicht mehr als eigene Bildebene vor oder hinter einem Bild zu zeichnen, sondern als Maske für ein Bild zu verwenden. Dazu dient der MASK-Modus: Setzen Sie mode: $.fn.progressPie.Mode.MASK, um diesen zu aktivieren. Der Mask-Modus ist nur awendbar, wenn mindestens ein Content-Plugin eine Hintergrundebene hinter der Diagrammebene einfügt. In dem Fall wird das Diagramm als Maske für die oberste Hintergrundebene (also die Ausgabe des ersten Content-Plugins, das in den Hintergrund zeichnet) verwendet. Beginnen wir mit genau einer Anwendung des Content-Plugins image zum Zeichnen eines Hintergrundbildes.

Das Standardverhalten im MASK-Modus ist: Das Diagramm wird praktisch mit dem Hintergrundbild ausgefüllt, dort, wo das Diagramm transparent ist, wird das kein Hintergrund gezeichnet:

$(".pp.mask").setupProgressPie({
    mode: $.fn.progressPie.Mode.MASK,
    strokeWidth: 5,
    size: 120,
    valueData: "val",
    contentPlugin: "image",
    contentPluginOptions: {
        href: "images/earth-147591.svg"
    }
}).progressPie();

Falls Sie mehr als ein Hintergrundbild laden, wirkt die Maske nur auf das oberste (also zuerst geladene). Alle weiteren Hintergrundebenen bleiben als Hintergrund unverändert erhalten. Das folgende Beispiel demonstriert dies durch Hinzufügen eines Puzzle-Hintergrundbilds hinter der Weltkugel:

$(".pp.mask2").setupProgressPie({
    mode: $.fn.progressPie.Mode.MASK,
    strokeWidth: 5,
    size: 120,
    valueData: "val",
    contentPlugin: ["image", "image"],
    contentPluginOptions: [
        { //first background, i.e. layer directly behind chart, to be masked
            href: "images/earth-147591.svg"
        },
        { //second background, i.e. layer even behind first background, not masked
            href: "images/puzzlebg.png"
        }
    ]
}).progressPie();

Natürlich könnte dieser Puzzle-Hintergrund auch kreisförmig beschnitten werden, so dass er nur den Diagramm-inneren Hintergrund füllt (per clipCircle-Option). Weiter unten in Abschnitt Margin und Padding werden wir dieses Beispiel noch einmal aufgreifen und zeigen, wie man die Größe des Diagramms im Verhältnis zum Hintergrundbild reduzieren kann.

Die Standard-Maske des MASK-Modus besteht nur aus transparenten oder vollständig deckenden Bereichen. Die Standard-Maskenfarbe für das Diagramm ist $.fn.progressPie.Mode.MASK.color, welche wiederum standardmäßig auf 'white' (weiß) eingestellt ist: Weiße Teile der Maske werden komplett mit dem Hintergrund gefüllt. Der Rest der Maske (nicht vom Diagramm bedeckte Flächen) sind transparent.

Wenn Sie sich mit Maskierung auskennen und das verändern wollen: Die Voreinstellung der Vordergrundfarbe für den MASK-Modus können Sie durch Überschreiben von $.fn.progressPie.Mode.MASK.color global ändern. Lokal für ein einzelnes Diagramm können Sie die bekannten Standard-Optionen wie color und strokeColor verwenden, um die „Farben“ innerhalb der Maske zu verändern. Praktisch zeigen sich diese im Bild nicht als Farben, sondern als Transparenzgrade. Das folgende Beispiel demonstriert dies, indem eine benutzerdefinierte Farbfunktion für die Tortengrafik im Mask-Modus verwendet wird, die für den Wert 0% die Farbe Schwarz (voll transparent), für 100% die Farbe weiß (voll deckend) und für alle Werte dazwischen eine entsprechende Graustufe (teilweise transparent) festlegt:

$(".pp.mask2.fg").setupProgressPie({
    color: function(p) {
        var v = Math.ceil(p * 255 / 100);
        return "rgb(" + v + ", " + v + ", " + v + ")";
    }
}).progressPie();

Analog können Sie neben den beiden eben genannten Vordergrundfarben auch die Hintergrund-/Füllfarbe des Diagramms in der Maske verändern. Zur Demonstration fügen wir zu beiden obigen Beispielen .pp.mask und .pp.mask2 jeweils die Option backgroundColor hinzu und setzen sie auf einen recht dunklen Grauton (je dunkler, desto weniger des maskierten Bildes scheint dort durch):

$(".pp.mask.bg, .pp.mask2.bg").setupProgressPie({
    backgroundColor: "#444"
}).progressPie();

Neben dem MASK-Modus gibt es noch eine zweite Variante, den inverted mask mode, IMASK. Im IMASK-Modus, wird das Tortendiagramm in der Farbe $.fn.progressPie.Mode.IMASK.color (standardmäßig schwarz) gezeichnet, und der gesamte Hintergrund der Maske wird mit Farbe $.fn.progressPie.Mode.IMASK.color (standardmäßig weiß) gefüllt. Effektiv bewirkt eine solche effektive Maske also, dass das Tortendiagramm „aus dem Hintergrundbild herausgeschnitten“ wird, d.h. im Hintergrundbild bleibt ein tortendiagrammförmiges transparentes Loch:

$(".pp.imask").progressPie({
    mode: $.fn.progressPie.Mode.IMASK,
    strokeWidth: 5,
    size: 120,
    valueData: "val",
    contentPlugin: "image",
    contentPluginOptions: {
        href: "images/puzzlebg.png"
    }               
});

Das obige Beispiel soll keinen echten, „hübschen“ Anwendungsfall darstellen, sondern lediglich den IMASK-Modus in einer einfachen Anwendung kurz vorstellen. Falls hinter der so maskierten Hintergrundebene weitere Hintergründe (z.B. ein weiteres Bild) existieren, so werden diese durch das „tortenförmige Loch“ sichtbar. Weiter unten werden wir den IMASK-Modus für ein komplexeres und hübscheres Beispiel anwenden. Dazu werden jedoch zunächst noch ein paar weitere Features benötigt, die vorher noch einzeln vorgestellt und demonstriert werden.

Margin und Padding (Außen- und Innenränder)

Die progressPie()-Funktion unterstützt zwei Optionen, die beide einen frei bleibenden Rand um das eigentliche Diagramm einfügen:

margin definiert einen immer transparenten Außenrand um das Diagramm. Effektiv wird durch diese Option einfach die so genannte „view box“ des SVG-Bildes vergrößert.
padding definiert einen Innenrand, der zwischen dem Außenrand margin und dem Diagramm eingefügt wird.

In beiden Optionen kann wahlweise eine einfache Zahl eingetragen werden, die die Breite des einzufügenden Randes an allen vier Seiten (oben, rechts, unten, links) des Bildes festlegt. Sollen die Ränder an verschiedenen Seiten unterschiedlich breit sein, kann in der Option auch auch ein Array von bis zu vier Zahlen angegeben werden. Die Zuordnung der bis zu vier Zahlen zu den einzelnen Bildseiten erfolgt analog zur bei CSS für margin- und padding-Styles bekannten Kurzschreibweise, d.h. die Werte werden im Uhrzeigersinn beginnend ab 12 Uhr gelesen: Die erste Zahl gibt die Breite des oberen Randes an, die zweite die Breite des rechten Randes, der dritte Wert definiert den unteren Rand und der vierte den linken. Wird kein vierter Wert angegeben, wird der linke Rand gleich breit wie der rechte, wird kein dritter Wert angegeben, wird entsprechend der untere Rand genauso breit wie der obere.

Beide Optionen (margin und padding) haben den Standardwert 0, d.h. es wird gar kein Rand um das Diagramm freigelassen. Innen- und Außenrand addieren sich zum insgesamt freigelassenen Rand um das Diagramm. Der Unterschied zwischen Innen- und Außenrand zeigt sich ausschließlich dann, wenn Sie mit einem Content-Plugin wie z.B. image oder backgroundRect (siehe folgenden Abschnitt) eine Hintergrundebene in „fullSize“ einfügen. Wie oben bereits gezeigt und erklärt, wird ein Hintergrundbild hinter einem Tortendiagramm standardmäßig in voller Größe, bei einem Ringdiagramm nur unter Angabe der Option fullSize: true in voller Größe gezeichnet. Die volle Größe ist in diesem Fall nicht nur die (quadratische) Grundfläche des (kreisförmigen) Diagramms, sondern umfasst zusätzlich den Innenrand (padding), während der Außenrand (margin) grundsätzlich leer bleibt.

Das folgende Beispiel soll dies demonstrieren: Wir legen ein padding von 20 fest, d.h. rund um die Torte wird ein 20 Pixel breiter Innenrand eingefügt, das Bild wird dadurch um insgesamt 40 Pixel breiter und höher als die eigentliche Torte. Das Puzzle-Hintergrundbild füllt diesen Innenrand mit aus. Vergleichen Sie das mit den vorhergehenden Beispielen, in denen wegen padding = 0 das Tortendiagramm jeweils die Ränder des Hintergrundbildes berührte!

Zu Demonstrationszwecken fügen wir zusätzlich auch einen Außenrand ein, also einen freibleibenden Rand rund um das Puzzle-Hintergrundbild. Um diesen sichtbar zu machen, zeichnen wir per CSS um das fertige SVG-Bild einen gepunkteten Rand: Der weiße Bereich zwischen dieser gepunkteten Linie und dem Puzzle-Bild ist der Außenrand. Bei der Gelegenheit sei auch gleich die Array-Syntax zur Angabe unterschiedlicher Rand-Breiten an den vier verschiedenen Bildseiten demonstriert: Wir setzen margin: [5, 10, 20], d.h. oben lassen wir einen Außenrand von 5 Pixeln, rechts von 10 Pixeln, unten von 20 Pixeln. Da eine vierte Angabe für den linken Rand fehlt, stimmt dieser mit dem rechten überein (ebenfalls 10 Pixel).

Zu guter Letzt ist es wichtig, zur Kenntnis zu nehmen, dass nicht nur das Puzzle-Bild nun die gesamte Fläche von Diagramm plus Innenrand ausfüllt, sondern auch das ebenfalls in fullSize gezeichnete Weltkugel-Bild. Auf den ersten Blick mag das nicht auffallen, dieses mit der Torte maskiert wird, aber wenn wir einfach nur zum obigen .pp.mask2-Beispiel die genannten margin- und padding-Optionen hinzufügten, sähe das Resultat wie folgt aus:

Vergleichen Sie dieses Bild mit den obigen, so sehen Sie, dass die Torte nur von einem inneren Ausschnitt der Weltkugel gefüllt wird, nicht von der ganzen: Von Afrika ist gar nichts mehr zu sehen, von Südamerika fehlt der Süden, auch im Norden ist einiges weggeschnitten. Das liegt daran, dass diese fehlenden Teile der Weltkugel nun innerhalb des Innenrandes liegen und von der Diagrammmaske mit abgeschnitten wurden.

Um diesen Effekt zu kompensieren, also das Bild der Weltkugel innerhalb des Bereichs von Diagramm plus Innenrand so zu verkleinern, dass es wieder nur noch die eigentliche Diagrammfläche füllt und nicht in den Innenrand hineinragt, verwenden wir die Margin-Option des Content-Plugins: Mit dieser kann innerhalb der Ausgabe des Content-Plugins ein Rand freigelassen werden. Dieser soll exakt mit dem Innenrand des Gesamtdiagramms übereinstimmen, also ebenfalls 20 Pixel breit sein. Dazu fügen wir also innerhalb der contentPluginOptions die Zeile margin: 20 ein. (Diese Margin-Option des Content-Plugins – siehe dazu auch Details zu Größenverhältnissen und Maßen – ist nicht mit der globalen Außenrand-Option von progressPie() zu verwechseln!)

Das gesamte Beispiel sieht damit wie folgt aus:

$(".pp.mask3").setupProgressPie({
    mode: $.fn.progressPie.Mode.MASK,
    strokeWidth: 5,
    size: 120,
    valueData: "val", 
    padding: 20,
    margin: [5, 10, 20],
    contentPlugin: ["image", "image"],
    contentPluginOptions: [
        { //first background, i.e. layer directly behind chart, to be masked
            href: "images/earth-147591.svg", 
            margin: 20 //neutralize global padding for this image only
        },
        { //second background, i.e. layer even behind first background, not masked
            href: "images/puzzlebg.png"
        }
    ]
}).progressPie();

.pp.mask3 svg {
    border: 1px dotted silver;
}

Hintergrund-Rechteck

Neben dem Content-Plugin "image" enthält die Datei jquery-progresspie-image.js noch ein zweites Content-Plugin namens "backgroundRect", das einfach eine Hintergrundebene mit einem Rechteck um das Diagramm herum einfügt. Genau wie bei "image" im fullSize-Modus umfasst die Fläche dieses Rechtecks die eigentliche (quadratische) Diagrammfläche zuzüglich des ggf. per padding festgelegten Innenrandes.

Das Rechteck kann aus einer Linie und/oder einer Füllung bestehen. Über die Option stroke können Sie eine Linienfarbe, über fill eine Füllfarbe festlegen. Mindestens eine dieser beiden Angaben ist Pflicht! Sofern Sie eine Linienfarbe eingestellt haben, können Sie zusätzlich die Linienstärke per strokeWidth festlegen. Beachten Sie, dass durch Wählen einer größeren Liniendicke nicht – wie normalerweise bei SVG üblich – das Rechteck insgesamt wächst: Die Rechteckgröße wird automatisch stets so gewählt, dass die äußere Kante des Rechtecks genau in den Innenrand des Bildes eingepasst wird und eine dickere Linie also nicht über den Innenrand hinaus gezeichnet wird. Mit wachsender Strichstärke wächst die Rechteck-Linie also immer nur „nach innen“ zum Diagramm hin.
Das folgende Beispiel soll auch dies demonstrieren: Dort wird ein oberes Padding von 4 Pixeln und ein linkes Padding von 5 Pixeln eingestellt, die gegenüberliegenden Ränder (unten bzw. rechts) sind jeweils doppelt so groß (8 bzw. 10 Pixel). Die Strichstärke (strokeWidth) wird ebenfalls auf 4 Pixel eingestellt. Da also die Strichstärke mit dem oberen Innenrand übereinstimmt, füllt oben die Linie des Rechtecks den gesamten Innenrand aus, die Linie berührt oben das Diagramm. Links verbleibt noch eine Lücke von einem Pixel (5 Pixel Padding abzüglich 4 Pixel Strichstärke). Da die Ränder nicht symmetrisch sind, ist das Diagramm auch nicht im Rechteck zentriert.

$(".pp.bgrect").progressPie({
    mode: $.fn.progressPie.Mode.COLOR,
    size: 50,
    padding: [4, 10, 8, 5], 
    strokeWidth: 3,
    valueData: "val",
    contentPlugin: "backgroundRect",
    contentPluginOptions: {
        stroke: "red",
        fill: "silver",
        strokeWidth: 4
    }
});

Zu Abschluss nun ein komplexeres Beispiel

Dieses Beispiel ist inspiriert durch die Anzeige eines App-Icons auf dem Home-Screen von iOS während der Installation der App oder eines Updates.

Wir zeichnen zunächst ein App-Icon als Hintergrundebene mittels des "image"-Plugins.
Darüber legen wir eine weitere Hintergrundebene: Eine halbtransparente graue Fläche, die wir mittels des "backgroundRect"-Plugins zeichnen. Diese Ebene dunkelt also das darunter liegende Icon deutlich ab.
Das Kuchendiagramm wiederum soll aus dieser Abdunklungs-Ebene „herausgeschnitten“ werden, d.h. die Ebene soll mit dem Diagramm maskiert werden, und zwar im invertierten Modus IMASK. Auf diese Weise scheint überall dort, wo ansonsten die Torte gezeichnet würde, das Icon aus dem Hintergrund in seiner Original-Helligkeit durch.
Damit die Torte nicht genauso groß wie das Icon wird und dessen Ränder berührt, fügen wir um die Torte einen Innenrand (padding) ein.
Und schließlich runden wir nachträglich die Ecken des eigenltich quadratischen SVG per CSS ab, indem wir einen border-radius hinzufügen.

$(".pp.appupdate").progressPie({
    mode: $.fn.progressPie.Mode.IMASK,
    padding: 20,
    size: 80,
    valueData: "val",
    contentPlugin: ["backgroundRect", "image"],
    contentPluginOptions: [
        { //options for "backgroundRect", first background directly behind chart, to be masked
            fill: "rgba(0,0,0,0.6)"
        },
        { //options for "image", second background behind the first, not masked
            href: "images/appstore.png"
        },
    ]                   
});

.pp.appupdate svg {
    border-radius: 30px;
}

Wenn Sie unter padding eine einzige Zahl angeben, so dass der Rand rund um die quadratische Diagrammfläche auf allen Seiten gleich breit ist, so ist das resultierende Gesamtbild wieder quadratisch. Ein Hintergrundbild sollte dann ebenfalls quadratisch sein, andernfalls wird es so in diese quadratische Fläche eingepasst, dass es vollständig sichtbar ist: Ein rechteckiges Bild, das breiter als hoch ist, würde dabei vertikal zentriert, ein Hochkantbild entsprechend horizontal zentriert. In beiden Fällen würde es nicht mehr die gesamte Diagramm- plus Innenrand-Fläche ausfüllen.
Wenn Sie also ein nicht-quadratisches Hintergrundbild verwenden möchten, das dennoch die gesamte Grundfläche (Diagramm plus Innenrand/Padding) ausfüllt, dann müssen die padding-Werte entsprechend so gesetzt werden, dass die Fläche aus Diagramm und Padding ein Rechteck mit demselben Seitenverhältnis wie dem des Bildes ergibt.

Das folgende Beispiel ist eine kleine Variaton des vorhergehenden. Als Hintergrund wird hier ein Foto geladen, das 640 Pixel breit und 426 Pixel hoch ist. Unser Diagramm soll dasselbe Seitenverhältnis haben, aber halb so klein sein (so dass auch auf hochauflösenden Displays mit Device-Pixel-Ratio von 2:1 noch ein nativ aufgelöstes Bild zu sehen ist), d.h. wir streben für das SVG eine Dimension von 320 x 213 Pixel an. Der Durchmesser des Tortendiagramms soll noch kleiner als die Höhe sein, damit auch oben und unten noch (Innen-)Rand zwischen den Rand des Fotos und dem Tortendiagramm frei bleibt. Wir wählen einen Durchmesser von 190 Pixeln. Das heißt, die Höhendifferenz von 213−190 = 23 Pixeln soll sich zu gleichen Teilen auf den oberen und unteren Innenrand aufteilen, das Padding für oben und unten beträgt also die Hälfte davon: 11,5 Pixel. Entsprechend setzen wir linken und rechten Innenrand auf 65 Pixel, so dass sich die gewünschte Gesamtbreite von 190 + 2 * 65 = 320 Pixeln ergibt.

$(".pp.mustang").setupProgressPie({
    mode: $.fn.progressPie.Mode.IMASK,
    size: 190,
    padding: [11.5, 65],
    strokeWidth: 5,
    valueData: "val",
    contentPlugin: ["backgroundRect", "image"],
    contentPluginOptions: [
        {
            fill: "rgba(255,255,255,0.8)"
        },
        {
            href: "images/mustang_640x426.jpg"
        }
    ]
}).progressPie();

Indem wir oben beim Padding genau zwei Werte angegeben haben, also die jeweils gegenüberliegenden Ränder gleich breit sind, ist das Tortendiagramm über dem Foto zentriert.
Durch abweichende Ränder können wir die Torte auch verschieben, z.B. um die Torte und damit den Fokus auf einen bestimmten Bildbereich zu legen:

$(".pp.mustang.focus").setupProgressPie({
    padding: [23, 47, 0, 83],
}).progressPie();

Alle in diesen Beispielen verwendeten Bilddateien stammen von .

Beispiele: Content-Plugins

Content-Plugins: Control Icons (Steuerungs-Symbole)

Steuerungssymbole innerhalb eines Rings mit Standardgröße und gleicher Farbe

Manuelle Größenwahl und abweichende Farbe fürs Control Icon

Kombination mit Torten- statt Ringgrafik

Content-Plugin: checkComplete

Styling per CSS

Eigene CSS-Klassennamen

Content plug-in: checkComplete

Animation

Sekundäres Content-Plugin, so lange nicht fertig (100%)

Styling per CSS

Content-Plugins: Fehler- und Warnungs-Symbole

cross und exclamationMark

Kombination mit Tortengrafiken

Kombination mit Ringgrafiken

Details zu Größenverhältnissen und Maßen

Styling per CSS

warning

Styling per CSS

Kombinierendes Beispiel: Aktivitätsanzeiger ohne Fortschrittsmessung mit Zustandsrückmeldung nach Abschluss

Content-Plugin: Wertanzeige im Ring

Default: Prozentwerte ind Standard-Schriftgröße mit Beschriftung "%" in zweiter Zeile

Kleiner (size: 30):

Ein dickerer Ring mit abgerundeten Enden und anderer Farbe für Ring und Inhalt:

Einzeiliger Modus

Manipulierte Schriftgrößen: Einheit "%" größer, Zahl dafür kleiner

Anzeigen des Rohwertes statt des Prozentwertes

Styling per CSS

Content-Plugins: Bilddateien als Vorder- oder Hintergrund hinzufügen, Hintergrund-Rechteck

Hintergrundbilder

Bilder/Icons in einem Ring-Graph

Masken

Margin und Padding (Außen- und Innenränder)

Hintergrund-Rechteck

Zu Abschluss nun ein komplexeres Beispiel

Kleiner (`size: 30`):