======
Places
======

The :py:class:`debusine.web.views.places.Place` class represents metadata about
a view in the Debusine web interface. It contains its URL, and information and
methods needed to refer to the view as a web link, a breadcrumb, a button, an
item in the navbar, and so on.

Place instances are normally created by :py:class:`debusine.web.views.ui.UI`
instances, and cached in the Django request.

Places can define parent places to form a navigational hierarchy, to be
rendered in the UI as breadcrumbs.

All :py:class:`debusine.web.views.places.Place` instances have as members:

* ``title``: text to use as user-visile content (page headers, button labels,
  link text, breadcrumbs, and so on)
* ``description`` (optional): description suitable for tooltips
* ``url``: URL to the view
* ``icon`` (optional): Bootstrap 5 icon name to use where appropriate
* ``parent`` (optional): Parent place in the breadcrumbs hierarchy
* ``current``: True if the place corresponds to the current view
  other page content

Place subclasses can define more members as needed for the use cases they need
to support.

Place values
============

Since place metadata is going to be rendered in various different UI
components, it is possible to provide variant values for its ``text``,
``description``, and ``icon`` elements.

Variant values are tracked by :py:class:`PlaceValue` elements, which can be
passed instead of strings to ``Place`` constructors.

Place widget methods
====================

The ``Place`` class defines various ``as_*`` methods that can be rendered using
the ``{% widget %}`` template tag. This allows passing extra arguments from
templates, like selecting a specific variant for its values, or explicitly
passing labels or class attributes.

Place types
===========

SitePlace
---------

:py:class:`debusine.web.views.places.SitePlace` represents a view that is not
about a Debusine resource, like the site homepage, about page, task status, and
so on.

It is the kind of Place that is generated automatically for views that do not
provide full place metadata.

ResourcePlace
-------------

:py:class:`debusine.web.views.places.ResourcePlace` represents a view about a
Debusine resource (see :ref:`internal-api-resources`).

It defines this extra member:

* ``ui``: UI helper for the resource instance

ResourceMainPlace
-----------------

:py:class:`debusine.web.views.places.ResourceMainPlace` represents the main
view for showing a Debusine resource (see :ref:`internal-api-resources`).

ResourceSubPlace
----------------

:py:class:`debusine.web.views.places.ResourceSubPlace` represents a view that
shows or controls an aspect of a Debusine resource (see
:ref:`internal-api-resources`).

ResourceSettingsPlace
---------------------

:py:class:`debusine.web.views.places.ResourceSettingsPlace` represents a view
that is part of the settings menu for a Debusine resource.