.. auto generated by export_components.py

**
UI
**

|development| |area|

A collection of resources for creating a user interface, similar to the Django admin, but for users.

**Version:** 4.0.0-d

**Provides**

- Compat
- Constants
- `Context Processors <https://docs.djangoproject.com/en/stable/ref/templates/api/#writing-your-own-context-processors>`_
- Descriptors
- Registry
- `Views <https://docs.djangoproject.com/en/stable/topics/http/views/>`_


Install
-------

Utilizing the UI system requires several additional setup steps.

You must first decide whether you want to load UI configurations automatically, or manage them manually.

.. tip::
    It is possible to use the built-in UI site with either manually or automatically added configurations. It is also
    possible to use the built-in UI site with additional manually created sites.

The settings to be added are:

- The UI app must be added to use automatic configuration.
- An HTML framework must be selected.
- Context processors will need to be included in template settings.
- The form renderer must be overridden.

Here is an excerpt from an example ``settings.py``:

.. code-block:: python

    # settings.py
    INSTALLED_APPS = [
        # ...
        'superdjango.assets.apps.DefaultConfig',
        'superdjango.html.frameworks.bootstrap4',
        'superdjango.ui.apps.AutoConfig',
    ]

    TEMPLATES = [
        {
            # ...
            'OPTIONS': {
                'context_processors': [
                    # ...
                    'superdjango.ui.context_processors.constants',
                    'superdjango.ui.context_processors.menu_items',
                ],
            },
        },
    ]
    FORM_RENDERER = 'django.forms.renderers.TemplatesSetting'

The ``urls.py`` file is the next thing to be updated.

- Include site URLs.
- For translation of UI JavaScript files, the JavaScriptCatalog must also be added.

.. code-block:: python

    # urls.py
    # ...
    from django.views.i18n import JavaScriptCatalog
    from superdjango.ui import site
    # ...

    urlpatterns = [
        # ...
        path('jsi18n/assets/', JavaScriptCatalog.as_view(packages=['superdjango.assets']), name='sd-javascript-catalog'),
        # Use apps/ (or whatever) or "" if the site is to serve all other URLs.
        path('apps/', include(site.get_urls())),
    ]

Then include the catalog URL in your base template:

.. code-block:: text

    <!-- this MUST come before form.media -->
    <script type="text/javascript" src="{% url 'sd-javascript-catalog' %}"></script>

    {% if form %}{{ form.media }}{% endif %}



.. _ui-ui-constants:

Constants
=========

|development| |configuration|

**Version:** 0.5.0-d

Constants used within the UI.

Developer Reference: :ref:`ui-ui-constants-developer`

**Provides**

- Constants


Various constants are used throughout the UI to maintain consistency and reduce the possibility of errors. In some
cases, changing the behavior of the UI requires the use of a value represented by a constant. When this is required, you
are strongly encouraged to use the appropriate constant rather than a "raw" variable.

Filtering
---------

List filters may make use of constants to manage the orientation and style of filters presented to the user.

Lists
-----

List constants refer to the "mode" of output and also pagination style.

Locations
---------

Location constants refer to an area of the rendered page where something should be displayed. While built-in templates
seek to honor a specified location, the output will in some cases still depend upon the theme's handling of layout.

Menus
-----

Standardize menu locations.

Orientations
------------

Horizontal or vertical orientation of output elements.

Pagination
----------

Various controls over paged results.

Size
----

Various indicators for the relative size of an element rendered on a page.

User
----

``USER`` helps identify the type or user.

- ``ALL``: All (or any) user.
- ``CUSTOMER``: A paying customer.
- ``NORMAL``: A normal user.
- ``ROOT`` is an administrator or superuser.
- ``STAFF`` a staff user.

Verbs
-----

Standard verbs/actions.


.. _ui-ui-context_processors:

Context Processors
==================

|development| |library|

**Version:** 0.3.0-d

Context processors for the UI

Developer Reference: :ref:`ui-ui-context_processors-developer`

**Provides**

- `Context Processors <https://docs.djangoproject.com/en/stable/ref/templates/api/#writing-your-own-context-processors>`_

.. _ui-ui-options:

Options
=======

|development| |library|

**Version:** 0.7.1-d

UI resources, once configured, may be transferred or output as runtime instances.

Developer Reference: :ref:`ui-ui-options-developer`

**Dependencies**

- `bleach <https://bleach.readthedocs.io/>`_ (suggested) *Used UI controls that deal with HTML output.*
- `markdown <https://python-markdown.github.io>`_ (suggested) *Used for the MarkdownControl.*

.. _ui-ui-runtime:

Runtime
=======

|development| |library|

**Version:** 0.2.0-d

UI resources, once configured, may be transferred or output as runtime instances.

Developer Reference: :ref:`ui-ui-runtime-developer`



.. note::
    Runtime resources are utilized internally by SuperDjango UI and may be rarely used in development.


.. _ui-ui-views:

Views
=====

|development| |library|

**Version:** 0.8.0-d

Class-based views initialized for the UI

Developer Reference: :ref:`ui-ui-views-developer`

**Provides**

- `Views <https://docs.djangoproject.com/en/stable/topics/http/views/>`_

**Dependencies**

- `django-formtools <https://django-formtools.readthedocs.io/>`_ (required) *Used for the form wizard functionality.*