mirror of
https://github.com/django/django.git
synced 2024-12-27 03:25:58 +00:00
f48a1990fb
The script previously used the PyPI package closure, which is slightly out of date and not maintained by Google. The JavaScript contribution docs and the compress.py script now runs the google-closure-compiler package in the recommended way. Google's documentation on usage and installation can be found at: https://github.com/google/closure-compiler-npm/tree/master/packages/google-closure-compiler#usage This also makes the usage simpler as the package now runs through npm's npx utility, which will automatically install google-closure-compiler to a per-user cache.
152 lines
4.8 KiB
Plaintext
152 lines
4.8 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 `ESLint`_ code linter to check your code for bugs and style errors.
|
|
ESLint will be run when you run the JavaScript tests. We also recommended
|
|
installing a ESLint 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::
|
|
|
|
$ 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 will be installed automatically by ``npm``. 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
|
|
.. _eslint: https://eslint.org/
|
|
.. _node.js: https://nodejs.org/
|
|
.. _qunit: https://qunitjs.com/
|