Platform Settings
Platform settings are key-value settings that admins edit on the Platform Settings page and that apply immediately. Read them anywhere with CmAdmin::PlatformSettings.
Quick exampleβ
rails g cm_admin:add_cm_platform_setting
CmAdmin::PlatformSettings["ct-bot-queue"] # raises if missing
CmAdmin::PlatformSettings.fetch("login-layout", "background_image") # with a default
Setupβ
We can add platform settings with key-value management.
Generate the tableβ
rails g cm_admin:add_cm_platform_setting
Add a settings category helperβ
- Add or create a new constant type for platform settings category.
- Add a helper method for platform settings category constant with name
select_options_for_setting_category. NOTE: Adding this helper method is mandatory, otherwise platform settings page will fail.
def select_options_for_setting_category(_ = nil, _ = nil)
# add the constant type for platform settings category according to your application.
::Constant.setting_category.map { |category| [category.name, category.id] }
end
- We can create a translation by going to
/cm_admin/platform_settings.
- setting - The name of the setting. Eg: Project Name
- description - The description of the setting. Eg: The title used to identify your project across the system.
- value - The value of the setting. Eg: Commutatus
- category - The category of the setting. Eg: Emails
Project settings vs platform settingsβ
These are two separate things and never override each other:
| Project settings | Platform settings | |
|---|---|---|
| Set by | Developers, in config/application.rb | Admins, on the Platform Settings page |
| Stored in | config.x.project_settings | The cm_platform_settings table, cached |
| Read with | Rails.configuration.x.project_settings.name | CmAdmin::PlatformSettings["slug"] |
| Examples | Project name, slug, logo URL, favicon URL, default email | Login layout, login image, Catalyst AI model, queue |
| Changes need | A deploy | Nothing; they apply immediately |
A platform setting with the same name as a project setting (for example an old Project Name row) has no
effect on config.x.project_settings.
Reading settingsβ
Read every platform setting through CmAdmin::PlatformSettings, from anywhere in the app (models,
views, jobs, mailers):
CmAdmin::PlatformSettings["ct-bot-queue"] # => "default"; raises if the setting doesn't exist
CmAdmin::PlatformSettings.fetch("login-layout", "background_image") # default used when the setting is missing or blank
CmAdmin::PlatformSettings.fetch("ct-bot-model") { "openai/gpt-5.6-sol" }
-
[]raisesCmAdmin::PlatformSettings::NotFound(aKeyError) when no setting has that slug, so a typo or a missing seed fails loudly instead of returningnil. It returnsnilonly for a setting that exists with no value. -
fetchworks likeHash#fetch: pass a default or a block when the code has a sensible fallback. Without one, it raisesNotFoundtoo. -
Settings are looked up by slug (the parameterised name:
Login Layoutβlogin-layout). -
A setting with an uploaded file returns its Active Storage redirect path (
/rails/active_storage/blobs/redirect/...), which never expires and can be used directly inimage_tagor a CSSurl().
Relatedβ
- Configuration
- Catalyst AI: AI platform settings