<commit_before>*******************
Template Gizmos API
*******************

**Last Updated:** May 21, 2015

Template Gizmos are building blocks that can be used to create beautiful interactive controls for web apps. Using the Template Gizmos API, developers can add date-pickers, plots, and maps to their app pages with minimal coding. This article provides an overview of how to use Gizmos. If you are not familiar with templating in Tethys apps, please review :doc:`../tutorials/getting_started/view` tutorial before proceeding.

For a detailed explanation and code examples of each Gizmo, see the :doc:`./gizmos_api` documentation.

Working with Gizmos
===================

The best way to illustrate how to use Template Gizmos is to look at an example. The following example illustrates how to add a date picker to a page using the Date Picker Gizmo. The basic workflow involves three steps:

1. Define gizmo options in the controller for the template
2. Load gizmo library in the template
3. Insert the gizmo tag in the template

A detailed description of each step follows.


1. Define Gizmo Options
-----------------------

The first step is to import the appropriate options object and configure the Gizmo. This is performed in the controller of the template where the Gizmo will be used.

In this case, we import ``DatePickerOptions`` and initialize a new object called ``date_picker_options`` with the appropriate options. Then we pass the object to the template via the ``context`` dictionary:

::

    from tethys_gizmos.gizmos_options import DatePickerOptions

    def example_controller(request):
        """
        Example of a controller that defines options for a Template Gizmo.
        """
        date_picker_options = DatePickerOptions(name='data1',
                                                display_text='Date',
                                                autoclose=True,
                                                format='MM d, yyyy',
                                                start_date='2/15/2014',
                                                start_view='decade',
                                                today_button=True,
                                                initial='February 15, 2014')

        context = {'date_picker_options': date_picker_options}

        return render(request, 'path/to/my/template.html', context)

.. note::

    The Gizmo Options objects are new as of version 1.1.0. Prior to this time, Gizmo options were defined using dictionaries. The dictionary parameterization of Gizmos is still supported, but will no longer be referenced in the documentation.

The :doc:`./gizmos_api` provides detailed descriptions of each Gizmo option object, valid parameters, and examples of how to use them.

2. Load Gizmo Library
---------------------

Now near the top of the template where the Gizmo will be inserted, load the ``tethys_gizmos`` library using the `Django load tag <https://docs.djangoproject.com/en/1.8/ref/templates/builtins/#load>`_. This only needs to be done once per template:

::

    {% load tethys_gizmos %}

3. Insert the Gizmo
-------------------

The ``gizmo`` tag is used to insert the date picker anywhere in the template. The ``gizmo`` tag accepts two arguments: the name of the Gizmo to insert and a dictionary of configuration options for the Gizmo:<commit_msg>tethys#85 - Resolved documentation typo with DatePickerOptions that should have been DatePicker.<commit_after>*******************
Template Gizmos API
*******************

**Last Updated:** May 21, 2015

Template Gizmos are building blocks that can be used to create beautiful interactive controls for web apps. Using the Template Gizmos API, developers can add date-pickers, plots, and maps to their app pages with minimal coding. This article provides an overview of how to use Gizmos. If you are not familiar with templating in Tethys apps, please review :doc:`../tutorials/getting_started/view` tutorial before proceeding.

For a detailed explanation and code examples of each Gizmo, see the :doc:`./gizmos_api` documentation.

Working with Gizmos
===================

The best way to illustrate how to use Template Gizmos is to look at an example. The following example illustrates how to add a date picker to a page using the Date Picker Gizmo. The basic workflow involves three steps:

1. Define gizmo options in the controller for the template
2. Load gizmo library in the template
3. Insert the gizmo tag in the template

A detailed description of each step follows.


1. Define Gizmo Options
-----------------------

The first step is to import the appropriate options object and configure the Gizmo. This is performed in the controller of the template where the Gizmo will be used.

In this case, we import ``DatePicker`` and initialize a new object called ``date_picker_options`` with the appropriate options. Then we pass the object to the template via the ``context`` dictionary:

::

    from tethys_gizmos.gizmos_options import DatePicker

    def example_controller(request):
        """
        Example of a controller that defines options for a Template Gizmo.
        """
        date_picker_options = DatePicker(name='data1',
                                         display_text='Date',
                                         autoclose=True,
                                         format='MM d, yyyy',
                                         start_date='2/15/2014',
                                         start_view='decade',
                                         today_button=True,
                                         initial='February 15, 2014')

        context = {'date_picker_options': date_picker_options}

        return render(request, 'path/to/my/template.html', context)

.. note::

    The Gizmo Options objects are new as of version 1.1.0. Prior to this time, Gizmo options were defined using dictionaries. The dictionary parameterization of Gizmos is still supported, but will no longer be referenced in the documentation.

The :doc:`./gizmos_api` provides detailed descriptions of each Gizmo option object, valid parameters, and examples of how to use them.

2. Load Gizmo Library
---------------------

Now near the top of the template where the Gizmo will be inserted, load the ``tethys_gizmos`` library using the `Django load tag <https://docs.djangoproject.com/en/1.8/ref/templates/builtins/#load>`_. This only needs to be done once per template:

::

    {% load tethys_gizmos %}

3. Insert the Gizmo
-------------------

The ``gizmo`` tag is used to insert the date picker anywhere in the template. The ``gizmo`` tag accepts two arguments: the name of the Gizmo to insert and a dictionary of configuration options for the Gizmo:
{'fraction_non_alphanumeric': 0.09104367135455219, 'fraction_numerical': 0.009474463360473723, 'mean_word_length': 2.618639528655597, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 28, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7027507', 'n_tokens_mistral': 1677, 'n_tokens_neox': 1589, 'n_words': 797}