Initial thoughts on a Linkable Model class. Please comment.
Patch by: Todd Larsen
==================Django at a glance==================Because Django was developed in a fast-paced newsroom environment, it wasdesigned to make common Web-development tasks fast and easy. Here's an informaloverview of how to write a database-driven Web app with Django.The goal of this document is to give you enough technical specifics tounderstand how Django works, but this isn't intended to be a tutorial orreference. Please see our more-detailed Django documentation_ when you're readyto start a project... _documentation: ../Design your model=================Although you can use Django without a database, it comes with anobject-relational mapper in which you describe your database layout in Pythoncode.The data-model syntax offers many rich ways of representing your models -- sofar, it's been solving two years' worth of database-schema problems. Here's aquick example:: class Reporter(models.Model): full_name = models.CharField(maxlength=70) def __str__(self): return self.full_name class Article(models.Model): pub_date = models.DateTimeField() headline = models.CharField(maxlength=200) article = models.TextField() reporter = models.ForeignKey(Reporter) def __str__(self): return self.headlineInstall it==========Next, run the Django command-line utility to create the database tablesautomatically:: manage.py syncdbThe ``syncdb`` command looks at all your available models and creates tablesin your database for whichever tables don't already exist.Enjoy the free API==================With that, you've got a free, and rich, Python API to access your data. The APIis created on the fly: No code generation necessary:: >>> from mysite.models import Reporter, Article # No reporters are in the system yet. >>> Reporter.objects.all() [] # Create a new Reporter. >>> r = Reporter(full_name='John Smith') # Save the object into the database. You have to call save() explicitly. >>> r.save() # Now it has an ID. >>> r.id 1 # Now the new reporter is in the database. >>> Reporter.objects.all() [John Smith] # Fields are represented as attributes on the Python object. >>> r.full_name 'John Smith' # Django provides a rich database lookup API. >>> Reporter.objects.get(id=1) John Smith >>> Reporter.objects.get(full_name__startswith='John') John Smith >>> Reporter.objects.get(full_name__contains='mith') John Smith >>> Reporter.objects.get(id=2) Traceback (most recent call last): ... DoesNotExist: Reporter does not exist for {'id__exact': 2} # Create an article. >>> from datetime import datetime >>> a = Article(pub_date=datetime.now(), headline='Django is cool', ... article='Yeah.', reporter=r) >>> a.save() # Now the article is in the database. >>> Article.objects.all() [Django is cool] # Article objects get API access to related Reporter objects. >>> r = a.reporter >>> r.full_name 'John Smith' # And vice versa: Reporter objects get API access to Article objects. >>> r.article_set.all() [Django is cool] # The API follows relationships as far as you need, performing efficient # JOINs for you behind the scenes. # This finds all articles by a reporter whose name starts with "John". >>> Article.objects.filter(reporter__full_name__startswith="John") [Django is cool] # Change an object by altering its attributes and calling save(). >>> r.full_name = 'Billy Goat' >>> r.save() # Delete an object with delete(). >>> r.delete()A dynamic admin interface: It's not just scaffolding -- it's the whole house============================================================================Once your models are defined, Django can automatically create a professional,production ready administrative interface -- a Web site that lets authenticatedusers add, change and delete objects. It's as easy as adding a line of code toyour model classes:: class Article(models.Model): pub_date = models.DateTimeField() headline = models.CharField(maxlength=200) article = models.TextField() reporter = models.ForeignKey(Reporter) class Admin: passThe philosophy here is that your site is edited by a staff, or a client, ormaybe just you -- and you don't want to have to deal with creating backendinterfaces just to manage content.One typical workflow in creating Django apps is to create models and get theadmin sites up and running as fast as possible, so your staff (or clients) canstart populating data. Then, develop the way data is presented to the public.Design your URLs================A clean, elegant URL scheme is an important detail in a high-quality Webapplication. Django encourages beautiful URL design and doesn't put any cruftin URLs, like ``.php`` or ``.asp``.To design URLs for an app, you create a Python module called a URLconf. A tableof contents for your app, it contains a simple mapping between URL patterns andPython callback functions. URLconfs also serve to decouple URLs from Pythoncode.Here's what a URLconf might look like for the ``Reporter``/``Article``example above:: from django.conf.urls.defaults import * urlpatterns = patterns('', (r'^/articles/(\d{4})/$', 'mysite.views.year_archive'), (r'^/articles/(\d{4})/(\d{2})/$', 'mysite.views.month_archive'), (r'^/articles/(\d{4})/(\d{2})/(\d+)/$', 'mysite.views.article_detail'), )The code above maps URLs, as simple regular expressions, to the location ofPython callback functions ("views"). The regular expressions use parenthesis to"capture" values from the URLs. When a user requests a page, Django runsthrough each pattern, in order, and stops at the first one that matches therequested URL. (If none of them matches, Django calls a special-case 404 view.)This is blazingly fast, because the regular expressions are compiled at loadtime.Once one of the regexes matches, Django imports and calls the given view, whichis a simple Python function. Each view gets passed a request object --which contains request metadata -- and the values captured in the regex.For example, if a user requested the URL "/articles/2005/05/39323/", Djangowould call the function ``mysite.views.article_detail(request,'2005', '05', '39323')``.Write your views================Each view is responsible for doing one of two things: Returning an``HttpResponse`` object containing the content for the requested page, orraising an exception such as ``Http404``. The rest is up to you.Generally, a view retrieves data according to the parameters, loads a templateand renders the template with the retrieved data. Here's an example view for``year_archive`` from above:: def year_archive(request, year): a_list = Article.objects.filter(pub_date__year=year) return render_to_response('news/year_archive.html', {'year': year, 'article_list': a_list})This example uses Django's template system, which has several powerfulfeatures but strives to stay simple enough for non-programmers to use.Design your templates=====================The code above loads the ``news/year_archive.html`` template.Django has a template search path, which allows you to minimize redundancy amongtemplates. In your Django settings, you specify a list of directories to checkfor templates. If a template doesn't exist in the first directory, it checks thesecond, and so on.Let's say the ``news/article_detail.html`` template was found. Here's what thatmight look like:: {% extends "base.html" %} {% block title %}Articles for {{ year }}{% endblock %} {% block content %} <h1>Articles for {{ year }}</h1> {% for article in article_list %} <p>{{ article.headline }}</p> <p>By {{ article.reporter.full_name }}</p> <p>Published {{ article.pub_date|date:"F j, Y" }}</p> {% endfor %} {% endblock %}Variables are surrounded by double-curly braces. ``{{ article.headline }}``means "Output the value of the article's headline attribute." But dots aren'tused only for attribute lookup: They also can do dictionary-key lookup, indexlookup and function calls.Note ``{{ article.pub_date|date:"F j, Y" }}`` uses a Unix-style "pipe" (the "|"character). This is called a template filter, and it's a way to filter the valueof a variable. In this case, the date filter formats a Python datetime object inthe given format (as found in PHP's date function; yes, there is one good ideain PHP).You can chain together as many filters as you'd like. You can write customfilters. You can write custom template tags, which run custom Python code behindthe scenes.Finally, Django uses the concept of "template inheritance": That's what the``{% extends "base.html" %}`` does. It means "First load the template called'base', which has defined a bunch of blocks, and fill the blocks with thefollowing blocks." In short, that lets you dramatically cut down on redundancyin templates: Each template has to define only what's unique to that template.Here's what the "base.html" template might look like:: <html> <head> <title>{% block title %}{% endblock %}</title> </head> <body> <img src="sitelogo.gif" alt="Logo" /> {% block content %}{% endblock %} </body> </html>Simplistically, it defines the look-and-feel of the site (with the site's logo),and provides "holes" for child templates to fill. This makes a site redesign aseasy as changing a single file -- the base template.It also lets you create multiple versions of a site, with different basetemplates, while reusing child templates. Django's creators have used thistechnique to create strikingly different cell-phone editions of sites -- simplyby creating a new base template.Note that you don't have to use Django's template system if you prefer anothersystem. While Django's template system is particularly well-integrated withDjango's model layer, nothing forces you to use it. For that matter, you don'thave to use Django's database API, either. You can use another databaseabstraction layer, you can read XML files, you can read files off disk, oranything you want. Each piece of Django -- models, views, templates -- isdecoupled from the next.This is just the surface========================This has been only a quick overview of Django's functionality. Some more usefulfeatures: * A caching framework that integrates with memcached or other backends. * A syndication framework that makes creating RSS and Atom feeds as easy as writing a small Python class. * More sexy automatically-generated admin features -- this overview barely scratched the surface.The next obvious steps are for you to `download Django`_, read `the tutorial`_and join `the community`_. Thanks for your interest!.. _download Django: http://www.djangoproject.com/download/.. _the tutorial: http://www.djangoproject.com/documentation/tutorial1/.. _the community: http://www.djangoproject.com/community/