django-subview 0.1

Treat Django views as reusable and generic components

django-subview
==============

django_subview is a module to include complete views with application logic into templates
and to retrieve them by a single, generic url.

What is this for?
-----------------

In the AJAX world, there are often parts in a page, that contain an own, self-contained and reusable application logic.
Call it pagelet, portlet, partial, subcontroller, ... we call it subview,
corresponding to Djangos Model/View/Template structure.
This is because it is just a normal view that is included into the response of another view.

Example use case:
Imagine the frontpage of a blog page. A module with the latest 5 comments should reload every minute.
1. This module should be included in the frontpage
2. It has to be rendered "standalone" for an AJAX request

Include view in template
------------------------
A view can simply included in a template as shown below.

{% subview "path.to.some_view" name1=value1 name2=value2 %}

The first argument is a path to a view. It can be an absolute Python path
or just ``app_name.view_name`` without the project name if the view is
located inside the project.

View parameters are space-separated values that are passed to the view function.
Only keyword arguments are supported. All arguments for the view should be present or have default values.

For example if you have a view ``app_name.latestcomments`` taking client's id and
the view has the following signature:

def latestcomments(request, amount):

then in a template you can call the subview for a certain client like this::

{% subview "app_name.latestcomments" amount=5 %}

Call view with generic URL
--------------------------

### What is this for? ###

Often, subviews are reusable, self contained components and are not intended to be opened standalone in a browser.
So you don't have to define a url for each view but can access it from your ajax app through a generic URL.

### Example ###

You have to include the bundled urlpatterns in your root urlconf like this:

urlpatterns = patterns('',
url(r'^subview', include('subview.urls')),
)

Now you simply can request a view from your browser like:

http://127.0.0.1:8000/subview/myapp.views.latestcomments/{"amount":"5"}?some=parameter

Please bear in mind that this excample is not urlencoded for readability. The real request should look like:

http://127.0.0.1:8000/subview/myapp.views.latestcomments/%7B"amount":"5"%7D?some=parameter

GET and POST parameters aren't affected in any way. This means you can use and access
them as usual from within your view / subview.