Skip to content

Commit 06e1852

Browse files
committed
Addon settings
1 parent 6926b34 commit 06e1852

File tree

2 files changed

+64
-0
lines changed

2 files changed

+64
-0
lines changed

content/pages/3.addons/2.anatomy/10.controllers/index.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,3 +64,7 @@ routes:
6464
uses: getEdit
6565
as: karma.edit
6666
```
67+
68+
Note: If you want a settings page, you do _not_ need to create a route. A `/cp/addons/addon-name/settings` route
69+
will be available to you automatically. To avoid conflicts you should not create a route named `settings`.
70+
[See how to create a settings page](/addons/anatomy/settings).
Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
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

Comments
 (0)