Bambu AJAX
==========

AJAX utility functions for Django that can be accessed via a single URL
(ala WordPress admin-ajax.php)

About Bambu AJAX
----------------

Bambu AJAX lets you write utility functions for your Django apps that
can be called via AJAX, without having to specify a separate URL pattern
and view for each one.

About Bambu Tools 2.0
---------------------

This is part of a toolset called Bambu Tools. It's being moved from a
namespace of ``bambu`` to its own 'root-level' package, along with all
the other tools in the set. If you're upgrading from a version prior to
2.0, please make sure to update your code to use ``bambu_ajax`` rather
than ``bambu.ajax``.

Installation
------------

Install the package via Pip:

::

    pip install bambu-ajax

Add it to your ``INSTALLED_APPS`` list:

::

    INSTALLED_APPS = (
        ...
        'bambu_ajax'
    )

Add ``bambu_ajax.urls`` to your URLconf:

::

    urlpatterns = patterns('',
        ...
        url(r'^ajax/', include('bambu_ajax.urls')),
    )

Basic usage
-----------

Create a file called ``ajax.php`` within your Django app, and import the
necessary module from the ``bambu-ajax`` package, like so:

::

    from bambu_ajax import site

    @site.register
    def my_ajax_function(request):
        return [
            'a', 'list', 'of', 'things'
        ]

Using the ``site.register`` decorator registers your AJAX function with
the ``bambu_ajax`` view.

To leverage this function from within a Django template, use the
``ajaxurl`` template tag, like so:

::

    {% load ajax %}
    <script>
        $.getJSON('{% ajaxurl 'my_project.my_app.my_ajax_function' %}&callback=?',
            function(data) {
                console.log(data);
            }
        );
    </script>

Here, ``my_project`` should refer to the name of your Django project,
``my_app`` should be the name of the app you put your ``ajax.py`` file
in, and ``my_ajax_function`` is the name of the function you defined
within ``ajax.py``.

The notation is similar to that used when referring to Django models, in
that you always skip the common portion ``ajax`` from the naming
convention.

Shortcut
--------

Make your life easier by including the utility library in your template:

::

    <script src="{% url 'ajax_utility' %}"></script>
    <script>
        bambu.ajax.get('my_project.my_app.my_ajax_function',
            function(data) {
                console.log(data);
            }
        );
    </script>

This achieves the same result, but in a much cleaner way.

Dynamically updating page content
---------------------------------

As well as returning JSON-serialisable data per the examples above, you
can also use AJAX functions just like views, in that they can return an
``HttpResponse`` object.

Using that method, the example above would print out the HTML (or other
data) returned in the HTTP response.

Additional decorators
---------------------

You can of course add other decorators, just as you would with normal
views.

Todo
----

-  Add a dedicated ``login_required`` decorator that returns a more
   helpful response for anonymous users
-  Look into integrating this with
   `Plunja <http://iamsteadman.github.io/plunja/>`_, my dynamic
   JavaScript templating library.

Questions or suggestions?
-------------------------

Find me on Twitter (@iamsteadman) or `visit my blog <http://steadman.io/>`_.
