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):

$(".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 %

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: {
        backgroundColor: null,
        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>

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 %

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
    }
});

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 pixabay.

^