================================
 Configuration / Settings Admin
================================

A master view can optionally define a Configuration interface which
allows the user to edit certain :term:`config settings <config
setting>` which pertain to it.

Any settings exposed in this way will be saved to the :term:`settings
table` just to be clear; this does not modify the :term:`config file`.

For basic use cases, the view can define some "simple settings" -
which are settings for which a simple key/value pair is sufficient.
(As opposed to complex use cases where multiple settings must be
combined in some way.)

The basic pattern is:

* view collects values for all relevant settings
* page is shown to the user with settings editable
* user can submit form, which:
  * *removes* all relevant settings, then
  * writes new settings to the table

The view can add extra context for rendering the template if needed.
The "simple" settings are easiest, but complex settings can also be
exposed in this way.

Since the "save" logic always removes relevant settings before writing
new ones, a button is also exposed so user can remove *without*
writing new ones (aka. factory reset).

This feature is intended for admin use of course, but it comes with
its own permission which you can grant to any role(s).


Attributes to Override
----------------------

* :attr:`~wuttaweb.views.master.MasterView.configurable`
* :attr:`~wuttaweb.views.master.MasterView.config_title`


Methods to Override
-------------------

* :meth:`~wuttaweb.views.master.MasterView.configure_get_simple_settings()`
* :meth:`~wuttaweb.views.master.MasterView.configure_gather_settings()`
* :meth:`~wuttaweb.views.master.MasterView.configure_get_context()`
* :meth:`~wuttaweb.views.master.MasterView.configure_remove_settings()`
* :meth:`~wuttaweb.views.master.MasterView.configure_save_settings()`


Template
--------

While most CRUD features aim to work (on a basic level) without
creating any templates, this Configuration feature requires you to
create a template exposing the specific settings involved.

The template must be named ``configure.mako`` and live in the folder
indicated by the view's ``template_prefix`` (relative to your projects
root template folder, e.g. ``poser/web/templates``).

The base for this template has some logic to auto-display the
Save/Cancel buttons when user modifies any values on the page.
However you must add ``@input="settingsNeedSaved = true"`` to relevant
input elements / widgets for this to work properly.

Here is a basic example:

.. code-block:: mako

   <%inherit file="/configure.mako" />

   <%def name="form_content()">

     <h3 class="block is-size-3">My Special Settings</h3>
     <div class="block" style="padding-left: 2rem; width: 50%;">

       <b-field>
         <b-checkbox name="poser.special.foo_flag"
                     v-model="simpleSettings['poser.special.foo_flag']"
                     native-value="true"
                     @input="settingsNeedSaved = true">
           Should we do special "foo" integration?
         </b-checkbox>
       </b-field>

       <b-field label="Failure Threshold">
         <b-input name="poser.special.failure_threshold"
                  v-model="simpleSettings['poser.special.failure_threshold']"
                  @input="settingsNeedSaved = true" />
       </b-field>

     </div>
   </%def>

For more examples see WuttaWeb source code:

* `appinfo/configure.mako
  <https://forgejo.wuttaproject.org/wutta/wuttaweb/src/branch/master/src/wuttaweb/templates/appinfo/configure.mako>`_
* `alembic/migrations/configure.mako
  <https://forgejo.wuttaproject.org/wutta/wuttaweb/src/branch/master/src/wuttaweb/templates/alembic/migrations/configure.mako>`_
* `upgrades/configure.mako
  <https://forgejo.wuttaproject.org/wutta/wuttaweb/src/branch/master/src/wuttaweb/templates/upgrades/configure.mako>`_
* `email/settings/configure.mako
  <https://forgejo.wuttaproject.org/wutta/wuttaweb/src/branch/master/src/wuttaweb/templates/email/settings/configure.mako>`_