.. CMS models explanation and API

CMS Models
==========

.. module:: xmm.models.cms

The CMS section consists of two base type models, that
define attributes, look and behaviour of their implementing
counterparts. The :class:`PageType` is implemented by :class:`Page`
and :class:`BlockType` have their :class:`Block`.

Additionally, the :class:`ReferencingPage` is a special subclass
that only accepts base attributes as well as a referenced page
from which it will get all its attributes.


.. autoclass:: PageType

.. autoclass:: BlockType

   .. attribute:: identifier

      The identifier of a blocktype is different from others, in that it
      is actually a Jinja2 template. You can use all common Jinja2 template
      tags and filters when defining your preview template.

      This template currently receives the following context variables:

      - ``block`` The block we want to create a preview for.
      - ``blocktype`` The BlockType object of this block.
      - ``request`` The current HTTP request to the XMM system.

      It is currently not possible to reference the current page the block is on.

      Example usage:

      - Show a scalar value in the template::

         {{ block.fields.my_decimal }}
         {{ block.fields.my_text }}
         {{ block.fields.my_translated.de }}

      - Render a reference or file attribute::

         {% set file = block.get_attribute('myfile') %}
         File size: {{ file.view_size() }}<br />
         File name: {{ file.filename }}<br />
         Preview: <img src="//xmm.mysite.com/{{ url_for('main.thumbnail', object_id=file.id, size='100x100') }}" />

      Rendering a reference attribute requires using the ``get_attribute`` method,
      otherwise the value would just be an ObjectId.

      - Show an attribute with multiple values::

            <ul>
              {% for film in block.fields.films %}
                <li><b>{{ film }}</b> (Runtime: {{ film.fields.length }}min)
                  <ul>
                  {% for category in film.fields.categories %}
                    <li>{{ category }}</li>
                  {% endfor %}
                  </ul>
                </li>
              {% endfor %}
            </ul>

.. autoclass:: Page
   :members:


.. autoclass:: ReferencingPage

   .. attribute:: referenced_page

      A :class:`Page` object that this page will fetch its
      attributes and contents from.

.. autoclass:: Block