Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

added notes on jQuery #639

Closed
wants to merge 2 commits into from

5 participants

Daniele Procida Marc Tamlyn Sébastien Leblanc Tim Graham Keryn Knight
Daniele Procida
Owner

I have tried to make the advice on what to do about jQuery in admin a bit clearer and the recommendations stronger.

Also, I couldn't find any mention of https://github.com/django/django/blob/master/django/contrib/admin/options.py#L401 in the docs.

Ticket: https://code.djangoproject.com/ticket/19597

docs/ref/contrib/admin/index.txt
((20 lines not shown))
  1394
+`Uncompressed and 'minified' jQuery`_.).
  1395
+
  1396
+It's also generally recommended that you make use of ``jquery.js`` as provided
  1397
+by Django, rather than calling in your own version.
  1398
+
  1399
+However, if you require the jQuery library to be in the global namespace, for
  1400
+example when using third-party jQuery plugins, or need a newer version of
  1401
+jQuery, you will have to include your own copy of jQuery.
  1402
+
  1403
+Uncompressed and 'minified' jQuery
  1404
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  1405
+Django provides both uncompressed and 'minified' versions of jQuery, as
  1406
+``jquery.js`` and ``jquery.min.js`` respectively.
  1407
+
  1408
+The ``BaseModelAdmin`` superclass has a ``media`` property that returns a list
  1409
+of media files' URLS to the form. If :setting:`DEBUG` is ``True`` it will return
1

media files' URLS is doesn't read particularly nicely, though the other option, media file URLs isn't much better.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Marc Tamlyn
Owner

Hmmm, I think this section of the docs should also mention the age of the included jQuery. Admin still runs on jQuery 1.4 which is probably not what you might expect if you include it for your own purposes. We have a few cases where we have both jQuery for django and a more modern version included to use other plugins on admin pages.

Daniele Procida
Owner

How about instead of "It's also generally recommended that you make use of jquery.js as provided by Django" then:

If possible, use jquery.js as provided by Django, rather than calling in your own version.

and noting that Django's jQuery is somewhat old?

Marc Tamlyn
Owner

Hmm, personally I wouldn't use the admin's jQuery for anything now so I would prefer the extra load.

Even better, update the jQuery. I don't know the reasons why/why not, but I don't think the django docs should be recommending the use of a version of a library which is 3 years out of date... You regularly run into issues with compatibility with modern plugins.

Daniele Procida
Owner

Also, perhaps it is worth treating the two issues in this as separate - the uncompressed and 'minified' jQuery note is about a different matter.

Marc Tamlyn
Owner

True, not worth having both, but kinda irrelevant if you're not using it....

Daniele Procida
Owner

I thought I'd commented on this but must have deleted it before hitting comment:

Even better, update the jQuery. I don't know the reasons why/why not, but I don't think the django docs should be recommending the use of a version of a library which is 3 years out of date... You regularly run into issues with compatibility with modern plugins.

If the Django jQuery is so old that users might expect to need a newer version for their custom admin, then the docs should explain that.

I don't understand it well enough to explain it, but I am willing to ask questions about it on IRC until I do...

Is something like http://pypi.python.org/pypi/django-jquery/1.8.1 worth mentioning?

Marc Tamlyn
Owner

I would say no, as I think that python packages shouldn't exist solely to install static assets. I believe our front end department currently advocate getting jQuery from a CDN anyway... There's no clearly defined "way of doing it"...

Sébastien Leblanc
Daniele Procida
Owner

The advantage of supplying (or by default using) a reasonably up-to-date version of jQuery for Django would be that developers would have something they could rely on the admin to provide.

It might not be suitable for everyone, but it would be suitable for many, and particularly it would help people who are starting out; it's one less thing to worry about: "if you want to use jQuery in your Django application, you can use this one, in this way. If your needs are more complex, then you can [...]"

It would also mean that authors of reusable applications won't feel the need to include their own version, unless they really have to. I'm using a bunch of reusable applications, and in some admin templates I have a veritable plethora of conflicting jQuery versions being loaded. They seem more conflict-prone than teenaged children.

Marc Tamlyn
Owner

They seem more conflict-prone than teenaged children.

Welcome to Javascript...

Tim Graham
Owner

Thanks for this. I've made some edits and committed it.

Tim Graham timgraham closed this January 15, 2013
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Showing 2 unique commits by 1 author.

Jan 11, 2013
Daniele Procida added notes on jQuery b708ea8
Daniele Procida fixed typo 406108c
This page is out of date. Refresh to see the latest.

Showing 1 changed file with 25 additions and 5 deletions. Show diff stats Hide diff stats

  1. 30  docs/ref/contrib/admin/index.txt
30  docs/ref/contrib/admin/index.txt
@@ -1380,15 +1380,35 @@ The :doc:`staticfiles app </ref/contrib/staticfiles>` prepends
1380 1380
 ``None``) to any media paths. The same rules apply as :ref:`regular media
1381 1381
 definitions on forms <form-media-paths>`.
1382 1382
 
1383  
-Django admin Javascript makes use of the `jQuery`_ library. To avoid
1384  
-conflicts with user-supplied scripts or libraries, Django's jQuery is
  1383
+Django admin Javascript makes use of the `jQuery`_ library. 
  1384
+
  1385
+To avoid conflicts with user-supplied scripts or libraries, Django's jQuery is
1385 1386
 namespaced as ``django.jQuery``. If you want to use jQuery in your own admin
1386 1387
 JavaScript without including a second copy, you can use the ``django.jQuery``
1387 1388
 object on changelist and add/edit views.
1388 1389
 
1389  
-If you require the jQuery library to be in the global namespace, for example
1390  
-when using third-party jQuery plugins, or need a newer version of jQuery, you
1391  
-will have to include your own copy of jQuery.
  1390
+The ``BaseModelAdmin`` superclass loads jQuery by default. There is no need to
  1391
+add jQuery to your ``ModelAdmin``'s list of required media resources just
  1392
+because it needs jQuery. In fact it is recommended *not* to; it's unnecessary,
  1393
+and could result in both ``jquery.js`` and ``jquery.min.js`` being loaded (see
  1394
+`Uncompressed and 'minified' jQuery`_.).
  1395
+
  1396
+It's also generally recommended that you make use of ``jquery.js`` as provided
  1397
+by Django, rather than calling in your own version.
  1398
+
  1399
+However, if you require the jQuery library to be in the global namespace, for
  1400
+example when using third-party jQuery plugins, or need a newer version of
  1401
+jQuery, you will have to include your own copy of jQuery.
  1402
+
  1403
+Uncompressed and 'minified' jQuery
  1404
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  1405
+Django provides both uncompressed and 'minified' versions of jQuery, as
  1406
+``jquery.js`` and ``jquery.min.js`` respectively.
  1407
+
  1408
+The ``BaseModelAdmin`` superclass has a ``media`` property that returns a list
  1409
+of media files' URLs to the form. If :setting:`DEBUG` is ``True`` it will return
  1410
+the uncompressed versions of various JavaScript files, including ``jquery.js``;
  1411
+if not, it will return the 'minified' versions.
1392 1412
 
1393 1413
 .. _jQuery: http://jquery.com
1394 1414
 
Commit_comment_tip

Tip: You can add notes to lines in a file. Hover to the left of a line to make a note

Something went wrong with that request. Please try again.