Debian Codegraph @

docs/internals/contributing/writing-code/javascript.txt

raw
1 ===============
2 JavaScript code
3 ===============
4
5 While most of Django core is Python, the ``admin`` and ``gis`` contrib apps
6 contain JavaScript code.
7
8 Please follow these coding standards when writing JavaScript code for inclusion
9 in Django.
10
11 Code style
12 ==========
13
14 * Please conform to the indentation style dictated in the ``.editorconfig``
15 file. We recommend using a text editor with `EditorConfig`_ support to avoid
16 indentation and whitespace issues. Most of the JavaScript files use 4 spaces
17 for indentation, but there are some exceptions.
18
19 * When naming variables, use ``camelCase`` instead of ``underscore_case``.
20 Different JavaScript files sometimes use a different code style. Please try to
21 conform to the code style of each file.
22
23 * Use the `ESLint`_ code linter to check your code for bugs and style errors.
24 ESLint will be run when you run the JavaScript tests. We also recommended
25 installing a ESLint plugin in your text editor.
26
27 * Where possible, write code that will work even if the page structure is later
28 changed with JavaScript. For instance, when binding a click handler, use
29 ``$('body').on('click', selector, func)`` instead of
30 ``$(selector).click(func)``. This makes it easier for projects to extend
31 Django's default behavior with JavaScript.
32
33 .. _javascript-patches:
34
35 JavaScript patches
36 ==================
37
38 Django's admin system leverages the jQuery framework to increase the
39 capabilities of the admin interface. In conjunction, there is an emphasis on
40 admin JavaScript performance and minimizing overall admin media file size.
41
42 .. _javascript-tests:
43
44 JavaScript tests
45 ================
46
47 Django's JavaScript tests can be run in a browser or from the command line.
48 The tests are located in a top level :source:`js_tests` directory.
49
50 Writing tests
51 -------------
52
53 Django's JavaScript tests use `QUnit`_. Here is an example test module:
54
55 .. code-block:: javascript
56
57 QUnit.module('magicTricks', {
58 beforeEach: function() {
59 const $ = django.jQuery;
60 $('#qunit-fixture').append('<button class="button"></button>');
61 }
62 });
63
64 QUnit.test('removeOnClick removes button on click', function(assert) {
65 const $ = django.jQuery;
66 removeOnClick('.button');
67 assert.equal($('.button').length, 1);
68 $('.button').click();
69 assert.equal($('.button').length, 0);
70 });
71
72 QUnit.test('copyOnClick adds button on click', function(assert) {
73 const $ = django.jQuery;
74 copyOnClick('.button');
75 assert.equal($('.button').length, 1);
76 $('.button').click();
77 assert.equal($('.button').length, 2);
78 });
79
80
81 Please consult the ``QUnit`` documentation for information on the types of
82 `assertions supported by QUnit <https://api.qunitjs.com/assert/>`_.
83
84 Running tests
85 -------------
86
87 The JavaScript tests may be run from a web browser or from the command line.
88
89 Testing from a web browser
90 ~~~~~~~~~~~~~~~~~~~~~~~~~~
91
92 To run the tests from a web browser, open up :source:`js_tests/tests.html` in your
93 browser.
94
95 To measure code coverage when running the tests, you need to view that file
96 over HTTP. To view code coverage:
97
98 * Execute ``python -m http.server`` from the root directory (not from inside
99 ``js_tests``).
100 * Open http://localhost:8000/js_tests/tests.html in your web browser.
101
102 Testing from the command line
103 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
104
105 To run the tests from the command line, you need to have `Node.js`_ installed.
106
107 After installing ``Node.js``, install the JavaScript test dependencies by
108 running the following from the root of your Django checkout:
109
110 .. console::
111
112 $ npm install
113
114 Then run the tests with:
115
116 .. console::
117
118 $ npm test
119
120 .. _EditorConfig: https://editorconfig.org/
121 .. _Java: https://www.java.com
122 .. _eslint: https://eslint.org/
123 .. _node.js: https://nodejs.org/
124 .. _qunit: https://qunitjs.com/