65 lines
2.5 KiB
Plaintext
65 lines
2.5 KiB
Plaintext
|
==========
|
||
|
|
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/
|