.. _plot-view:

*********
Plot View
*********

**Last Updated:** August 10, 2015

Tethys Platform provides two interactive plotting engines: `D3 <http://d3js.org/>`_ and `Highcharts <http://www.highcharts.com/>`_. 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 <http://shop.highsoft.com/highcharts.html>`_). 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 <https://github.com/erdc-cm/tethysapp-dam_break/wiki/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 %}

Four elements are required:

1) A controller for the AJAX call with a plot view gizmo.
::

    @login_required()
    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)
::

    {% load tethys_gizmos %}

    {% gizmo flood_plot %}

3) A url map to the controller in app.py
::

    ...
        UrlMap(name='hydrograph_ajax',
               url='dam-break/map/hydrograph',
               controller='dam_break.controllers.hydrograph_ajax'),
    ...



4) The AJAX call in the 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 <http://api.highcharts.com/highcharts>`_.

::

    var plot = $('#my-plot').highcharts();