Added Tag documentation.

[philo.git] / philo / models / pages.py

diff --git a/philo/models/pages.py b/philo/models/pages.py
index 2221ee4..3ad05d8 100644 (file)
--- a/philo/models/pages.py
+++ b/philo/models/pages.py
@@ -1,4 +1,9 @@
 # encoding: utf-8
 # encoding: utf-8

+"""
+:class:`Page`\ s are the most frequently used :class:`View` subclass. They define a basic HTML page and its associated content. Each :class:`Page` renders itself according to a :class:`Template`. The :class:`Template` may contain :ttag:`container <philo.templatetags.containers.do_container>` tags, which define related :class:`Contentlet`\ s and :class:`ContentReference`\ s for any page using that :class:`Template`.
+
+"""
+

 from django.conf import settings
 from django.contrib.contenttypes.models import ContentType
 from django.contrib.contenttypes import generic
 from django.conf import settings
 from django.contrib.contenttypes.models import ContentType
 from django.contrib.contenttypes import generic


@@ -8,13 +13,14 @@ from django.http import HttpResponse
 from django.template import TemplateDoesNotExist, Context, RequestContext, Template as DjangoTemplate, add_to_builtins as register_templatetags, TextNode, VariableNode
 from django.template.loader_tags import BlockNode, ExtendsNode, BlockContext
 from django.utils.datastructures import SortedDict
 from django.template import TemplateDoesNotExist, Context, RequestContext, Template as DjangoTemplate, add_to_builtins as register_templatetags, TextNode, VariableNode
 from django.template.loader_tags import BlockNode, ExtendsNode, BlockContext
 from django.utils.datastructures import SortedDict

+

 from philo.models.base import TreeModel, register_value_model
 from philo.models.fields import TemplateField
 from philo.models.nodes import View
 from philo.models.base import TreeModel, register_value_model
 from philo.models.fields import TemplateField
 from philo.models.nodes import View

+from philo.signals import page_about_to_render_to_string, page_finished_rendering_to_string

 from philo.templatetags.containers import ContainerNode
 from philo.utils import fattr
 from philo.validators import LOADED_TEMPLATE_ATTR
 from philo.templatetags.containers import ContainerNode
 from philo.utils import fattr
 from philo.validators import LOADED_TEMPLATE_ATTR

-from philo.signals import page_about_to_render_to_string, page_finished_rendering_to_string

 
 
 class LazyContainerFinder(object):
 
 
 class LazyContainerFinder(object):


@@ -70,18 +76,21 @@ class LazyContainerFinder(object):
 
 
 class Template(TreeModel):
 
 
 class Template(TreeModel):

+       """Represents a database-driven django template."""
+       #: The name of the template. Used for organization and debugging.

        name = models.CharField(max_length=255)
        name = models.CharField(max_length=255)

+       #: Can be used to let users know what the template is meant to be used for.

        documentation = models.TextField(null=True, blank=True)
        documentation = models.TextField(null=True, blank=True)

+       #: Defines the mimetype of the template. This is not validated. Default: ``text/html``.

        mimetype = models.CharField(max_length=255, default=getattr(settings, 'DEFAULT_CONTENT_TYPE', 'text/html'))
        mimetype = models.CharField(max_length=255, default=getattr(settings, 'DEFAULT_CONTENT_TYPE', 'text/html'))

+       #: An insecure :class:`~philo.models.fields.TemplateField` containing the django template code for this template.

        code = TemplateField(secure=False, verbose_name='django template code')
        
        @property
        def containers(self):
                """
        code = TemplateField(secure=False, verbose_name='django template code')
        
        @property
        def containers(self):
                """

-               Returns a tuple where the first item is a list of names of contentlets referenced by containers,
-               and the second item is a list of tuples of names and contenttypes of contentreferences referenced by containers.
-               This will break if there is a recursive extends or includes in the template code.
-               Due to the use of an empty Context, any extends or include tags with dynamic arguments probably won't work.
+               Returns a tuple where the first item is a list of names of contentlets referenced by containers, and the second item is a list of tuples of names and contenttypes of contentreferences referenced by containers. This will break if there is a recursive extends or includes in the template code. Due to the use of an empty Context, any extends or include tags with dynamic arguments probably won't work.
+               

                """
                template = DjangoTemplate(self.code)
                
                """
                template = DjangoTemplate(self.code)
                


@@ -130,6 +139,7 @@ class Template(TreeModel):
                return contentlet_specs, contentreference_specs
        
        def __unicode__(self):
                return contentlet_specs, contentreference_specs
        
        def __unicode__(self):

+               """Returns the value of the :attr:`name` field."""

                return self.name
        
        class Meta:
                return self.name
        
        class Meta:


@@ -138,18 +148,29 @@ class Template(TreeModel):
 
 class Page(View):
        """
 
 class Page(View):
        """

-       Represents a page - something which is rendered according to a template. The page will have a number of related Contentlets depending on the template selected - but these will appear only after the page has been saved with that template.
+       Represents a page - something which is rendered according to a :class:`Template`. The page will have a number of related :class:`Contentlet`\ s and :class:`ContentReference`\ s depending on the template selected - but these will appear only after the page has been saved with that template.
+       

        """
        """

