.. _plot-view:
*********
Plot View
*********
**Last Updated:** August 10, 2015
Tethys Platform provides two interactive plotting engines: `D3 `_ and `Highcharts `_. The Plot view options objects have been designed to be engine independent, meaning that you can configure a D3 plot using the same syntax as a Highcharts plot. This allows you to switch which plotting engine to use via configuration. This article describes each of the plot views that are available.
.. warning::
Highcharts is free-of-charge for certain applications (see: `Highcharts JS Licensing `_). If you need a guaranteed fee-free solution, D3 is recommended.
.. note::
D3 plotting implemented for Line Plot, Pie Plot, Bar Plot, Scatter Plot, and Timeseries Plot.
Line Plot
=========
.. autoclass:: tethys_sdk.gizmos.LinePlot
Scatter Plot
============
.. autoclass:: tethys_sdk.gizmos.ScatterPlot
Polar Plot
==========
.. autoclass:: tethys_sdk.gizmos.PolarPlot
Pie Plot
========
.. autoclass:: tethys_sdk.gizmos.PiePlot
Bar Plot
========
.. autoclass:: tethys_sdk.gizmos.BarPlot
Time Series
===========
.. autoclass:: tethys_sdk.gizmos.TimeSeries
Area Range
==========
.. autoclass:: tethys_sdk.gizmos.AreaRange
JavaScript API
--------------
For advanced features, the JavaScript API can be used to interact with the HighCharts object that is generated by the Plot View JavaScript library.
TETHYS_PLOT_VIEW.initHighChartsPlot(jquery_element)
+++++++++++++++++++++++++++++++++++++++++++++++++++
This method initializes a chart generated from an AJAX request. An example is demonstrated in the `Dam Break javascript tutorial `_.
.. note::
In order to use this, you will either need to use a ``PlotView`` gizmo on
the main page or register the dependencies in the main html template page
using the ``import_gizmo_dependency`` tag with the ``plot_view`` name
in the ``import_gizmos`` block.
For example:
::
{% block import_gizmos %}
{% import_gizmo_dependency plot_view %}
{% endblock %}
Three elements are required:
1) A controller for the AJAX call with a plot view gizmo.
.. code-block:: python
@controller(
url="dam-break/map/hydrograph",
)
def hydrograph_ajax(request):
"""
Controller for the hydrograph ajax request.
"""
# add a plot view gizmo
flood_plot = TimeSeries(
...
)
context = {"flood_plot": flood_plot}
return render(request, "dam_break/hydrograph_ajax.html", context)
2) A template for with the tethys gizmo (e.g. hydrograph_ajax.html)
.. code-block:: html+django
{% load tethys_gizmos %}
{% gizmo flood_plot %}
3) The AJAX call in the javascript
.. code-block:: javascript
$(function() { //wait for page to load
$.ajax({
url: 'hydrograph',
method: 'GET',
data: {
'peak_flow': 500, //example data to pass to the controller
},
success: function(data) {
// add plot to page
$("#plot_view_div").html(data);
//Initialize Plot
TETHYS_PLOT_VIEW.initHighChartsPlot($('.highcharts-plot'));
}
});
});
Highcharts JavaScript API
-------------------------
The Highcharts plots can be modified via JavaScript by using jQuery to select the Highcharts div and calling the ``highcharts()`` method on it. This will return the JavaScript object that represents the plot, which can be modified using the `Highcharts API `_.
::
var plot = $('#my-plot').highcharts();