Schnelleinstieg - Isg-Software

Voraussetzungen

Dieses Plugin wurde designed, um Grafiken zu einem HTML-Dokument hinzuzufügen, welche Zahlen visualisieren, die bereits Teil besagten Dokuments sind. Eine erste Voraussetzung ist also, dass Ihr HTML-Dokument die zu visualisierenden Werte (typischerweise Prozentwerte von 0 bis 100) bereits enthält – entweder als sichtbaren Dokumenten-Text oder unsichtbar in HTML-Attributen gewisser HTML-Elemente. Jedes Element, das einen solchen Wert enthält, muss selektierbar sein, z.B. über eine ID oder eine CSS-Klasse. Die Zahl selbst muss entweder der einzige Inhalt des selektierten Elements sein oder der Wert eines seiner Attribute oder eines seiner Kindelemente. Die Torten- oder Ringgrafik wird dann ins selektierte Element eingefügt (dem Inhalt wahlweise vorangestellt oder hinten angehängt).
Die Grafiken werden als Inline-SVG-Grafik ins HTML eingefügt. Eine Anzeige ist nur in neueren Browsern möglich, die (Inline-)SVG unterstützen. Ältere Browser zeigen die Grafiken schlicht nicht an. (Dasselbe gilt für Browser, in denen JavaScript abgeschaltet ist.)
Da diese Software als jQuery-Plugin entwickelt wurde, muss Ihr Dokument natürlich eine (halbwegs aktuelle) Version der jQuery-Bibliothek einbinden, entweder direkt von einem CDN, oder Sie downloaden und hosten die jQuery-Bibliothek direkt in Ihrem Web-Projekt.

Vereinfachte Benutzung mittels »Application Script«

Für eine besonders einfache Art der Einbindung wird nebem dem eigentlichen jQuery-Plugin noch ein zusätzliches JavaScript mitgeliefert, das optional hinzugeladen werden kann. Es wendet das jQuery-Plugin mit einigen vordefinierten Optionsmengen auf vordefinierte Selektoren an. Diese Art der Benutzung kommt ohne eigene Script-Programmierung aus, stellt aber nicht alle Möglichkeiten des Plugins zur Verfügung.

Um das Application Script zu verwenden, laden Sie es einfach nach der jQuery-Library und dem Plugin (im Kopfbereich Ihres HTMLs), z.B.:

						
<html>
    <head>
        <script type="text/javascript" src="http://code.jquery.com/jquery-1.11.3.min.js"></script>
        <script type="text/javascript" src="/path/to/jquery-progresspiesvg-min.js"></script>
        <script type="text/javascript" src="/path/to/progresspiesvgAppl-min.js"></script>
        …
    </head>
    …

Jedem Element, das einen Prozentwert hält und um eine Tortendarstellung ergänzt werden soll, ist nun mittels class-Attribut die Klasse progresspie zuzuordnen. Oder verwenden Sie alternativ die Klasse progressring für eine Ring- statt Tortendarstellung.
```
						
    …
    <body>
        …
        <p>Progress: <span class="progresspie">33</span> %</p>
        …
    </body>
</html>
					
```
Durch Hinzufügen weiterer vordefinierter Klassen oder von data-Attributen kann die Grafikerzeugung weiter konfiguriert werden.
Siehe Beispiele »Appl« für diverse Codeausschnitte und deren Ergebnis.

Direkte Anwendung des Plugins

Die „normale“ Anwendung eines jQuery-Plugins besteht im Schreiben eines eigenen JavaScript-Codes, welcher mittels jQuery einige Elemente des HTML-Dokuments selektiert und dann auf die Ergebnismenge das Plugin anwendet.

Zunächst müssen natürlich im Kopf des Elements jQuery und das Plugin geladen werden. (Das Application Script wird nicht benötigt.)
Schreiben Sie weiterhin Ihren eigenen JavaScript-Code, entweder in ein separates Script-File, das nach dem Plugin im HTML referenziert wird, oder direkt in einem script-Block im HTML. Um einfach einmalig beim Laden des Dokuments (statische) SVG-Grafiken zu im Dokument enthaltenen (statischen) Zahlen hinzuzufügen, schreiben Sie eine Eventhandler-Funktion für jQuerys „ready“-Event. In dieser Funktion starten Sie Ihre jQuery-Selektionsanfrage und rufen Sie auf dem Ergebnis das Plugin auf. Eine sehr einfache Anwendung sieht z.B. wie folgt aus:
```
						
<html>
    <head>
        <script type="text/javascript" src="http://code.jquery.com/jquery-1.11.3.min.js"></script>
        <script type="text/javascript" src="/path/to/jquery-progresspiesvg-min.js"></script>
        <script type="text/javascript" >
            $(function() {
                $(".progress.percent").progresspie();
            });
        </script>
        …
    </head>
    <body>
        …
        <p>Progress: <span class="progress percent">33</span> %</p>
        …
    </body>
</html>
					
```
Anpassungen an den Default-Einstellungen können vorgenommen werden, indem der Plugin-Funktion ein Objekt mit Optionen übergeben wird, wie z.B.:
```
$(".ring.percent").progressPie({
    strokeWidth: 1,
    ringWidth: 3,
    mode: $.fn.progressPie.Mode.COLOR 
});
```
Falls eine Grafik mehr als nur einmal gezeichnet werden soll, also nicht nur einmalig bei Seitenaufruf statische Werte visualisiert werden sollen, sondern per JavaScript auch die Werte der Grafik aktualisiert werden sollen, bietet das Plug-in seit Version 1.3.0 die Möglichkeit, über eine Setup-Funktion einmalig die Parameter festzulegen und anschließend über den parameterlose progressPie()-Funktion die Grafik (neu) zu zeichnen. Für jedes Update ist dann auf dem selektierten Element lediglich erneut progressPie() aufzurufen, ohne jedes Mal die Optionen wieder übergeben zu müssen. Damit ergibt sich folgendes Muster:
```
$(".ring.percent").setupProgressPie({
    strokeWidth: 1,
    ringWidth: 3,
    mode: $.fn.progressPie.Mode.COLOR 
}).progressPie();
```
Spätere Update-Aufrufe (Neuzeichnen nach dem Aktualisieren des eingentlichen Wertes):
```
$(".ring.percent").progressPie();
```
Siehe Beispiel-Seite für weitere, komplexere Codebeispiele, die die diversen Optionen vorführen, mit denen das Plugin aufgerufen werden kann.
Siehe generierte JDoc-Dokumentation für eine detaillierte Referenz.