+       #: A :class:`ForeignKey` to the :class:`Template` used to render this :class:`Page`.

        template = models.ForeignKey(Template, related_name='pages')
        template = models.ForeignKey(Template, related_name='pages')

+       #: The name of this page. Chances are this will be used for organization - i.e. finding the page in a list of pages - rather than for display.

        title = models.CharField(max_length=255)
        
        def get_containers(self):
        title = models.CharField(max_length=255)
        
        def get_containers(self):

+               """
+               Returns the results :attr:`~Template.containers` for the related template. This is a tuple containing the specs of all :ttag:`containers <philo.templatetags.containers.do_container>` in the :class:`Template`'s code. The value will be cached on the instance so that multiple accesses will be less expensive.
+               
+               """

                if not hasattr(self, '_containers'):
                        self._containers = self.template.containers
                return self._containers
        containers = property(get_containers)
        
        def render_to_string(self, request=None, extra_context=None):
                if not hasattr(self, '_containers'):
                        self._containers = self.template.containers
                return self._containers
        containers = property(get_containers)
        
        def render_to_string(self, request=None, extra_context=None):

+               """
+               In addition to rendering as an :class:`HttpResponse`, a :class:`Page` can also render as a string. This means, for example, that :class:`Page`\ s can be used to render emails or other non-HTML content with the same :ttag:`container <philo.templatetags.containers.do_container>`-based functionality as is used for HTML.
+               
+               """

                context = {}
                context.update(extra_context or {})
                context.update({'page': self, 'attributes': self.attributes})
                context = {}
                context.update(extra_context or {})
                context.update({'page': self, 'attributes': self.attributes})


@@ -165,12 +186,18 @@ class Page(View):
                return string
        
        def actually_render_to_response(self, request, extra_context=None):
                return string
        
        def actually_render_to_response(self, request, extra_context=None):

+               """Returns an :class:`HttpResponse` with the content of the :meth:`render_to_string` method and the mimetype set to the :attr:`~Template.mimetype` of the related :class:`Template`."""

                return HttpResponse(self.render_to_string(request, extra_context), mimetype=self.template.mimetype)
        
        def __unicode__(self):
                return HttpResponse(self.render_to_string(request, extra_context), mimetype=self.template.mimetype)
        
        def __unicode__(self):

+               """Returns the value of :attr:`title`"""

                return self.title
        
        def clean_fields(self, exclude=None):
                return self.title
        
        def clean_fields(self, exclude=None):

+               """
+               This is an override of the default model clean_fields method. Essentially, in addition to validating the fields, this method validates the :class:`Template` instance that is used to render this :class:`Page`. This is useful for catching template errors before they show up as 500 errors on a live site.
+               
+               """

                if exclude is None:
                        exclude = []
                
                if exclude is None:
                        exclude = []
                


@@ -196,11 +223,16 @@ class Page(View):
 
 
 class Contentlet(models.Model):
 
 
 class Contentlet(models.Model):

+       """Represents a piece of content on a page. This content is treated as a secure :class:`~philo.models.fields.TemplateField`."""
+       #: The page which this :class:`Contentlet` is related to.

        page = models.ForeignKey(Page, related_name='contentlets')
        page = models.ForeignKey(Page, related_name='contentlets')

+       #: This represents the name of the container as defined by a :ttag:`container <philo.templatetags.containers.do_container>` tag.

        name = models.CharField(max_length=255, db_index=True)
        name = models.CharField(max_length=255, db_index=True)

+       #: A secure :class:`~philo.models.fields.TemplateField` holding the content for this :class:`Contentlet`. Note that actually using this field as a template requires use of the :ttag:`include_string <philo.templatetags.include_string.do_include_string>` template tag.

        content = TemplateField()
        
        def __unicode__(self):
        content = TemplateField()
        
        def __unicode__(self):

+               """Returns the value of the :attr:`name` field."""

                return self.name
        
        class Meta:
                return self.name
        
        class Meta:


@@ -208,13 +240,18 @@ class Contentlet(models.Model):
 
 
 class ContentReference(models.Model):
 
 
 class ContentReference(models.Model):

+       """Represents a model instance related to a page."""
+       #: The page which this :class:`ContentReference` is related to.

        page = models.ForeignKey(Page, related_name='contentreferences')
        page = models.ForeignKey(Page, related_name='contentreferences')

+       #: This represents the name of the container as defined by a :ttag:`container <philo.templatetags.containers.do_container>` tag.

        name = models.CharField(max_length=255, db_index=True)
        content_type = models.ForeignKey(ContentType, verbose_name='Content type')
        content_id = models.PositiveIntegerField(verbose_name='Content ID', blank=True, null=True)
        name = models.CharField(max_length=255, db_index=True)
        content_type = models.ForeignKey(ContentType, verbose_name='Content type')
        content_id = models.PositiveIntegerField(verbose_name='Content ID', blank=True, null=True)

+       #: A :class:`GenericForeignKey` to a model instance. The content type of this instance is defined by the :ttag:`container <philo.templatetags.containers.do_container>` tag which defines this :class:`ContentReference`.

        content = generic.GenericForeignKey('content_type', 'content_id')
        
        def __unicode__(self):
        content = generic.GenericForeignKey('content_type', 'content_id')
        
        def __unicode__(self):

+               """Returns the value of the :attr:`name` field."""

                return self.name
        
        class Meta:
                return self.name
        
        class Meta: