Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

added notes on jQuery #639

Closed
wants to merge 2 commits into from

5 participants

@evildmp
Collaborator

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))
+`Uncompressed and 'minified' jQuery`_.).
+
+It's also generally recommended that you make use of ``jquery.js`` as provided
+by Django, rather than calling in your own version.
+
+However, if you require the jQuery library to be in the global namespace, for
+example when using third-party jQuery plugins, or need a newer version of
+jQuery, you will have to include your own copy of jQuery.
+
+Uncompressed and 'minified' jQuery
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Django provides both uncompressed and 'minified' versions of jQuery, as
+``jquery.js`` and ``jquery.min.js`` respectively.
+
+The ``BaseModelAdmin`` superclass has a ``media`` property that returns a list
+of media files' URLS to the form. If :setting:`DEBUG` is ``True`` it will return

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
@mjtamlyn
Collaborator

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.

@evildmp
Collaborator

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?

@mjtamlyn
Collaborator

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.

@evildmp
Collaborator

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

@mjtamlyn
Collaborator

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

@evildmp
Collaborator

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?

@mjtamlyn
Collaborator

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"...

@sebleblanc
@evildmp
Collaborator

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.

@mjtamlyn
Collaborator

They seem more conflict-prone than teenaged children.

Welcome to Javascript...

@timgraham
Owner

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

@timgraham timgraham closed this
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Jan 11, 2013
  1. @evildmp

    added notes on jQuery

    evildmp authored
  2. @evildmp

    fixed typo

    evildmp authored
This page is out of date. Refresh to see the latest.
Showing with 25 additions and 5 deletions.
  1. +25 −5 docs/ref/contrib/admin/index.txt
View
30 docs/ref/contrib/admin/index.txt
@@ -1380,15 +1380,35 @@ The :doc:`staticfiles app </ref/contrib/staticfiles>` prepends
``None``) to any media paths. The same rules apply as :ref:`regular media
definitions on forms <form-media-paths>`.
-Django admin Javascript makes use of the `jQuery`_ library. To avoid
-conflicts with user-supplied scripts or libraries, Django's jQuery is
+Django admin Javascript makes use of the `jQuery`_ library.
+
+To avoid conflicts with user-supplied scripts or libraries, Django's jQuery is
namespaced as ``django.jQuery``. If you want to use jQuery in your own admin
JavaScript without including a second copy, you can use the ``django.jQuery``
object on changelist and add/edit views.
-If you require the jQuery library to be in the global namespace, for example
-when using third-party jQuery plugins, or need a newer version of jQuery, you
-will have to include your own copy of jQuery.
+The ``BaseModelAdmin`` superclass loads jQuery by default. There is no need to
+add jQuery to your ``ModelAdmin``'s list of required media resources just
+because it needs jQuery. In fact it is recommended *not* to; it's unnecessary,
+and could result in both ``jquery.js`` and ``jquery.min.js`` being loaded (see
+`Uncompressed and 'minified' jQuery`_.).
+
+It's also generally recommended that you make use of ``jquery.js`` as provided
+by Django, rather than calling in your own version.
+
+However, if you require the jQuery library to be in the global namespace, for
+example when using third-party jQuery plugins, or need a newer version of
+jQuery, you will have to include your own copy of jQuery.
+
+Uncompressed and 'minified' jQuery
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Django provides both uncompressed and 'minified' versions of jQuery, as
+``jquery.js`` and ``jquery.min.js`` respectively.
+
+The ``BaseModelAdmin`` superclass has a ``media`` property that returns a list
+of media files' URLs to the form. If :setting:`DEBUG` is ``True`` it will return
+the uncompressed versions of various JavaScript files, including ``jquery.js``;
+if not, it will return the 'minified' versions.
.. _jQuery: http://jquery.com
Something went wrong with that request. Please try again.