.. _topics-views:

=====
Views
=====

.. admonition:: About this document

   This document describes the Django views provided by Softwarefabrica Django
   Wiki.

.. contents::
   :depth: 3

Views
=====

Most views are implemented using generic views, directly inside
``softwarefabrica.django.wiki.urls``. These are so simple that are
self-documenting and not described here.

Custom views are implemented in ``softwarefabrica.django.wiki.views``.

See also the `models documentation`_, `forms documentation`_, and `templates
documentation`_.

.. _`models documentation`: models.html
.. _`forms documentation`: forms.html
.. _`templates documentation`: templates.html

``v_wikipage``
--------------

Renders a wiki ``Page``.

The default template used is ``"wiki/page_detail.html"``.

If the request ``GET`` as a ``rev`` parameter, then it's used to fetch a
specific ``PageContent``.

If the request ``GET`` as a ``format`` parameter, then it's used to render in
the specified format (``"text"``, ``"html"`` or ``"pdf"``. ``"pdf"`` is not yet
implemented.). If the format is specified, a different template is used:
``"wiki/page_detail_txt.txt"`` for ``"text"`` and ``"wiki/page_detail_html.html"`` for
``"html"``. The ``"html"`` format is used to return an HTML version with a
plain-text MIME type, thus forcing the browser to propose a download. This is
useful to get a page off the wiki in HTML to be placed on a different location.

**Required arguments**

None.

**Optional arguments**

``wikiname``
    the `qualified name` for the ``Wiki``, where the ``Page`` specified by
    ``pagename`` is to be searched.

``pagename``
    the `absolute qualified name` for the ``Page`` to be rendered, or the
    `qualified name` is ``wikiname`` is specified.

``template_name``
    the template file to use.

**Context:**

``wiki``
    the ``Wiki`` instance of ``Page``.

``page``
    the ``Page`` instance that will be rendered.

``content``
    the ``PageContent`` that will be rendered.

``name``
    the ``page`` name or ``pagename``.

``has_nav``
    True if ``page`` has navigational fields (``prev``, ``up`` and/or ``next``).

**Template:**

``"wiki/page_detail.html"`` or ``template_name`` if ``format`` is not specified in
the request ``GET`` dictionary.

``v_wikipage_edit``
-------------------

Handles creation or modification of a wiki ``Page``.

The default template used is ``"wiki/page_edit.html"``.

Please note that every time a ``Page`` instance content is modified, a new
``PageContent`` instance is created (using ``PageContentForm``), with a greater
``rev`` field value.

**Required arguments**

One of ``page_id``, ``pagename`` or ``create``. See below for their meaning.

**Optional arguments**

``wikiname``
    the `qualified name` for the ``Wiki``, where the ``Page`` specified by
    ``pagename`` is to be searched, or created.

``page_id``
    if ``create`` is ``False``, the ``Page`` UUID.

``pagename``
    the `absolute qualified name` for the ``Page`` to be edited/created, or the
    `qualified name` is ``wikiname`` is specified.

``create``
    if True, the ``Page`` is to be created.

``template_name``
    the template file to use.

**Context:**

``wiki``
    the ``Wiki`` instance of ``Page``.

``page``
    the ``Page`` instance or ``None``.

``content``
    the ``PageContent`` or ``None``.

``name``
    the ``page`` name or ``pagename``.

``form``
    the ``PageForm`` instance.

``contect_form``
    the ``PageContentForm`` instance.

``create``
    True if the ``Page`` needs to be created.

``change``
    True if the ``Page`` needs to be modified.

**Template:**

``"wiki/page_edit.html"`` or ``template_name``.

``v_search``
------------

Performs searches through the wiki, returning ``Wiki``, ``Page`` and
``PageContent`` instances.

The default template used is ``"wiki/search_results.html"``.

**Required arguments**

None.

**Optional arguments**

``template_name``
    the template file to use.

**Context:**

``query_string``
    the query string found in request ``GET`` ``q`` variable, if any.

``wikis``
    matching ``Wiki`` instances.

``pages``
    matching ``Page`` instances.

``pagecontents``
    matching ``PageContent`` instances.

**Template:**

``"wiki/search_results.html"`` or ``template_name``.
