mirror of https://github.com/django/django.git
153 lines
4.9 KiB
Plaintext
153 lines
4.9 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.
|
|
|
|
* Where possible, write code that will work even if the page structure is later
|
|
changed with JavaScript. For instance, when binding a click handler, use
|
|
``$('body').on('click', selector, func)`` instead of
|
|
``$(selector).click(func)``. This makes it easier for projects to extend
|
|
Django's default behavior with JavaScript.
|
|
|
|
.. _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:
|
|
|
|
.. console::
|
|
|
|
$ pip install closure
|
|
$ 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. The Closure Compiler library is
|
|
not bundled with Django, but you can install it using pip as done above. 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.
|
|
|
|
.. _javascript-tests:
|
|
|
|
JavaScript tests
|
|
================
|
|
|
|
Django's JavaScript tests can be run in a browser or from the command line.
|
|
The tests are located in a top level ``js_tests`` directory.
|
|
|
|
Writing tests
|
|
-------------
|
|
|
|
Django's JavaScript tests use `QUnit`_. Here is an example test module:
|
|
|
|
.. code-block:: javascript
|
|
|
|
QUnit.module('magicTricks', {
|
|
beforeEach: function() {
|
|
var $ = django.jQuery;
|
|
$('#qunit-fixture').append('<button class="button"></button>');
|
|
}
|
|
});
|
|
|
|
QUnit.test('removeOnClick removes button on click', function(assert) {
|
|
var $ = django.jQuery;
|
|
removeOnClick('.button');
|
|
assert.equal($('.button').length, 1);
|
|
$('.button').click();
|
|
assert.equal($('.button').length, 0);
|
|
});
|
|
|
|
QUnit.test('copyOnClick adds button on click', function(assert) {
|
|
var $ = django.jQuery;
|
|
copyOnClick('.button');
|
|
assert.equal($('.button').length, 1);
|
|
$('.button').click();
|
|
assert.equal($('.button').length, 2);
|
|
});
|
|
|
|
|
|
Please consult the QUnit documentation for information on the types of
|
|
`assertions supported by QUnit <https://api.qunitjs.com/assert/>`_.
|
|
|
|
Running tests
|
|
-------------
|
|
|
|
The JavaScript tests may be run from a web browser or from the command line.
|
|
|
|
Testing from a web browser
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
To run the tests from a web browser, open up ``js_tests/tests.html`` in your
|
|
browser.
|
|
|
|
To measure code coverage when running the tests, you need to view that file
|
|
over HTTP. To view code coverage:
|
|
|
|
* Execute ``python -m http.server`` from the root directory (not from inside
|
|
``js_tests``).
|
|
* Open http://localhost:8000/js_tests/tests.html in your web browser.
|
|
|
|
Testing from the command line
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
To run the tests from the command line, you need to have `Node.js`_ installed.
|
|
|
|
After installing `Node.js`, install the JavaScript test dependencies by running
|
|
the following from the root of your Django checkout:
|
|
|
|
.. console::
|
|
|
|
$ npm install
|
|
|
|
Then run the tests with:
|
|
|
|
.. console::
|
|
|
|
$ npm test
|
|
|
|
.. _Closure Compiler: https://developers.google.com/closure/compiler/
|
|
.. _EditorConfig: https://editorconfig.org/
|
|
.. _Java: https://www.java.com
|
|
.. _jshint: https://jshint.com/
|
|
.. _node.js: https://nodejs.org/
|
|
.. _qunit: https://qunitjs.com/
|