p15693087
/
django
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Fixed #15335 -- Improved Sphinx crossref targets and metadata for the sites and flatpages reference docs. 

git-svn-id: http://code.djangoproject.com/svn/django/trunk@15562 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Gabriel Hurley 2011-02-18 00:58:34 +00:00
parent f81d5d6854
commit fe1110018a
2 changed files with 83 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
docs/ref/contrib/flatpages.txt
View File

@ -47,6 +47,8 @@ To install the flatpages app, follow these steps:
4. Run the command :djadmin:`manage.py syncdb <syncdb>`.
.. currentmodule:: django.contrib.flatpages.middleware
How it works
============
@ -56,25 +58,29 @@ that simply maps a URL to a title and bunch of text content.
``django_flatpage_sites`` associates a flatpage with a site.
The :class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware`
does all of the work. Each time any Django application raises a 404 error, this
middleware checks the flatpages database for the requested URL as a last resort.
Specifically, it checks for a flatpage with the given URL with a site ID that
corresponds to the :setting:`SITE_ID` setting.
does all of the work.
If it finds a match, it follows this algorithm:
.. class:: FlatpageFallbackMiddleware
* If the flatpage has a custom template, it loads that template. Otherwise,
it loads the template :file:`flatpages/default.html`.
Each time any Django application raises a 404 error, this middleware
checks the flatpages database for the requested URL as a last resort.
Specifically, it checks for a flatpage with the given URL with a site ID
that corresponds to the :setting:`SITE_ID` setting.
* It passes that template a single context variable, :data:`flatpage`, which
is the flatpage object. It uses
:class:`~django.template.context.RequestContext` in rendering the
template.
If it finds a match, it follows this algorithm:
If it doesn't find a match, the request continues to be processed as usual.
* If the flatpage has a custom template, it loads that template.
Otherwise, it loads the template :file:`flatpages/default.html`.
The middleware only gets activated for 404s -- not for 500s or responses of any
other status code.
* It passes that template a single context variable, ``flatpage``,
which is the flatpage object. It uses
:class:`~django.template.RequestContext` in rendering the
template.
If it doesn't find a match, the request continues to be processed as usual.
The middleware only gets activated for 404s -- not for 500s or responses
of any other status code.
.. admonition:: Flatpages will not apply view middleware
@ -104,6 +110,8 @@ For more on middleware, read the :doc:`middleware docs
:class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware`
will not attempt to serve a flat page.
.. currentmodule:: django.contrib.flatpages.models
How to add, change and delete flatpages
=======================================
@ -117,7 +125,7 @@ other object in the system.
Via the Python API
------------------
.. class:: models.FlatPage
.. class:: FlatPage
Flatpages are represented by a standard
:doc:`Django model </topics/db/models>`,
@ -126,6 +134,8 @@ Via the Python API
.. _django/contrib/flatpages/models.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/flatpages/models.py
.. currentmodule:: django.contrib.flatpages
Flatpage templates
==================
@ -141,7 +151,7 @@ Creating the :file:`flatpages/default.html` template is your responsibility;
in your template directory, just create a :file:`flatpages` directory
containing a file :file:`default.html`.
Flatpage templates are passed a single context variable, :data:`flatpage`,
Flatpage templates are passed a single context variable, ``flatpage``,
which is the flatpage object.
Here's a sample :file:`flatpages/default.html` template:
@ -164,7 +174,7 @@ both ``flatpage.title`` and ``flatpage.content`` are marked as **not**
requiring :ref:`automatic HTML escaping <automatic-html-escaping>` in the
template.
Getting a list of :class:`~django.contrib.flatpages.models.Flatpage` objects in your templates
Getting a list of :class:`~django.contrib.flatpages.models.FlatPage` objects in your templates
==============================================================================================
.. versionadded:: 1.3
@ -194,7 +204,7 @@ Displaying ``registration_required`` flatpages
----------------------------------------------
By default, the :ttag:`get_flatpages` templatetag will only show
flatpages that are marked :attr:`registration_required`\=False. If you
flatpages that are marked ``registration_required = False``. If you
want to display registration-protected flatpages, you need to specify
an authenticated user using a``for`` clause.

74
docs/ref/contrib/sites.txt
View File

@ -6,6 +6,8 @@ The "sites" framework
:synopsis: Lets you operate multiple Web sites from the same database and
Django project
.. currentmodule:: django.contrib.sites.models
Django comes with an optional "sites" framework. It's a hook for associating
objects and functionality to particular Web sites, and it's a holding place for
the domain names and "verbose" names of your Django-powered sites.
@ -15,13 +17,21 @@ need to differentiate between those sites in some way.
The whole sites framework is based on a simple model:
.. class:: django.contrib.sites.models.Site
.. class:: Site
A model for storing the ``domain`` and ``name`` attributes of a Web site.
The :setting:`SITE_ID` setting specifies the database ID of the
:class:`~django.contrib.sites.models.Site` object associated with that
particular settings file.
.. attribute:: domain
The domain name associated with the Web site.
.. attribute:: name
A human-readable "verbose" name for the Web site.
This model has :attr:`~django.contrib.sites.models.Site.domain` and
:attr:`~django.contrib.sites.models.Site.name` fields. The :setting:`SITE_ID`
setting specifies the database ID of the
:class:`~django.contrib.sites.models.Site` object associated with that
particular settings file.
How you use this is up to you, but Django uses it in a couple of ways
automatically via simple conventions.
@ -85,9 +95,10 @@ This accomplishes several things quite nicely:
Associating content with a single site
--------------------------------------
Similarly, you can associate a model to the :class:`~django.contrib.sites.models.Site`
Similarly, you can associate a model to the
:class:`~django.contrib.sites.models.Site`
model in a many-to-one relationship, using
:class:`~django.db.models.fields.related.ForeignKey`.
:class:`~django.db.models.ForeignKey`.
For example, if an article is only allowed on a single site, you'd use a model
like this::
@ -158,6 +169,15 @@ the sites framework is installed) or a RequestSite instance (if it is not).
This allows loose coupling with the sites framework and provides a usable
fallback for cases where it is not installed.
.. versionadded:: 1.3
.. function:: get_current_site(request)
Checks if contrib.sites is installed and returns either the current
:class:`~django.contrib.sites.models.Site` object or a
:class:`~django.contrib.sites.models.RequestSite` object based on
the request.
Getting the current domain for display
--------------------------------------
@ -260,10 +280,12 @@ clear the cache using ``Site.objects.clear_cache()``::
Site.objects.clear_cache()
current_site = Site.objects.get_current()
.. currentmodule:: django.contrib.sites.managers
The ``CurrentSiteManager``
==========================
.. class:: django.contrib.sites.managers.CurrentSiteManager
.. class:: CurrentSiteManager
If :class:`~django.contrib.sites.models.Site` plays a key role in your
application, consider using the helpful
@ -300,9 +322,9 @@ How did :class:`~django.contrib.sites.managers.CurrentSiteManager`
know which field of ``Photo`` was the
:class:`~django.contrib.sites.models.Site`? By default,
:class:`~django.contrib.sites.managers.CurrentSiteManager` looks for a
either a :class:`~django.db.models.fields.related.ForeignKey` called
either a :class:`~django.db.models.ForeignKey` called
``site`` or a
:class:`~django.db.models.fields.related.ManyToManyField` called
:class:`~django.db.models.ManyToManyField` called
``sites`` to filter on. If you use a field named something other than
``site`` or ``sites`` to identify which
:class:`~django.contrib.sites.models.Site` objects your object is
@ -325,7 +347,7 @@ demonstrates this::
on_site = CurrentSiteManager('publish_on')
If you attempt to use :class:`~django.contrib.sites.managers.CurrentSiteManager`
and pass a field name that doesn't exist, Django will raise a :exc:`ValueError`.
and pass a field name that doesn't exist, Django will raise a ``ValueError``.
Finally, note that you'll probably want to keep a normal
(non-site-specific) ``Manager`` on your model, even if you use
@ -379,7 +401,7 @@ Here's how Django uses the sites framework:
:class:`~django.contrib.sites.models.Site` name to the template as
``{{ site_name }}``.
* The shortcut view (:func:`django.views.defaults.shortcut`) uses the domain
* The shortcut view (``django.views.defaults.shortcut``) uses the domain
of the current :class:`~django.contrib.sites.models.Site` object when
calculating an object's URL.
@ -387,6 +409,7 @@ Here's how Django uses the sites framework:
:class:`~django.contrib.sites.models.Site` to work out the domain for the
site that it will redirect to.
.. currentmodule:: django.contrib.sites.models
``RequestSite`` objects
=======================
@ -401,13 +424,26 @@ requires.) For those cases, the framework provides a
:class:`~django.contrib.sites.models.RequestSite` class, which can be used as a
fallback when the database-backed sites framework is not available.
.. class:: RequestSite
A class that shares the primary interface of
:class:`~django.contrib.sites.models.Site` (i.e., it has
``domain`` and ``name`` attributes) but gets its data from a Django
:class:`~django.http.HttpRequest` object rather than from a database.
The ``save()`` and ``delete()`` methods raise ``NotImplementedError``.
.. method:: __init__(request)
Sets the ``name`` and ``domain`` attributes to the value of
:meth:`~django.http.HttpRequest.get_host`.
A :class:`~django.contrib.sites.models.RequestSite` object has a similar
interface to a normal :class:`~django.contrib.sites.models.Site` object, except
its :meth:`~django.contrib.sites.models.RequestSite.__init__()` method takes an
:class:`~django.http.HttpRequest` object. It's able to deduce the
:attr:`~django.contrib.sites.models.RequestSite.domain` and
:attr:`~django.contrib.sites.models.RequestSite.name` by looking at the
request's domain. It has :meth:`~django.contrib.sites.models.RequestSite.save()`
and :meth:`~django.contrib.sites.models.RequestSite.delete()` methods to match
the interface of :class:`~django.contrib.sites.models.Site`, but the methods
raise :exc:`NotImplementedError`.
``domain`` and ``name`` by looking at the request's domain. It has ``save()``
and ``delete()`` methods to match the interface of
:class:`~django.contrib.sites.models.Site`, but the methods raise
``NotImplementedError``.