Das Optionen-Objekt von jqPlot

Inhaltsverzeichnis

• Einführung
• Titel
• Achsen
• Daten-Serien
• Legende

Einführung

Hier eine Einführung in die Funktionsweise der jqPlot-Optionen. Eine ausführliche Dokumentation aller Optionen findet sich weiter unten im Kapitel API. Wird ein Chart in einem DIV mit der id chart erzeugt, sieht der Aufruf so aus:

chartObject = $.jqplot('chart', dataSeries, optionsObj);

dataSeries ist hier eine Liste der Daten, die angezeigt werden sollen, optionsObj ist das Optionen-Objekt, um das es hier nun genauer gehen soll. Als allererstes gleich ein wichtiger Hinweis: Optionen für den Chart sollten nicht im DIV-Element gesetzt werden, sondern immer über das Options-Objekt.

Die Funktion jqplot() oben erzeugt ein jqPlot-Objekt, das viele Attribute besitzt, die das Aussehen des Charts beeinflussen. Werden einige diese Attribute im Optionen-Objekt genannt überschreiben diese die gleichlautenden Attribute im jqPlot-Objekt. Ein kleiner Ausschnitt der Attribute sieht so aus.

jqPlot-|
        |-seriesColors
        |-textColor
        |-fontFamily
        |-fontSize
        |-stackSeries
        |-series(Array)-|
        |               |-Series1-|
        |               |         |-lineWidth
        |               |         |-linePattern
        |               |         |-shadow
        |               |         |-showLine
        |               |         |-showMarker
        |               |         |-color
        |               |-Series2...
        |               |-...
        |               |-SeriesN
        |
        |-grid(Object)-|
        |              |-drawGridLines
        |              |-background
        |              |-borderColor
        |              |-borderWidth
        |              |-shadow
        |
        |-title(Object)-|
        |               |-text
        |               |-show
        |               |-fontFamily
        |               |-fontSize
        |               |-textAlign
        |               |-textColor
        |
        |-axes(Object)-|
        |              |-xais-|
        |              |      |-min
        |              |      |-max
        |              |      |-numberTicks
        |              |      |-showTicks
        |              |      |-showTickMarks
        |              |      |-pad
        |
        | ... und so weiter

Das Options-Objekt sollte bis auf wenige (noch genauer zu erklärende) Ausnahmen dieselbe Struktur aufweisen, wie das Objekt oben. Ein Beispiel wäre also:

optionObj = {
    textColor:"#ff0000",
    grid: {
        shadow:false, 
        borderWidth:9.0
    }
}

Renderer und Plugins

Ein Renderer ist ein Objekt, das etwas zeichnet. Er ist an ein bestehendes Objekt gebunden, um es zu zeichnen.Ein Plugin kann mehr als nur zeichnen. Plugins stellen alle möglichen Funktionalitäten zur Verfügung wie z.B. die Berechnung einer Trendlinie oder die Realisierung von Eventhandling. So sind also Renderer Plugins, aber Plugins müssen nicht notwendigerweise Renderer sein.

Renderer werden also verwendet, indem sie an ein Objekt gebunden werden, das sie zeichnen sollen. Zum Beispiel so:

optionsObj = {
   seriesDefaults:{renderer:$.jqplot.BarRenderer},
   axes:{xaxis:{renderer:$.jqplot.CategoryAxisRenderer}}
}

Über die Option seriesDefaults werden Optionen für alle Daten-Serien gesetzt. Hier wird also für alle Serien der Standard-Renderer durch den BarRenderer ersetzt. Für die X-Achse wird der Standard-Renderer durch den CategoryAxisRenderer ersetzt.

Will man für einen Renderer Optionen mitgeben, kann man dies über die rendererOption Option. Zum Beispiel:

optionsObj = {
   seriesDefaults:{
       renderer:$.jqplot.BarRenderer},
       rendererOptions:{
           barWidth:25
       },
   axes:{xaxis:{renderer:$.jqplot.CategoryAxisRenderer}}
}

Plugins sind nicht an ein Objekt gebunden und können je nach Funktionalität auf unterschiedliche Weise konfiguriert werden. Wie sich dies dann im Options-Objekt niederschlägt, sollte der Dokumentation des entsprechenden Plugins entnommen werden.

Themen

Titel

Der Titel gibt die Überschrift über dem Plot an. Standard ist keinen Titel anzuzeigen. Beispiel:

optionsObj = {
   title: 'Mein Plot'
}

Achsen

Mit dem Achsen-Objekt lassen sich viele Optionen an den Achsen verändern. Beispiel:

optionsObj = {
    axesDefaults: {
        tickOptions: {formatString: "$%'d"}
    },
    axes: {
        xaxis: {
            renderer: $.jqplot.DateAxisRenderer,
            label: "Months",
            numberTicks: 3,
            tickOptions: {formatString: "%B"}
        },
        yaxis: {
            label: "Geld in €"
        },
        y2axis: {
            label: 'Profit'
        }
    }
}

axisDefaults definiert Standardwerte für alle Axen, die von einzelnen axes-Definitione überschrieben werden können.

Daten-Serien

Die eigentlichen Daten werden dem jqPlot-Objekt als zweites Argument übergeben. Im Option-Objekt können die Eigenschaften konfiguriert werden. Zum Beispiel:

optionsObj = {
    seriesDefaults: {
        yaxis: 'y3axis',
        markerOptions: {
            style: 'filledCircle',
            size: 10,
            showLine: true
        }
    },
    series: [
        {}, // für die erste Serie die Defaults lassen
        {
            yaxis: 'y2axis',
            label: 'Profit'
        }
    ]
}

Mit seriesDefaults können Standard-Konfigurationen festgelegt werden, die für alle Serien gelten. Diese Default-Werte können aber auch in der series-Konfiguration für einzelne Serien überschrieben werden.

Legende

optionsObj = {
    legend: {
        show: true,
        placement: 'outsideGrid'
    }
}