django-smarter 1.1
Smarter declarative style generic views for Django.
Another approach for declarative style generic views for Django. I beleive, it’s a bit smarter :)
Overview
So many times we have to write:
@login_required def edit_post(request, pk): post = get_object_or_404(Post, pk=pk) if request.method == 'POST': form = EditPostForm(request.POST, instance=post) if form.is_valid(): post = form.save() return redirect(post.get_absolute_url()) else: form = EditPostForm() return render(request, 'edit_post.html', {'form': form})
Right? Well, it’s ok to write some reusable helpers for such repeatable views, but when we don’t need sophisticated ones here we go:
class PostViews(smarter.GenericViews): model = Post options = { 'add': { 'form': NewPostForm, 'decorators': (login_required,) }, 'edit': { 'form': EditPostForm, 'decorators': (login_required,) }, 'remove': { 'decorators': (login_required,) } }
That’s it.
Changes in v1.0
API is finally and completely changed since v0.6 release.
We’ve made a “quantum jump” by breaking old-and-not-so-good API to new one - solid and nice. Hope you’ll like it.
Here are some hints that may help you with migration. I’m actually successfully migrated my real-production project, so the hints are based on “real-battle” example.
Contributors
Thank you, comrades! :)
Installation
Requirements:
- Django >= 1.4
Installation:
pip install django-smarter
You may add smarter to your INSTALLED_APPS to get default templates and tests, but you don’t have to:
INSTALLED_APPS = ( # ... 'smarter', # ... )
Then you should define your views and include them in URLs, see Getting started section below.
Getting started
Create your models
Let’s define a simple model:
class Page(models.Model): owner = models.ForeignKey('auth.User') title = models.CharField(max_length=100) text = models.TextField() def __unicode__(self): return self.title
Register views
Now you can add generic views for the model.
In your urls.py:
import smarter from myapp.models import Page site = smarter.Site() site.register(smarter.GenericViews, Page) urlpatterns = patterns('', url(r'^', include(site.urls)), # other urls ... )
This code creates generic views for Page model, accessed by urls:
- /page/
- /page/add/
- /page/<pk>/
- /page/<pk>/edit/
- /page/<pk>/remove/
Customize views
Subclass from smarter.GenericViews and set custom options and/or override methods.
from django.contrib.auth.decorators import login_required import smarter from .models import Page class PageViews(smarter.GenericViews): model = Page options = { 'add': { 'decorators': (login_required,) 'exclude': ('owner',) }, } def add__save(self, request, form, **kwargs): obj = form.save(commit=False) obj.owner = request.user obj.save() return obj
And don’t forget to register new views in urls.py:
import smarter from myapp.views import PageViews site = smarter.Site() site.register(PageViews) # model argument is not required as model is already set in PageViews urlpatterns = patterns('', url(r'^', include(site.urls)), )
Customize templates
In the example above each URL by default to template.
Default template search paths are:
('%(app)s/%(model)s/%(action)s.html', '%(app)s/%(model)s/%(action)s.ajax.html', 'smarter/%(action)s.html', 'smarter/_form.html', 'smarter/_ajax.html',)
So, you have some easy way options:
Singleton Site
A very special instance of smarter.Site is in the smarter module. It allows you to register your applications’ views outside your urls.py file, and works well with autodiscover().
Here is smarter_views.py in your app:
from smarter import site, GenericViews from models import Model class Views(GenericViews): model = Model # ... site.register(Views)
… And urls.py:
from django.conf.urls import patterns, include, url import smarter smarter.autodiscover() urlpatterns = patterns('', url(r'^', include(smarter.site.urls)), )
This is mostly recommended for non-reusable applications local to your Django project.
API reference
Actions
Actions are actually “ids” for views. Well, each action has id like ‘add’, ‘edit’, ‘bind-to-user’ and is mapped to view method with underscores instead of ‘-‘: add, edit, bind_to_user.
In smarter.GenericViews class such actions are defined by default:
What is [prefix]? Prefix is defined for smarter.Site instance:
site = smarter.Site(prefix='myapp') site.register(PageViews) # ...
So, it can be empty and URL names without prefix are defined as [model]-index. Please, read Reversing urls section for more details.
Options
Options is a GenericViews.options dict, class property, it contains actions names as keys and actions parameters as values. Parameters structure is:
{ 'url': <string for url pattern>, 'form': <form class>, 'decorators': <tuple/list of decorators>, 'fields': <tuple/list of form fields>, 'exclude': <tuple/list of excluded form fields>, 'initial': <tuple/list of form fields initialized by request.GET>, 'permissions': <tuple/list of required permissions>, 'widgets': <dict for widgets overrides>, 'help_text': <dict for help texts overrides>, 'required': <dict for required fields overrides>, 'template': <string template name>, 'redirect': <string or callable returning redirect path> }
Every key here is optional. So, here’s how options can be defined for views:
import smarter class Views(smarter.GenericViews): model = <model> defaults = <default parameters> options = { '<action 1>': <parameters 1>, '<action 2>': <parameters 2> }
And here’s GenericViews.defaults class attribute:
defaults = { 'initial': None, 'form': ModelForm, 'exclude': None, 'fields': None, 'labels': None, 'widgets': None, 'required': None, 'help_text': None, 'next': None, 'template': ( '%(app)s/%(model)s/%(action)s.html', '%(app)s/%(model)s/%(action)s.ajax.html', 'smarter/%(action)s.html', 'smarter/_form.html', 'smarter/_ajax.html',), 'decorators': None, 'permissions': None, }
When option value can’t be found in options dict for action it’s searched in GenericViews.defaults. Note, that defaults are applied to all actions.
Action names and URLs
Actions are named so they can be mapped to views methods and they should not override reserved attributes and methods, so they:
- must contain only latin symbols and ‘_’ or ‘-‘, no spaces
- can’t be in this list: ‘model’, ‘defaults’, ‘options’, ‘deny’
- can’t start with ‘-‘, ‘_’ or ‘get_’
- can’t contain ‘__’
Sure, you’ll get an exception if something goes wrong with that. We’re following ‘errors should never pass silently’ here.
And here’s how URLs for default views are defined:
{ 'index': { 'url': r'', }, 'details': { 'url': r'(?P<pk>\d+)/', }, 'add': { 'url': r'add/', }, 'edit': { 'url': r'(?P<pk>\d+)/edit/', }, 'remove': { 'url': r'(?P<pk>\d+)/remove/', } }
smarter.Site
Site
Constructor gets two keyword arguments:
- prefix=None, for prefixing URL names for views registered with site object, like ‘%(prefix)s-%(model)s-%(action)s’. If prefix if empty, URLs are named without prefix, like ‘%(model)s-%(action)s’.
- delim=’-‘, delimiter for URL names, can be ‘-‘, ‘_’ or empty string. URL names are composed with specified delimiter and with uderscore it would be like ‘%(prefix)s_%(model)s_%(action)s’.
Site.register
This method gets 1 required argument for views class and optional keyword arguments:
- model=None, model class for views. This argument is required if views class doesn’t have ‘model’ property.
- base_url=None, base URL for views. If empty, then lower-case model name is used, so base URL becomes ‘%(model)s/’.
- prefix=None, prefix for URL names. If empty, then lower-case model name is used.
smarter.GenericViews
Pipeline
Each action like ‘add’, ‘edit’ or ‘remove’ is a pipeline: a sequence (list) of methods called one after another. A result of each method is passed to the next one.
The result is either None or dict or HttpResponse object:
- None - result from previous pipeline method is used for next one,
- dict - result is passed to next pipeline method,
- HttpResponse - returned immidiately as view response.
For example, ‘edit’ action pipeline is: ‘edit’ -> ‘edit__perm’ -> ‘edit__form’ -> ‘edit__post’ -> ‘edit__done’.
Note about __perm step. Basic permissions are checked before pipeline start view (e.g ‘edit’), as if view were decorated with permission_required decorator. Actualy we’re not using decorator, because we need to call our custom deny() method if permissions are not sufficient, but it’s not the key. The key is you don’t need to check basic permissions in custom __perm method, it’s necessary for per-object permissions checks.
Note, that in general you won’t need to redefine pipeline methods, as in many cases custom behavior can be reached with declarative style using options. If you’re going too far with overriding views, that may mean you’d better write some views from scratch separate from “smarter”.
Reversing URLs
Every action mapped to named URL. Names are composed as:
[site prefix][delimiter][views prefix][delimiter][action]
Where:
- site prefix is ‘prefix’ parameter in smarter.Site constructor
- delimiter is ‘delim’ paratemer in smarter.Site constructor
- views prefix is ‘prefix’ parameter in Site.register method
So, in Getting started example named URLs are ‘page-add’, ‘page-edit’, ‘page-remove’, etc., as we don’t provide any custom prefixes and delimiter is ‘-‘ by default.
Pipeline example
For deeper understanding here’s an example of custom pipeline for ‘edit’ action. It’s not actually a recommended way, as we can reach the same effect without overriding edit method by defining options['edit']['initial'], but it illustrates the principle of pipeline.
import smarter class PageViews(smarter.GenericViews): model = Page def edit(request, pk=None): # Custom initial title initial = {'title': request.GET.get('title': '')} return { 'obj': self.get_object(request, pk=pk), 'form' {'initial': initial, 'instance': obj} } def edit__perm(request, **kwargs): # Custom permission check if kwargs['obj'].owner != request.user: return self.deny(request) def edit__form(request, **kwargs): # Actually, nothing custom here, it's totally generic: # we should validate & save form and then return dict # with 'form_saved' set to True if it's ok. kwargs['form'] = self.get_form(request, **kwargs) if kwargs['form'].is_valid(): kwargs['obj'] = self.edit__save(request, **kwargs) kwargs['form_saved'] = True return kwargs def edit__done(request, obj=None, form=None, form_saved=None): # Custom redirect to pages index on success if form_saved: # Success, redirecting! return redirect(self.get_url('index')) else: # Start edit or form has errors return render(request, self.get_template(request), {'obj': obj, 'form': form})
Complete example
License
Copyright (c) 2013, Alexey Kinyov <rudy@05bit.com> Licensed under BSD, see LICENSE for more details.
- Downloads (All Versions):
- 16 downloads in the last day
- 99 downloads in the last week
- 335 downloads in the last month
- Author: Alexey Kinyov
- Keywords: django,application,scaffolding,crud,views,utility
- License: BSD
- Categories
- Package Index Owner: Alexey.Kinyov
- DOAP record: django-smarter-1.1.xml