Metadata-Version: 1.1
Name: bambu-ajax
Version: 2.0
Summary: AJAX utility functions for Django
Home-page: https://github.com/iamsteadman/bambu-ajax
Author: Steadman
Author-email: mark@steadman.io
License: UNKNOWN
Description: 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/>`_.
        
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
