==========
JavaScript
==========

While most of Django core is Python, the ``admin`` and ``gis`` contrib apps
contain JavaScript code.

Please follow these coding standards when writing JavaScript code for inclusion
in Django.

Code style
----------

* Please conform to the indentation style dictated in the ``.editorconfig``
  file. We recommend using a text editor with `EditorConfig`_ support to avoid
  indentation and whitespace issues. Most of the JavaScript files use 4 spaces
  for indentation, but there are some exceptions.

* When naming variables, use ``camelCase`` instead of ``underscore_case``.
  Different JavaScript files sometimes use a different code style. Please try to
  conform to the code style of each file.

* Use the `JSHint`_ code linter to check your code for bugs and style errors.
  JSHint will be run when you run the JavaScript tests. We also recommended
  installing a JSHint plugin in your text editor.

.. _javascript-patches:

JavaScript patches
------------------

Django's admin system leverages the jQuery framework to increase the
capabilities of the admin interface. In conjunction, there is an emphasis on
admin JavaScript performance and minimizing overall admin media file size.
Serving compressed or "minified" versions of JavaScript files is considered
best practice in this regard.

To that end, patches for JavaScript files should include both the original
code for future development (e.g. ``foo.js``), and a compressed version for
production use (e.g. ``foo.min.js``). Any links to the file in the codebase
should point to the compressed version.

Compressing JavaScript
~~~~~~~~~~~~~~~~~~~~~~

To simplify the process of providing optimized JavaScript code, Django
includes a handy Python script which should be used to create a "minified"
version. To run it::

    python django/contrib/admin/bin/compress.py

Behind the scenes, ``compress.py`` is a front-end for Google's
`Closure Compiler`_ which is written in Java. However, the Closure Compiler
library is not bundled with Django directly, so those wishing to contribute
complete JavaScript patches will need to download and install the library
independently. The Closure Compiler library requires `Java`_ 7 or higher.

Please don't forget to run ``compress.py`` and include the ``diff`` of the
minified scripts when submitting patches for Django's JavaScript.

.. _Closure Compiler: https://developers.google.com/closure/compiler/
.. _EditorConfig: http://editorconfig.org/
.. _Java: https://www.java.com
.. _jshint: http://jshint.com/