Metadata-Version: 1.1
Name: DjPj
Version: 0.3.1
Summary: A template-block-based Django helper for jQuery-PJAX.
Home-page: https://github.com/alexhill/djpj
Author: Alex Hill
Author-email: alex@hill.net.au
License: BSD
Description: Overview of DjPj (formerly Django-PJAX-Blocks)
        ==============================================
        
        DjPj is a simple, flexible way to add PJAX support to your Django project and
        deliver a faster browsing experience to users of your website.
        
        If you don't know what PJAX is, `read about how it works`__ below. In a
        nutshell, it makes navigating between pages on your website faster by loading
        only the part of the page that needs to change, rather than the whole thing.
        It's is a well-established technique; if you're reading this on GitHub, you
        probably loaded this content via PJAX.
        
        __ https://pypi.python.org/pypi/djpj/#how-does-pjax-work
        
        In a nutshell, your DjPj-enabled website will respond to PJAX requests with
        the contents of a single template block of your choosing. It requires no
        changes to your views, which means it's easy to add PJAX support to
        third-party Django apps.
        
        Getting started
        ===============
        
        PJAX requires cooperation between your front end (the Javascript that runs in
        your visitors' web browsers) and your Django back end.
        
        1. Set up the front end with jquery-pjax
        ----------------------------------------
        
        The front end is handled by the jquery-pjax library, so first of all, read about
        `how to use jQuery-PJAX`__ and pick one of the techniques there.
        
        __ https://github.com/defunkt/jquery-pjax
        
        2. Install DjPj on your server
        ------------------------------
        
        First, make sure the views you're PJAXing return TemplateResponse__. DjPj works
        by changing the way your templates are rendered, so it doesn't work with
        pre-rendered ``HttpResponse``s.
        
        __ https://docs.djangoproject.com/en/dev/ref/template-response/
        
        Install DjPj from PyPI::
        
            > pip install djpj
        
        3. Start using PJAX - basic usage examples
        ------------------------------------------
        
        Imagine you have a template, ``blog_post.html`` that looks like this::
        
            <head>
                <title>{{ blog_post_title }}</title>
            </head>
        
            ...
        
            <div id="blog_post">
            {% block blog_post %}
                ...
            {% endblock %}
            </article>
        
        Respond to PJAX requests to ``blog_post_view`` with the contents of the
        "blog_post" template block::
        
            @pjax_block("blog_post")
            def blog_post_view(request, ...)
                ...
                return TemplateResponse(request, "blog_post.html", context)
        
        If you want PJAX to correctly update the title of your page, include a
        ``title_block`` or ``title_variable`` argument to ``pjax_block``::
        
            @pjax_block("blog_post", title_variable="blog_post_title")
            def blog_post_view(request, ...)
                ...
        
        The "container" in PJAX parlance is the HTML element the contains the content
        you want to swap out. In the example above, the name of the block is the same
        as the id of the container element - they're both "blog_post". In these cases
        you can just omit the first argument entirely, and DjPj will look for a block
        whose name is the same as the container's id::
        
            @pjax_block(title_variable-"blog_post_title")
            def blog_post_view(request, ...)
                ...
        
        Use DjPj's middleware to enable PJAX without modifying your views
        -----------------------------------------------------------------
        
        If your site uses third-party views that you can't modify - for example, views
        defined by an ecommerce or CMS package - you can use DjPj's middleware instead
        of decorating views directly. This can also be handy when you have a number of
        views that you want to PJAXify which all share a common URL pattern.
        
        Here's what it looks like::
        
            # DjangoPJAXMiddleware should appear last in MIDDLEWARE_CLASSES
            MIDDLEWARE_CLASSES = (
                ...,
                "djpj.middleware.DjangoPJAXMiddleware",
            )
        
            DJPJ_PJAX_URLS = (
                ('^/blog/', '@pjax_block("blog_post", title_variable="blog_post_title")'),
            )
        
        Each entry in ``DJPJ_PJAX_URLS`` is a 2-tuple with the first element a regular
        expression matching the URLs you want to PJAXify, and the second a string
        containing Python code defining the decorator, just as it would be done in
        views.py.
        
        Using a different template for PJAX requests
        --------------------------------------------
        
        You can also use a specific template for PJAX requests, instead of returning a
        specific block. To do this, use the ``pjax_template`` decorator, and pass your
        PJAX template's name as the first argument::
        
            from djpj import pjax_template
        
            @pjax_template("pjax_template.html")
            def my_view(request)
                context = {"post_title": "My First Blog Post", ...}
                return TemplateResponse(request, "template.html", context)
        
        Your template should include a ``<title>`` tag if you want the title to be
        updated in the user's web browser.
        
        Customising the behaviour of DjPj
        =================================
        
        You can customise how DjPj selects blocks and templates by supplying your own
        functions to the ``pjax_block`` and ``pjax_template`` decorators. `Read more
        about that on GitHub.`__
        
        __ https://github.com/AlexHill/django-pjax-blocks/blob/master/DOCS.rst
        
        
        How does PJAX work?
        ===================
        
        Normally, when you click a link, your browser has to set up everything from
        scratch: HTML has to be parsed, scripts have to be compiled and executed,
        stylesheets interpreted and applied. It's a lot of work, and when you're
        browsing between different pages on the same website, much of this work is
        duplicated. It's like heating up a new skillet for every pancake.
        
        When a user clicks a link on your PJAX-enabled website, the server sends only
        the content that needs to change to display the new page. The fresh dollop of
        content drops into place in your page, and the browser doesn't have to do all
        the work associated with a full page load. To complete the trick, we manipulate
        the browser history to make the back and forward buttons work normally.
        
        
        Acknowledgements
        ================
        
        DjPj relies on defunkt's `jquery-pjax`__ – the canonical
        client-side PJAX library and the same one used by GitHub.
        
        __ https://github.com/defunkt/jquery-pjax
        
        DjPj was originally adapted from Jacob Kaplan-Moss' `Django-PJAX`__.
        
        __ https://github.com/jacobian/django-pjax
        
        Python and Django compatibility
        ===============================
        
        This package is tested in Django 1.4+ and Python 2.6, 2.7, 3.3+ and PyPy.
        
        Testing
        =======
        
        Tests are run using nose. To install::
        
            pip install nose
        
        And to run the tests::
        
            nosetests tests.py
        
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Programming Language :: Python
