Ticket #13290: 13290_js_compression_docs.diff

File 13290_js_compression_docs.diff, 3.2 KB (added by gabrielhurley, 5 years ago)

adds info on minifying admin javascript and compress.py

  • django/contrib/admin/media/js/compress.py

     
    99def main():
    1010    usage = "usage: %prog [file1..fileN]"
    1111    description = """With no file paths given this script will automatically
    12 compress all jQuery based files of the admin app."""
     12compress all jQuery-based files of the admin app. Requires the Google Closure
     13Compiler library and Java version 6 or later."""
    1314    parser = optparse.OptionParser(usage, description=description)
    1415    parser.add_option("-c", dest="compiler", default="~/bin/compiler.jar",
    15                       help="path to closure compiler jar file")
     16                      help="path to Closure Compiler jar file")
    1617    parser.add_option("-v", "--verbose",
    1718                      action="store_true", dest="verbose")
    1819    parser.add_option("-q", "--quiet",
  • docs/internals/contributing.txt

     
    433433
    434434.. _Django i18n mailing list: http://groups.google.com/group/django-i18n/
    435435
     436Submitting javascript patches
     437=============================
     438
     439.. versionadded:: 1.2
     440
     441Django's admin system leverages the jQuery framework to increase the
     442capabilities of the admin interface. In conjunction, there is an emphasis on
     443admin javascript performance and minimizing overall admin media file size.
     444Serving compressed or "minified" versions of javascript files is considered
     445best practice in this regard.
     446
     447To that end, patches for javascript files should include both the original
     448code for future development (e.g. "foo.js"), and a compressed version for
     449production use (e.g. "foo.min.js"). Any links to the file in the codebase
     450should point to the compressed version.
     451
     452To simplify the process of providing optimized javascript code, Django
     453includes a handy script which should be used to create a "minified" version.
     454This script is located at ``/contrib/admin/media/js/compress.py``.
     455
     456Behind the scenes, ``compress.py`` is a front-end for Google's
     457`Closure Compiler`_ which is written in Java. However, the Closure Compiler
     458library is not bundled with Django directly, so those wishing to contribute
     459complete javascript patches will need to download and install the library
     460independently.
     461
     462The Closure Compiler library requires Java version 6 or higher (Java 1.6 or
     463higher on Mac OS X). Note that Mac OS X 10.5 and earlier did not ship with Java
     4641.6 by default, so it may be necessary to upgrade your Java installation before
     465the tool will be functional. Also note that even after upgrading Java, the
     466default `/usr/bin/java` command may remain linked to the previous Java
     467binary, so relinking that command may be necessary as well.
     468
     469Please don't forget to run ``compress.py`` and include the ``diff`` of the
     470minified scripts when submitting patches for Django's javascript.
     471
     472.. _Closure Compiler: http://code.google.com/closure/compiler/
     473
    436474Django conventions
    437475==================
    438476
Back to Top