diff --git a/docs/SETTINGS_SYSTEM.md b/docs/SETTINGS_SYSTEM.md index 461384e5..661705ec 100644 --- a/docs/SETTINGS_SYSTEM.md +++ b/docs/SETTINGS_SYSTEM.md @@ -1,4 +1,4 @@ -## ⚙ Settings +## ⚙ Setting system This is an explanation how settings are handled intended for anyone thinking about writing their own plugin or contributing to the project. @@ -6,13 +6,35 @@ If you are a user of the app, settings should be described in the `Settings` sec ### 🛢 Data storage -The source of truth for user-defined values is the `pialert.conf` file. Editing the file overwrites values in the databse and in the `table_settings.json` file. +The source of truth for user-defined values is the `pialert.conf` file. Editing the file makes the App overwrite values in the `Settings` database table and in the `table_settings.json` file. #### Settings database table + +The `Settings` database table contains settings for App run purposes. The table is recreated every time the App restarts. The settings are loaded from the source-of-truth, that is the `pialert.conf` file. A high-level overview on the databse structure can be found in the [database documentation](/docs/DATABASE.md). + #### table_settings.json + +This is the [API endpoint](/docs/API.md) that reflects the state of the `Settings` database table. Settings can be accessed with the: + +* `getSetting(key)` JavaScript method + +The json file is also cached on the client-side local storage of the browser. + #### pialert.conf + +> [!INFO] +> This is the source of truth for settings. User-defined values in this files always override default values specified in the Plugin definition. + +The App generates two `pialert.conf` entries for every setting (Since version 23.8+). One entry is the setting value, the second is the `__metadata` associated with the setting. This `__metadata` entry contains the full setting definition in JSON format. This should helps the future extensibility of the Settings system. + #### Plugin settings +> [!INFO] +> This is the preferred way adding settings going forward. I'll be likely migrating all app settings into plugin-based settings. + +Plugin settings are loaded dynamically from the `config.json` of individual plugins. If a setting isn't defined in the `pialert.conf` file, it is initialized via the `default_value` property of a setting from the `config.json` file. Check the [Plugins documentation](/front/plugins/README.md), section `⚙ Setting object structure` for details on the structure of the setting. + +![Screen 1][screen1] ### Settings Process flow @@ -50,6 +72,6 @@ Here's a high-level description of the code: - Finally, it logs the successful import of the new configuration. +_____________________ - - +[screen1]: https://raw.githubusercontent.com/jokob-sk/Pi.Alert/main/docs/img/plugins_json_settings.png "Screen 1" \ No newline at end of file diff --git a/front/plugins/README.md b/front/plugins/README.md index b4bf425c..7adbf049 100755 --- a/front/plugins/README.md +++ b/front/plugins/README.md @@ -387,10 +387,11 @@ Below are some general additional notes, when defining `params`: Required attributes are: - `"function": ""` - What function the setting drives or a simple unique code name -- `"type": ""` - The form control used for the setting displayed in the Settings page and what values are accepted. +- `"type": ""` - The form control used for the setting displayed in the Settings page and what values are accepted. - `"localized"` - a list of properties on the current JSON level which need to be localized -- `"name"` and `"description"` - Displayed in the Settings page. An array of localized strings. (see Localized strings below). +- `"name"` and `"description"` - Displayed on the Settings page. An array of localized strings. (see Localized strings below). - (optional) `"events"` - `` - to generate an execution button next to the input field of the setting (not fully tested) +- (optional) `"override_value"` - used to determine a user-defined override for the setting. Useful for template-based plugins, where you can choose to leave the current value or override it with the value defined in the setting. (wip) ##### Supported settings `function` values diff --git a/pialert/plugin.py b/pialert/plugin.py index 61017408..77f59d8d 100755 --- a/pialert/plugin.py +++ b/pialert/plugin.py @@ -31,7 +31,7 @@ def run_plugin_scripts(db, runType): # run if overdue scheduled time prefix = plugin["unique_prefix"] - # check scheduels if any contains a unique plugin prefix matching the current plugin + # check schedules if any contains a unique plugin prefix matching the current plugin for schd in conf.mySchedules: if schd.service == prefix: # Check if schedule overdue