Plugin Settings
===============

Settings let users configure your plugin without editing code. Define
the schema in ``settings.json``, and the app renders the UI and
delivers values to your plugin.

Define the schema
-----------------

Edit ``settings.json``:

.. code-block:: json

   {
     "fields": [
       {
         "id": "template",
         "label": "Default Template",
         "type": "textarea",
         "default": "## What's New\n\n- \n\n## Bug Fixes\n\n- "
       },
       {
         "id": "auto_tag",
         "label": "Create git tag on publish",
         "type": "bool",
         "default": true
       }
     ]
   }

Supported field types:

.. list-table::
   :header-rows: 1

   * - Type
     - Widget
     - Value
   * - ``text``
     - Single-line input
     - ``str``
   * - ``password``
     - Masked input
     - ``str``
   * - ``textarea``
     - Multi-line input
     - ``str``
   * - ``bool``
     - Checkbox
     - ``bool``
   * - ``secret_file``
     - File picker
     - ``bytes`` (via :meth:`~forkbit_sdk.BasePlugin.secret_file`)

Read settings in your plugin
----------------------------

Settings are available as :attr:`~forkbit_sdk.BasePlugin.settings` —
a plain dict keyed by field ID:

.. code-block:: python

   def on_ready(self) -> None:
       template = self.settings.get("template", "")
       self.editor.setPlainText(template)

React to changes at runtime
----------------------------

When the user saves settings, :meth:`~forkbit_sdk.BasePlugin.on_settings_changed`
is called. Override it to update your UI without restarting:

.. code-block:: python

   def on_settings_changed(self, settings: dict) -> None:
       super().on_settings_changed(settings)
       # Re-apply template if editor is empty
       if not self.editor.toPlainText().strip():
           self.editor.setPlainText(settings.get("template", ""))

Next: :doc:`data`.