docs/models/nodes-and-views.rst

   1 Nodes and Views: Building Website structure
   2 ===========================================
   3 .. currentmodule:: philo.models
   4
   5 Nodes
   6 -----
   7
   8 :class:`Node`\ s are the basic building blocks of a website using Philo. They define the URL hierarchy and connect each URL to a :class:`View` subclass instance which is used to generate an HttpResponse.
   9
  10 .. class:: Node
  11
  12    :class:`!Node` subclasses :class:`TreeEntity`. It defines the following additional methods and attributes:
  13
  14    .. attribute:: view
  15
  16       :class:`GenericForeignKey` to a non-abstract subclass of :class:`View`
  17
  18    .. attribute:: accepts_subpath
  19
  20       A property shortcut for :attr:`self.view.accepts_subpath <View.accepts_subpath>`
  21
  22    .. method:: render_to_response(request[, extra_context=None])
  23
  24       This is a shortcut method for :meth:`View.render_to_response`
  25
  26    .. method:: get_absolute_url()
  27
  28       As long as :mod:`philo.urls` is included somewhere in the urlpatterns, this will return the URL of this node. The returned value will always start and end with a slash.
  29
  30 Views
  31 -----
  32
  33 Abstract View Models
  34 ++++++++++++++++++++
  35 .. class:: View
  36
  37    :class:`!View` is an abstract model that represents an item which can be "rendered", either in response to an :class:`HttpRequest` or as a standalone. It subclasses :class:`Entity`, and defines the following additional methods and attributes:
  38
  39    .. attribute:: accepts_subpath
  40
  41       Defines whether this View class can handle subpaths. Default: ``False``
  42
  43    .. attribute:: nodes
  44
  45       A generic relation back to nodes.
  46
  47    .. method:: get_subpath(obj)
  48
  49       If the view :attr:`accepts subpaths <.accepts_subpath>`, try to find a reversal for the given object using ``self`` as the urlconf. This method calls :meth:`~.get_reverse_params` with ``obj`` as the argument to find out the reversing parameters for that object.
  50
  51    .. method:: get_reverse_params(obj)
  52
  53       This method should return a ``view_name``, ``args``, ``kwargs`` tuple suitable for reversing a url for the given ``obj`` using ``self`` as the urlconf.
  54
  55    .. method:: attributes_with_node(node)
  56
  57       Returns a :class:`QuerySetMapper` using the :class:`node <Node>`'s attributes as a passthrough.
  58
  59    .. method:: render_to_response(request[, extra_context=None])
  60
  61       Renders the :class:`View` as an :class:`HttpResponse`. This will raise :const:`philo.exceptions.MIDDLEWARE_NOT_CONFIGURED` if the `request` doesn't have an attached :class:`Node`. This can happen if :class:`philo.middleware.RequestNodeMiddleware` is not in :setting:`settings.MIDDLEWARE_CLASSES` or if it is not functioning correctly.
  62
  63       :meth:`!render_to_response` will send the :obj:`view_about_to_render <philo.signals.view_about_to_render>` signal, then call :meth:`actually_render_to_response`, and finally send the :obj:`view_finished_rendering <philo.signals.view_finished_rendering>` signal before returning the ``response``.
  64
  65    .. method:: actually_render_to_response(request[, extra_context=None])
  66
  67       Concrete subclasses must override this method to provide the business logic for turning a ``request`` and ``extra_context`` into an :class:`HttpResponse`.
  68
  69 .. class:: MultiView
  70
  71    :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:
  72
  73    .. attribute:: accepts_subpath
  74
  75       Same as :attr:`View.accepts_subpath`. Default: ``True``
  76
  77    .. attribute:: urlpatterns
  78
  79       Returns urlpatterns that point to views (generally methods on the class). :class:`!MultiView`\ s can be thought of as "managing" these subpaths.
  80
  81    .. method:: actually_render_to_response(request[, extra_context=None])
  82
  83       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.
  84
  85    .. method:: get_context()
  86
  87       Hook for providing instance-specific context - such as the value of a Field - to all views.
  88
  89    .. method:: basic_view(field_name)
  90
  91       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`.
  92
  93 Concrete View Subclasses
  94 ++++++++++++++++++++++++
  95
  96 .. class:: Redirect
  97
  98    A :class:`View` subclass. Defines a 301 or 302 redirect to a different url on an absolute or relative path.
  99
 100    .. attribute:: STATUS_CODES
 101
 102       A choices tuple of redirect status codes (temporary or permanent).
 103
 104    .. attribute:: target
 105
 106       A :class:`CharField` which may contain an absolute or relative URL. This will be validated with :class:`philo.validators.RedirectValidator`.
 107
 108    .. attribute:: status_code
 109
 110       An :class:`IntegerField` which uses :attr:`STATUS_CODES` as its choices. Determines whether the redirect is considered temporary or permanent.
 111
 112    .. method:: actually_render_to_response(request[, extra_context=None])
 113
 114       Returns an :class:`HttpResponseRedirect` to :attr:`self.target`.
 115
 116 .. class:: File
 117
 118    A :class:`View` subclass. Stores an arbitrary file.
 119
 120    .. attribute:: mimetype
 121
 122       Defines the mimetype of the uploaded file. This will not be validated.
 123
 124    .. attribute:: file
 125
 126       Contains the uploaded file. Files are uploaded to ``philo/files/%Y/%m/%d``.
 127
 128    .. method:: __unicode__()
 129
 130       Returns the name of :attr:`self.file <file>`.
 131
 132 Pages
 133 *****
 134
 135 :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`.
 136
 137 .. class:: Page
 138
 139    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.
 140
 141    .. attribute:: template
 142
 143       A :class:`ForeignKey` to the :class:`Template` used to render this :class:`Page`.
 144
 145    .. attribute:: title
 146
 147       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.
 148
 149    .. attribute:: containers
 150
 151       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.
 152
 153    .. method:: render_to_string([request=None, extra_context=None])
 154
 155       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.
 156
 157    .. method:: actually_render_to_response(request[, extra_context=None])
 158
 159       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>`.
 160
 161    .. clean_fields(self[, exclude=None)
 162
 163       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.
 164
 165    .. method:: __unicode__()
 166
 167       Returns :meth:`self.title <title>`
 168
 169 .. class:: Template
 170
 171    Subclasses :class:`TreeModel`. Represents a database-driven django template. Defines the following additional methods and attributes:
 172
 173    .. attribute:: name
 174
 175       The name of the template. Used for organization and debugging.
 176
 177    .. attribute:: documentation
 178
 179       Can be used to let users know what the template is meant to be used for.
 180
 181    .. attribute:: mimetype
 182
 183       Defines the mimetype of the template. This is not validated. Default: ``text/html``.
 184
 185    .. attribute:: code
 186
 187       An insecure :class:`~philo.models.fields.TemplateField` containing the django template code for this template.
 188
 189    .. attribute:: containers
 190
 191       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.
 192
 193    .. method:: __unicode__()
 194
 195       Returns the results of the :meth:`~TreeModel.get_path` method, using the "name" field and a chevron joiner.
 196
 197 .. class:: Contentlet
 198
 199    Defines a piece of content on a page. This content is treated as a secure :class:`~philo.models.fields.TemplateField`.
 200
 201    .. attribute:: page
 202
 203       The page which this :class:`Contentlet` is related to.
 204
 205    .. attribute:: name
 206
 207       This represents the name of the container as defined by a :ttag:`container` tag.
 208
 209    .. attribute:: content
 210
 211       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.
 212
 213    .. method:: __unicode__()
 214
 215       Returns :attr:`self.name <name>`
 216
 217 .. class:: ContentReference
 218
 219    Defines a model instance related to a page.
 220
 221    .. attribute:: page
 222
 223       The page which this :class:`ContentReference` is related to.
 224
 225    .. attribute:: name
 226
 227       This represents the name of the container as defined by a :ttag:`container` tag.
 228
 229    .. attribute:: content
 230
 231       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`.
 232
 233    .. method:: __unicode__()
 234
 235       Returns :attr:`self.name <name>`