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([request=None, with_domain=False, secure=False])
  27
  28       This is essentially a shortcut for calling :meth:`construct_url` without a subpath - which will return the URL of the Node.
  29
  30    .. method:: construct_url([subpath="/", request=None, with_domain=False, secure=False])
  31
  32       This method will do its best to construct a URL based on the Node's location. If with_domain is True, that URL will include a domain and a protocol; if secure is True as well, the protocol will be https. The request will be used to construct a domain in cases where a call to :meth:`Site.objects.get_current` fails.
  33
  34       Node urls will not contain a trailing slash unless a subpath is provided which ends with a trailing slash. Subpaths are expected to begin with a slash, as if returned by :func:`django.core.urlresolvers.reverse`.
  35
  36       :meth:`construct_url` may raise the following exceptions:
  37
  38       - :class:`NoReverseMatch` if "philo-root" is not reversable -- for example, if :mod:`philo.urls` is not included anywhere in your urlpatterns.
  39       - :class:`Site.DoesNotExist <ObjectDoesNotExist>` if with_domain is True but no :class:`Site` or :class:`RequestSite` can be built.
  40       - :class:`AncestorDoesNotExist` if the root node of the site isn't an ancestor of the node constructing the URL.
  41
  42 Views
  43 -----
  44
  45 Abstract View Models
  46 ++++++++++++++++++++
  47 .. class:: View
  48
  49    :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:
  50
  51    .. attribute:: accepts_subpath
  52
  53       Defines whether this :class:`View` can handle subpaths. Default: ``False``
  54
  55    .. method:: handles_subpath(subpath)
  56
  57       Returns True if the the :class:`View` handles the given subpath, and False otherwise.
  58
  59    .. attribute:: nodes
  60
  61       A generic relation back to nodes.
  62
  63    .. method:: reverse([view_name=None, args=None, kwargs=None, node=None, obj=None])
  64
  65       If :attr:`accepts_subpath` is True, try to reverse a URL using the given parameters using ``self`` as the urlconf.
  66
  67       If ``obj`` is provided, :meth:`get_reverse_params` will be called and the results will be combined with any ``view_name``, ``args``, and ``kwargs`` that may have been passed in.
  68
  69       This method will raise the following exceptions:
  70
  71       - :class:`ViewDoesNotProvideSubpaths` if :attr:`accepts_subpath` is False.
  72       - :class:`ViewCanNotProvideSubpath` if a reversal is not possible.
  73
  74    .. method:: get_reverse_params(obj)
  75
  76       This method is not implemented on the base class. It should return a ``view_name``, ``args``, ``kwargs`` tuple suitable for reversing a url for the given ``obj`` using ``self`` as the urlconf. If a reversal will not be possible, this method should raise :class:`ViewCanNotProvideSubpath`.
  77
  78    .. method:: attributes_with_node(node)
  79
  80       Returns a :class:`QuerySetMapper` using the :class:`node <Node>`'s attributes as a passthrough.
  81
  82    .. method:: render_to_response(request[, extra_context=None])
  83
  84       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.
  85
  86       :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``.
  87
  88    .. method:: actually_render_to_response(request[, extra_context=None])
  89
  90       Concrete subclasses must override this method to provide the business logic for turning a ``request`` and ``extra_context`` into an :class:`HttpResponse`.
  91
  92 .. class:: MultiView
  93
  94    :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:
  95
  96    .. attribute:: accepts_subpath
  97
  98       Same as :attr:`View.accepts_subpath`. Default: ``True``
  99
 100    .. attribute:: urlpatterns
 101
 102       Returns urlpatterns that point to views (generally methods on the class). :class:`!MultiView`\ s can be thought of as "managing" these subpaths.
 103
 104    .. method:: actually_render_to_response(request[, extra_context=None])
 105
 106       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.
 107
 108    .. method:: get_context()
 109
 110       Hook for providing instance-specific context - such as the value of a Field - to all views.
 111
 112    .. method:: basic_view(field_name)
 113
 114       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`.
 115
 116 Concrete View Subclasses
 117 ++++++++++++++++++++++++
 118
 119 .. class:: Redirect
 120
 121    A :class:`View` subclass. Defines a 301 or 302 redirect to a different url on an absolute or relative path.
 122
 123    .. attribute:: STATUS_CODES
 124
 125       A choices tuple of redirect status codes (temporary or permanent).
 126
 127    .. attribute:: status_code
 128
 129       An :class:`IntegerField` which uses :attr:`STATUS_CODES` as its choices. Determines whether the redirect is considered temporary or permanent.
 130
 131    .. attribute:: target_node
 132
 133       An optional :class:`ForeignKey` to a :class:`Node`. If provided, that node will be used as the basis for the redirect.
 134
 135    .. attribute:: url_or_subpath
 136
 137       A :class:`CharField` which may contain an absolute or relative URL. This will be validated with :class:`philo.validators.RedirectValidator`.
 138
 139    .. attribute:: reversing_parameters
 140
 141       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.
 142
 143    .. attribute:: target_url
 144
 145       Calculates and returns the target url based on the :attr:`target_node`, :attr:`url_or_subpath`, and :attr:`reversing_parameters`.
 146
 147    .. method:: actually_render_to_response(request[, extra_context=None])
 148
 149       Returns an :class:`HttpResponseRedirect` to :attr:`self.target`.
 150
 151 .. class:: File
 152
 153    A :class:`View` subclass. Stores an arbitrary file.
 154
 155    .. attribute:: mimetype
 156
 157       Defines the mimetype of the uploaded file. This will not be validated.
 158
 159    .. attribute:: file
 160
 161       Contains the uploaded file. Files are uploaded to ``philo/files/%Y/%m/%d``.
 162
 163    .. method:: __unicode__()
 164
 165       Returns the name of :attr:`self.file <file>`.
 166
 167 Pages
 168 *****
 169
 170 :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`.
 171
 172 .. class:: Page
 173
 174    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.
 175
 176    .. attribute:: template
 177
 178       A :class:`ForeignKey` to the :class:`Template` used to render this :class:`Page`.
 179
 180    .. attribute:: title
 181
 182       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.
 183
 184    .. attribute:: containers
 185
 186       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.
 187
 188    .. method:: render_to_string([request=None, extra_context=None])
 189
 190       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.
 191
 192    .. method:: actually_render_to_response(request[, extra_context=None])
 193
 194       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>`.
 195
 196    .. clean_fields(self[, exclude=None)
 197
 198       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.
 199
 200    .. method:: __unicode__()
 201
 202       Returns :meth:`self.title <title>`
 203
 204 .. class:: Template
 205
 206    Subclasses :class:`TreeModel`. Represents a database-driven django template. Defines the following additional methods and attributes:
 207
 208    .. attribute:: name
 209
 210       The name of the template. Used for organization and debugging.
 211
 212    .. attribute:: documentation
 213
 214       Can be used to let users know what the template is meant to be used for.
 215
 216    .. attribute:: mimetype
 217
 218       Defines the mimetype of the template. This is not validated. Default: ``text/html``.
 219
 220    .. attribute:: code
 221
 222       An insecure :class:`~philo.models.fields.TemplateField` containing the django template code for this template.
 223
 224    .. attribute:: containers
 225
 226       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.
 227
 228    .. method:: __unicode__()
 229
 230       Returns the results of the :meth:`~TreeModel.get_path` method, using the "name" field and a chevron joiner.
 231
 232 .. class:: Contentlet
 233
 234    Defines a piece of content on a page. This content is treated as a secure :class:`~philo.models.fields.TemplateField`.
 235
 236    .. attribute:: page
 237
 238       The page which this :class:`Contentlet` is related to.
 239
 240    .. attribute:: name
 241
 242       This represents the name of the container as defined by a :ttag:`container` tag.
 243
 244    .. attribute:: content
 245
 246       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.
 247
 248    .. method:: __unicode__()
 249
 250       Returns :attr:`self.name <name>`
 251
 252 .. class:: ContentReference
 253
 254    Defines a model instance related to a page.
 255
 256    .. attribute:: page
 257
 258       The page which this :class:`ContentReference` is related to.
 259
 260    .. attribute:: name
 261
 262       This represents the name of the container as defined by a :ttag:`container` tag.
 263
 264    .. attribute:: content
 265
 266       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`.
 267
 268    .. method:: __unicode__()
 269
 270       Returns :attr:`self.name <name>`