Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

More doc improvments: moved overview into doc system so it can be dis…

…tributed with the package, and fixed a few spelling errors in templates doc (fixes #31).

git-svn-id: http://code.djangoproject.com/svn/django/trunk@49 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 0f40f3b757f51c5d1e006364291f89cc754b81bf 1 parent f7d619e
Jacob Kaplan-Moss jacobian authored
Showing with 312 additions and 3 deletions.
  1. +308 −0 docs/overview.txt
  2. +4 −3 docs/templates.txt
308 docs/overview.txt
View
@@ -0,0 +1,308 @@
+===============
+Django overview
+===============
+
+Because Django was developed in a fast-paced newsroom environment, it was
+designed to make common Web-development tasks fast and easy. Here's an informal
+overview of how to write a database-driven Web app with Django.
+
+The goal of this document is to give you enough technical specifics to
+understand how Django works, but this isn't intended to be a tutorial or
+reference. Please see our more-detailed Django documentation_ when you're ready
+to start a project.
+
+.. _documentation: http://www.djangoproject.com/documentation/
+
+Design your model
+=================
+
+Start by describing your database layout in Python code. Django's data-model API
+offers many rich ways of representing your models — so far, it's been
+solving two years' worth of database-schema problems. Here's a quick example::
+
+ class Reporter(meta.Model):
+ fields = (
+ meta.CharField('full_name', "reporter's full name", maxlength=70),
+ )
+
+ def __repr__(self):
+ return self.full_name
+
+ class Article(meta.Model):
+ fields = (
+ meta.DateTimeField('pub_date', 'publication date'),
+ meta.CharField('headline', 'headline', maxlength=200),
+ meta.TextField('article', 'article'),
+ meta.ForeignKey(Reporter),
+ )
+
+ def __repr__(self):
+ return self.headline
+
+Install it
+==========
+
+Next, run the Django command-line utility. It'll create the database tables for
+you automatically, in the database specified in your Django settings. Django
+works with PostgreSQL and MySQL, although other database adapters are on the
+way::
+
+ django-admin.py install news
+
+Enjoy the free API
+==================
+
+With that, you've got a free, and rich, Python API to access your data. The API
+is created on the fly: No code generation necessary::
+
+ # Modules are dynamically created within django.models.
+ # Their names are plural versions of the model class names.
+ >>> from django.models.news import reporters, articles
+
+ # No reporters are in the system yet.
+ >>> reporters.get_list()
+ []
+
+ # Create a new Reporter.
+ >>> r = reporters.Reporter(id=None, 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.
+ >>> reporters.get_list()
+ [John Smith]
+
+ # Fields are represented as attributes on the Python object.
+ >>> r.full_name
+ 'John Smith'
+
+ # Django provides a rich database lookup API that's entirely driven by keyword arguments.
+ >>> reporters.get_object(id__exact=1)
+ John Smith
+ >>> reporters.get_object(full_name__startswith='John')
+ John Smith
+ >>> reporters.get_object(full_name__contains='mith')
+ John Smith
+ >>> reporters.get_object(id__exact=2)
+ Traceback (most recent call last):
+ ...
+ django.models.polls.ReporterDoesNotExist: Reporter does not exist for {'id__exact': 2}
+
+ # Create an article.
+ >>> from datetime import datetime
+ >>> a = articles.Article(id=None, pub_date=datetime.now(), headline='Django is cool', article='Yeah.', reporter_id=1)
+ >>> a.save()
+
+ # Now the article is in the database.
+ >>> articles.get_list()
+ [Django is cool]
+
+ # Article objects get API access to related Reporter objects.
+ >>> r = a.get_reporter()
+ >>> r.full_name
+ 'John Smith'
+
+ # And vice versa: Reporter objects get API access to Article objects.
+ >>> r.get_article_list()
+ [Django is cool]
+
+ # The API follows relationships as far as you need.
+ # Find all articles by a reporter whose name starts with "John".
+ >>> articles.get_list(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 an administrative
+interface — a Web site that lets authenticated users add, change and
+delete objects. It's as easy as adding an extra admin attribute to your model
+classes::
+
+ class Article(meta.Model):
+ fields = (
+ meta.DateTimeField('pub_date', 'publication date'),
+ meta.CharField('headline', 'headline', maxlength=200),
+ meta.TextField('article', 'article'),
+ meta.ForeignKey(Reporter),
+ )
+ admin = meta.Admin(
+ fields = (
+ (None, {'fields': ('headline', 'article')}),
+ ('Extra stuff', {'fields': ('pub_date', 'reporter_id')}),
+ ),
+ )
+
+The ``admin.fields`` defines the layout of your admin form. Each element in the
+fields tuple corresponds to a ``<fieldset>`` in the form.
+
+The philosophy here is that your site is edited by a staff, or a client, or
+maybe just you -- and you don't want to have to deal with creating backend
+interfaces just to manage content.
+
+Our typical workflow at World Online is to create models and get the admin sites
+up and running as fast as possible, so our staff journalists can start
+populating data. Then we 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 Web
+application. Django lets you design URLs however you want, with no framework
+limitations.
+
+To design URLs for an app, you create a Python module. For the above
+Reporter/Article example, here's what that might look like::
+
+ from django.conf.urls.defaults import *
+
+ urlpatterns = patterns('',
+ (r'^/articles/(?P\d{4})/$', 'myproject.news.views.articles.year_archive'),
+ (r'^/articles/(?P\d{4})/(?P\d{2})/$', 'myproject.news.views.articles.month_archive'),
+ (r'^/articles/(?P\d{4})/(?P\d{2})/$', 'myproject.news.views.articles.month_archive'),
+ (r'^/articles/(?P\d{4})/(?P\d{2})/(?P\d+)/$', 'myproject.news.views.articles.article_detail'),
+ )
+
+
+The code above maps URLs, as regular expressions, to the location of Python
+callback functions (views). The regular expressions use parenthesis to "capture"
+values from the URLs. When a user requests a page, Django runs through each
+regular expression, in order, and stops at the first one that matches the
+requested URL. (If none of them matches, Django calls a special 404 view.) This
+is blazingly fast, because the regular expressions are compiled at load time.
+
+Once one of the regexes matches, Django imports and calls the given view, which
+is a simple Python function. Each view gets passed a request object —
+which contains request metadata and lets you access GET and POST data as simple
+dictionaries — and the values captured in the regex, via keyword
+arguments.
+
+For example, if a user requested the URL "/articles/2005/05/39323/", Django
+would call the function ``myproject.news.views.articles.article_detail(request,
+year='2005', month='05', article_id='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, or
+raising an exception such as ``Http404``. The rest is up to you.
+
+Generally, a view retrieves data according to the parameters, loads a template
+and renders the template with the retrieved data. Here's an example view for
+article_detail from above::
+
+ from django.models.news import articles
+
+ def article_detail(request, year, month, article_id):
+ # Use the Django API to find an object matching the URL criteria.
+ try:
+ a = articles.get_object(pub_date__year=year, pub_date__month=month, id__exact=article_id)
+ except articles.ArticleDoesNotExist:
+ raise Http404
+ t = template_loader.get_template('news/article_detail')
+ c = Context(request, {
+ 'article': a,
+ })
+ content = t.render(c)
+ return HttpResponse(content)
+
+This example uses Django's template system, which has several key features.
+
+Design your templates
+=====================
+
+The code above loads the ``news/article_detail`` template.
+
+Django has a template search path, which allows you to minimize redundancy among
+templates. In your Django settings, you specify a list of directories to check
+for templates. If a template doesn't exist in the first directory, it checks the
+second, and so on.
+
+Let's say the ``news/article_detail`` template was found. Here's what that might
+look like::
+
+ {% extends "base" %}
+
+ {% block title %}{{ article.headline }}{% endblock %}
+
+ {% block content %}
+ <h1>{{ article.headline }}</h1>
+ <p>By {{ article.get_reporter.full_name }}</p>
+ <p>Published {{ article.pub_date|date:"F j, Y" }}</p>
+ {{ article.article }}
+ {% endblock %}
+
+
+It should look straightforward. Variables are surrounded by double-curly braces.
+``{{ article.headline }}`` means "Output the value of the article's headline
+attribute." But dots aren't used only for attribute lookup: They also can do
+dictionary-key lookup, index lookup and function calls (as is the case with
+``article.get_reporter``).
+
+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 value
+of a variable. In this case, the date filter formats a Python datetime object in
+the given format (as found in PHP's date function; yes, there is one good idea
+in PHP).
+
+You can chain together as many filters as you'd like. You can write custom
+filters. You can write custom template tags, which run custom Python code behind
+the scenes.
+
+Finally, Django uses the concept of template inheritance: That's what the ``{%
+extends "base" %}`` does. It means "First load the template called 'base', which
+has defined a bunch of blocks, and fill the blocks with the following blocks."
+In short, that lets you dramatically cut down on redundancy in templates: Each
+template has to define only what's unique to that template.
+
+Here's what the "base" template might look like::
+
+
+ <html>
+ <head>
+ <title>{% block title %}</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 as
+easy as changing a single file — the base template.
+
+Note that you don't have to use Django's template system if you prefer another
+system. While Django's template system is particularly well-integrated with
+Django's model layer, nothing forces you to use it. For that matter, you don't
+have to use Django's API, either. You can use another database abstraction
+layer, you can read XML files, you can read files off disk, or anything you
+want. Each piece of Django — models, views, templates — is decoupled
+from the next.
+
+This is just the surface
+========================
+
+This has been only a quick overview of Django's functionality. Some more useful
+features:
+
+ * A caching framework that integrates with memcached or other backends.
+ * An RSS framework that makes creating RSS 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 documentation
+and join the community. Thanks for your interest!
7 docs/templates.txt
View
@@ -21,7 +21,8 @@ To actually be useful, a template will contain **variables**, which get replaced
with values from the database when the template is evaluated, and **tags**,
which control the logic of the template.
-Below is a minimal template that I'll be using to illustrate the parts of a template throughout this introduction::
+Below is a minimal template that I'll be using to illustrate the parts of a
+template throughout this introduction::
{% extends base_generic %}
@@ -47,7 +48,7 @@ Variables look like this: ``{{ variable }}``. When the template engine
encounters a variable, it evaluates that variable and replaces the variable with
the result. Many variables will be structures with named attributes; you can
"drill down" into these structures with dots (``.``), so in the above example ``
-{{ section.title }}`` will be replaces with the ``title`` attribute of the
+{{ section.title }}`` will be replaced with the ``title`` attribute of the
``section`` object.
If you use a variable that doesn't exist, it will be silently ignored; the
@@ -61,7 +62,7 @@ Variables may be modified before being displayed by **filters**.
What's a filter?
================
-Filters look like this: ``{{ name|lower }}``. This display the value of the
+Filters look like this: ``{{ name|lower }}``. This displays the value of the
``{{ name }}`` variable after being filtered through the ``lower`` filter which,
as you might have guessed, lowercases the text passed through it.
Please sign in to comment.
Something went wrong with that request. Please try again.