docs/models/nodes-and-views.rst

   1 Nodes and Views: Building Website structure
   2 ===========================================
   3 .. automodule:: philo.models.nodes
   4
   5 Nodes
   6 -----
   7
   8 .. autoclass:: Node
   9         :show-inheritance:
  10         :members:
  11         :exclude-members: attribute_set
  12
  13 Views
  14 -----
  15
  16 Abstract View Models
  17 ++++++++++++++++++++
  18
  19 .. autoclass:: View
  20         :show-inheritance:
  21         :members:
  22         :exclude-members: attribute_set
  23
  24 .. class:: MultiView
  25
  26    :class:`!MultiView` is an abstract model which represents a section of related pages - for example, a :class:`~philo.contrib.penfield.BlogView` might have a foreign key to :class:`Page`\ s for an index, an entry detail, an entry archive by day, and so on. :class:`!MultiView` subclasses :class:`View`, and defines the following additional methods and attributes:
  27
  28    .. attribute:: accepts_subpath
  29
  30       Same as :attr:`View.accepts_subpath`. Default: ``True``
  31
  32    .. attribute:: urlpatterns
  33
  34       Returns urlpatterns that point to views (generally methods on the class). :class:`!MultiView`\ s can be thought of as "managing" these subpaths.
  35
  36    .. method:: actually_render_to_response(request[, extra_context=None])
  37
  38       Resolves the remaining subpath left after finding this :class:`View`'s node using :attr:`self.urlpatterns <urlpatterns>` and renders the view function (or method) found with the appropriate args and kwargs.
  39
  40    .. method:: get_context()
  41
  42       Hook for providing instance-specific context - such as the value of a Field - to all views.
  43
  44    .. method:: basic_view(field_name)
  45
  46       Given the name of a field on ``self``, accesses the value of that field and treats it as a :class:`View` instance. Creates a basic context based on :meth:`get_context` and any extra_context that was passed in, then calls the :class:`View` instance's :meth:`~View.render_to_response` method. This method is meant to be called to return a view function appropriate for :attr:`urlpatterns`.
  47
  48 Concrete View Subclasses
  49 ++++++++++++++++++++++++
  50
  51 .. class:: Redirect
  52
  53    A :class:`View` subclass. Defines a 301 or 302 redirect to a different url on an absolute or relative path.
  54
  55    .. attribute:: STATUS_CODES
  56
  57       A choices tuple of redirect status codes (temporary or permanent).
  58
  59    .. attribute:: status_code
  60
  61       An :class:`IntegerField` which uses :attr:`STATUS_CODES` as its choices. Determines whether the redirect is considered temporary or permanent.
  62
  63    .. attribute:: target_node
  64
  65       An optional :class:`ForeignKey` to a :class:`Node`. If provided, that node will be used as the basis for the redirect.
  66
  67    .. attribute:: url_or_subpath
  68
  69       A :class:`CharField` which may contain an absolute or relative URL. This will be validated with :class:`philo.validators.RedirectValidator`.
  70
  71    .. attribute:: reversing_parameters
  72
  73       A :class:`~philo.models.fields.JSONField` instance. If the value of :attr:`reversing_parameters` is not None, the :attr:`url_or_subpath` will be treated as the name of a view to be reversed. The value of :attr:`reversing_parameters` will be passed into the reversal as args if it is a list or as kwargs if it is a dictionary.
  74
  75    .. attribute:: target_url
  76
  77       Calculates and returns the target url based on the :attr:`target_node`, :attr:`url_or_subpath`, and :attr:`reversing_parameters`.
  78
  79    .. method:: actually_render_to_response(request[, extra_context=None])
  80
  81       Returns an :class:`HttpResponseRedirect` to :attr:`self.target`.
  82
  83 .. class:: File
  84
  85    A :class:`View` subclass. Stores an arbitrary file.
  86
  87    .. attribute:: mimetype
  88
  89       Defines the mimetype of the uploaded file. This will not be validated.
  90
  91    .. attribute:: file
  92
  93       Contains the uploaded file. Files are uploaded to ``philo/files/%Y/%m/%d``.
  94
  95    .. method:: __unicode__()
  96
  97       Returns the name of :attr:`self.file <file>`.
  98
  99 Pages
 100 *****
 101
 102 :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` tags, which define related :class:`Contentlet`\ s and :class:`ContentReference`\ s for any page using that :class:`Template`.
 103
 104 .. class:: Page
 105
 106    A :class:`View` subclass. 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.
 107
 108    .. attribute:: template
 109
 110       A :class:`ForeignKey` to the :class:`Template` used to render this :class:`Page`.
 111
 112    .. attribute:: title
 113
 114       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.
 115
 116    .. attribute:: containers
 117
 118       Returns :attr:`self.template.containers <Template.containers>` - a tuple containing the specs of all :ttag:`container`\ s defined in the :class:`Template`. The value will be cached on the instance so that multiple accesses will be less expensive.
 119
 120    .. method:: render_to_string([request=None, extra_context=None])
 121
 122       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-related content with the same :ttag:`container`-based functionality as is used for HTML.
 123
 124    .. method:: actually_render_to_response(request[, extra_context=None])
 125
 126       Returns an :class:`HttpResponse` with the content of the :meth:`render_to_string` method and the mimetype set to :attr:`self.template.mimetype <Template.mimetype>`.
 127
 128    .. clean_fields(self[, exclude=None)
 129
 130       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.
 131
 132    .. method:: __unicode__()
 133
 134       Returns :meth:`self.title <title>`
 135
 136 .. class:: Template
 137
 138    Subclasses :class:`TreeModel`. Represents a database-driven django template. Defines the following additional methods and attributes:
 139
 140    .. attribute:: name
 141
 142       The name of the template. Used for organization and debugging.
 143
 144    .. attribute:: documentation
 145
 146       Can be used to let users know what the template is meant to be used for.
 147
 148    .. attribute:: mimetype
 149
 150       Defines the mimetype of the template. This is not validated. Default: ``text/html``.
 151
 152    .. attribute:: code
 153
 154       An insecure :class:`~philo.models.fields.TemplateField` containing the django template code for this template.
 155
 156    .. attribute:: containers
 157
 158       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.
 159
 160    .. method:: __unicode__()
 161
 162       Returns the results of the :meth:`~TreeModel.get_path` method, using the "name" field and a chevron joiner.
 163
 164 .. class:: Contentlet
 165
 166    Defines a piece of content on a page. This content is treated as a secure :class:`~philo.models.fields.TemplateField`.
 167
 168    .. attribute:: page
 169
 170       The page which this :class:`Contentlet` is related to.
 171
 172    .. attribute:: name
 173
 174       This represents the name of the container as defined by a :ttag:`container` tag.
 175
 176    .. attribute:: content
 177
 178       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` template tag.
 179
 180    .. method:: __unicode__()
 181
 182       Returns :attr:`self.name <name>`
 183
 184 .. class:: ContentReference
 185
 186    Defines a model instance related to a page.
 187
 188    .. attribute:: page
 189
 190       The page which this :class:`ContentReference` is related to.
 191
 192    .. attribute:: name
 193
 194       This represents the name of the container as defined by a :ttag:`container` tag.
 195
 196    .. attribute:: content
 197
 198       A :class:`GenericForeignKey` to a model instance. The content type of this instance is defined by the :ttag:`container` tag which defines this :class:`ContentReference`.
 199
 200    .. method:: __unicode__()
 201
 202       Returns :attr:`self.name <name>`