aino-jstools

============
aino-jstools
============

aino-jstools is a set of tools for working with JavaScript and Django.
Primarily it compiles javascripts.


Design background
-----------------
We wanted to make a tool that made including a bunch of JavaScripts in a
template easy and clean and compiling all those JavaScripts into packed pieces
in production for optimal performance. The other goal we wanted to achive was
to expose urls defined in ``urls.py``, ``MEDIA_URL``, ``DEBUG`` settings to
JavaScript code. Our future includes making a cleaner implementation for i18n
in JavaScript than the one provided by Django.


Requirements
------------
- Django 1.x
- Python 2.5+
- Java (for compiling JavaScripts)


Install
-------
Include ``jstools`` in ``INSTALLED_APPS`` in your project settings.
Optionally include the jstools/urls.py in your ``urls.py``::

   (r'^jstools/', include('jstools.urls'))


Template usage
--------------
First define your scripts in a template as follows::

    {% scripts "js/mysite-min.js" %}
        http://yui.yahooapis.com/3.1.0/build/yui/yui-min.js
        js/a.js
        js/b.js
        {% url jshelper %}
    {% endscripts %}

When ``settings.DEBUG`` is ``True`` this will translate to::

    <script src="http://yui.yahooapis.com/3.1.0/build/yui/yui-min.js"></script>
    <script src="{{ MEDIA_URL }}js/a.js"></script>
    <script src="{{ MEDIA_URL }}js/b.js"></script>
    <script src="{% url jshelper %}"></script>

When ``settings.DEBUG`` is ``False`` this will translate to::

    <script src="{{ MEDIA_URL }}js/mysite-min.js?TIMESTAMP"></script>

where ``TIMESTAMP`` is based on modification date of
``{{ MEDIA_ROOT }}js/myste-min.js``


Compiling
---------
Compiling all defined scripts is as simple as running::

    python manage.py buildjs

If you are using the default ``filesystem`` and/or
``app_directories`` this management command will find all templates with
``{% scripts %}`` tags and compile its contents into the first argument of the
tag.


jshelper view
-------------
This view will output named urls, ``settings.MEDIA_URL``, ``settings.DEBUG``
(I suggest you override this in your template unless you want to recompile the
script when you change your ``DEBUG`` setting) for use in your JavaScript code. You
will have access to a JavaScript object named ``JSTOOLS`` by default, you can
change the name by setting ``JSTOOLS_NAMESPACE``.

``JSTOOLS.settings.MEDIA_URL``
    ``settings.MEDIA_URL``

``JSTOOLS.settings.DEBUG``
    ``settings.DEBUG``

``JSTOOLS.get_url``
    This function will get named urls defined in your ``urls.py``. First argument is
    the name of the named url, subsequent arguments are arguments passed to that
    pattern. Examples::

        JSTOOLS.get_url('jshelper');
        JSTOOLS.get_url('blog_entry', 2010, 04, 25, 'aino-jstools');