Skip to main content

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 settingsPlatform settings
Set byDevelopers, in config/application.rbAdmins, on the Platform Settings page
Stored inconfig.x.project_settingsThe cm_platform_settings table, cached
Read withRails.configuration.x.project_settings.nameCmAdmin::PlatformSettings["slug"]
ExamplesProject name, slug, logo URL, favicon URL, default emailLogin layout, login image, Catalyst AI model, queue
Changes needA deployNothing; 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" }
  • [] raises CmAdmin::PlatformSettings::NotFound (a KeyError) when no setting has that slug, so a typo or a missing seed fails loudly instead of returning nil. It returns nil only for a setting that exists with no value.

  • fetch works like Hash#fetch: pass a default or a block when the code has a sensible fallback. Without one, it raises NotFound too.

  • 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 in image_tag or a CSS url().