"""
end
defp input_name(keys) do
Bonfire.Common.Settings.LiveHandler.input_name(keys)
end
end
```
### Example 4: Instance-Level Setting
Create an admin-only instance setting:
```elixir
# extensions/my_extension/lib/components/settings/instance_limits_live.ex
defmodule MyExtension.Settings.InstanceLimitsLive do
use Bonfire.UI.Common.Web, :stateless_component
prop scope, :any, default: nil
declare_settings(:number, l("Maximum Items Per User"),
keys: [MyExtension, :max_items_per_user],
default_value: 1000,
unit: l("items"),
description: l("Maximum number of items each user can create"),
scope: :instance # Admin only
)
end
```
## Best Practices
### Naming Conventions
1. **Keys should be hierarchical:**
```elixir
[:my_extension, :feature, :sub_feature] # Good
[:my_random_key] # Avoid
```
2. **Use your module or extension as the top-level key:**
```elixir
[Bonfire.UI.Social.Feed, :default_sort] # Good
[:feed, :default_sort] # Avoid - conflicts possible
```
### Default Values
Always provide sensible defaults:
```elixir
# Good - provides fallback
Settings.get([MyExt, :timeout], 30, current_user: user)
# Bad - could return nil unexpectedly
Settings.get([MyExt, :timeout], current_user: user)
```
### Scoping
Choose appropriate scopes:
- **User scope** - Specific preferences for that profile (privacy settings, notifications)
- **Account scope** - General personal preferences (theme, language)
- **Instance scope** - System-wide configuration (limits, features)
### Performance
- Instance-level settings are cached in OTP config
- User and account settings are loaded from database (all loaded once per page rather than queried individually when needed)
- Preload settings associations when querying user/account objects
### Security
- Instance settings require admin permissions
- Avoid storing secrets in settings (use environment variables)
- Validate and sanitize user input
- Consider privacy implications of settings data
### Testing
```elixir
defmodule MyExtension.SettingsTest do
use Bonfire.DataCase
use Bonfire.Common.Settings
test "setting default value" do
user = fake_user!()
# Test default
assert Settings.get([MyExt, :feature], false, current_user: user) == false
# Test setting value
{:ok, _} = Settings.put([MyExt, :feature], true, current_user: user)
assert Settings.get([MyExt, :feature], false, current_user: user) == true
end
test "hierarchy works correctly" do
user = fake_user!()
# Instance setting
{:ok, _} = Settings.put([MyExt, :limit], 100, scope: :instance, skip_boundary_check: true)
# User override
{:ok, _} = Settings.put([MyExt, :limit], 50, current_user: user)
# User setting takes precedence
assert Settings.get([MyExt, :limit], 10, current_user: user) == 50
end
end
```
## Troubleshooting
### Common Issues
1. **Settings not saving:**
- Check that form has `phx-change="Bonfire.Common.Settings:set"`
- Ensure `scope` input is included in form
- Verify user has permission for the scope
2. **Settings not loading:**
- Confirm keys match exactly (atoms vs strings)
- Check that default value is provided
- Verify context includes current_user/current_account
3. **Permission errors:**
- Instance settings require admin permissions
- Check `skip_boundary_check: true` for testing
- Verify user is properly authenticated
4. **Settings not appearing in UI:**
- Check file is in correct extension directory
- Verify component uses `declare_settings_component` or `declare_settings`
- Ensure extension is enabled
### Debugging
Enable debug logging:
```elixir
# In your settings call
Settings.get([MyExt, :setting], default,
current_user: user,
debug: true # Shows lookup process
)
```
Check database directly:
```sql
SELECT * FROM bonfire_data_identity_settings
WHERE id = 'user_id_here';
```
### Key Validation
Settings keys should follow these patterns:
```elixir
# Good patterns
[MyExtension, :feature_name]
[MyExtension, :category, :setting]
[Bonfire.UI.Common, :theme, :dark_mode]
# Bad patterns - avoid
[:global_setting] # Too generic
["string_key"] # Use atoms where sensible
[MyExtension, "mixed", :types] # Be consistent
```
## Conclusion
The Bonfire settings system provides a flexible, hierarchical way to manage configuration at multiple levels. By following the patterns and best practices outlined in this guide, you can create robust, user-friendly settings for your extensions.
Key takeaways:
- Use the hierarchical scope system (user > account > instance > OTP config > code)
- Choose between custom components and template components based on complexity
- Always provide default values and consider performance
- Test your settings thoroughly and follow security best practices
- Leverage the automatic UI integration for consistent user experience
For more examples, examine existing settings components in the `bonfire_ui_*` extensions.