Developing Gizmos

Last Updated: July 13, 2106

Anatomy of a Gizmo

Gizmos are made up of several parts: a TethysGizmoOptions class that is used to configure the Gizmo in the controller, a Django template, that contains the HTML that is required to render the Gizmo, static dependencies such as 3rd party JavaScript or CSS that is required by the Gizmo, and a function that defines which dependencies should be loaded for the Gizmo. Optionally, Gizmos can also have Django views (controllers) or other Python methods.

Organization of Gizmo Module

All Tethys Gizmos reside in the tethys_gizmo module of the main tethys repository. It is organized as follows:

tethys_gizmos/
  |-- gizmo_options/
  |-- lib/
  |-- static/tethys_gizmos/
        |-- css/
        |-- images/
        |-- js/
        |-- kml/
        |-- less/
        |-- vendor/
  |-- templates/tethys_gizmos/
        |-- gizmo_showcase/
        |-- gizmos/
  |-- templatetags/
        |-- tethys_gizmos.py
  |-- views/
        |-- gizmos/
        |-- gizmos_showcase.py
  |-- admin.py
  |-- context_processors.py
  |-- gizmo_dependencies.py
  |-- urls.py

The TethysGizmoOptions classes are defined in a separate Python script for each Gizmo in the gizmo_options package. The templates for each Gizmo are located in the templates/tethys_gizmos/gizmos directory. Any static files required for Gizmos are located in the static\tethys_gizmos with different types of static files located in the appropriate folder (i.e.: css, js, less).

Each Gizmo should also have a function in the gizmo_dependencies.py script that returns a tuple of the relative paths to the static files that need to be loaded when the Gizmo is rendered. All files of a Gizmo should share the same name with a different extension. The name of the gizmo_dependency function should share this name. For example, the date_picker Gizmo has a TethysGizmoOptions class defined in a file called date_picker.py, a template called date_picker.html and a gizmo_dependency function called date_picker(). It is not required that static files follow this same naming convention, but it is useful for tracking.

NOTE:

Only custom static files that you create for the Gizmos should be located in the js, css, and less directories. Any third party libraries that are included should be put into the vendor directory under an approriately named directory, rather than split between the css and js directories.

Tips for Creating New Gizmos