diff options
Diffstat (limited to 'docs/internals/contributing/writing-code/javascript.txt')
| -rw-r--r-- | docs/internals/contributing/writing-code/javascript.txt | 64 |
1 files changed, 64 insertions, 0 deletions
diff --git a/docs/internals/contributing/writing-code/javascript.txt b/docs/internals/contributing/writing-code/javascript.txt new file mode 100644 index 0000000000..fa3685720e --- /dev/null +++ b/docs/internals/contributing/writing-code/javascript.txt @@ -0,0 +1,64 @@ +========== +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/ |