|
| 1 | +--- |
| 2 | +overview: > |
| 3 | + Addons can be configured using a number of settings. While these are stored in |
| 4 | + a YAML file, it's simple to create a UI for editing these through the Control Panel. |
| 5 | +title: Settings |
| 6 | +id: 14266569-ed5c-4804-b36c-fc66e502491e |
| 7 | +--- |
| 8 | +## Overview |
| 9 | + |
| 10 | +Instead of hard-coding values into your addon, you may allow them to be user-configurable. You may leverage this |
| 11 | +using configuration settings. |
| 12 | + |
| 13 | +``` .language-php |
| 14 | +// Instead of hardcoding values... |
| 15 | +$message = 'Hello John!'; |
| 16 | +
|
| 17 | +// Use a config setting! |
| 18 | +$name = $this->getConfig('greeting_name', 'John'); |
| 19 | +$message = "Hello {$name}!"; |
| 20 | +``` |
| 21 | + |
| 22 | +You should add all your settings to `default.yaml` in your addon folder. As the filename suggests, these will |
| 23 | +act as the default values. |
| 24 | + |
| 25 | +If a user wants to override a setting they may create a `site/addons/addon_name.yaml` file and add the value |
| 26 | +in there. Note that the whole `default.yaml` doesn't need to be copied. Only the values that they wish to |
| 27 | +override need to be in there. |
| 28 | + |
| 29 | +## Creating a Settings UI {#ui} |
| 30 | + |
| 31 | +A nice alternative to opening YAML files is the ability to edit settings through the Control Panel. |
| 32 | + |
| 33 | +To allow your users to edit your configuration settings, simply create a `settings.yaml` fieldset |
| 34 | +in your addon's folder. |
| 35 | + |
| 36 | +``` .language-yaml |
| 37 | +fields: |
| 38 | + foo: |
| 39 | + type: text |
| 40 | +``` |
| 41 | + |
| 42 | +You should _not_ include `display` or `instructions` values. Instead, these should be added to your addon's |
| 43 | +`resources/lang/en/settings.php` file. |
| 44 | + |
| 45 | +``` .language-php |
| 46 | +<?php |
| 47 | +return [ |
| 48 | + 'foo' => 'Foo', |
| 49 | + 'foo_instruct' => "What's a foo? You tell me." |
| 50 | +]; |
| 51 | +``` |
| 52 | + |
| 53 | +Of course, these strings may be translated into other languages by using separate files. |
| 54 | + |
| 55 | +## Retrieving config settings |
| 56 | + |
| 57 | +You can use `$this->getConfig($value, $fallback)` (as well as the type-casting alternatives: `getConfigInt`, |
| 58 | +`getConfigBool`, etc) to retrieve a value. |
| 59 | + |
| 60 | +Config settings can be used from within any addon aspect. |
0 commit comments