Module: UltraSettings

Defined in:
lib/ultra_settings.rb,
lib/ultra_settings/field.rb,
lib/ultra_settings/coerce.rb,
lib/ultra_settings/railtie.rb,
lib/ultra_settings/version.rb,
lib/ultra_settings/rack_app.rb,
lib/ultra_settings/web_view.rb,
lib/ultra_settings/mini_i18n.rb,
lib/ultra_settings/tasks/utils.rb,
lib/ultra_settings/view_helper.rb,
lib/ultra_settings/yaml_config.rb,
lib/ultra_settings/config_helper.rb,
lib/ultra_settings/configuration.rb,
lib/ultra_settings/render_helper.rb,
lib/ultra_settings/application_view.rb,
lib/ultra_settings/audit_data_sources.rb,
lib/ultra_settings/configuration_view.rb,
lib/ultra_settings/uninitialized_runtime_settings.rb

Overview

This is the root namespace for UltraSettings. You can add configurations to this namespace using the add method.

Examples:

UltraSettings.add(:test)
UltraSettings.test # => TestConfiguration.instance

Defined Under Namespace

Modules: ConfigHelper, MiniI18n, RenderHelper, Tasks, ViewHelper Classes: ApplicationView, AuditDataSources, Coerce, Configuration, ConfigurationView, Field, RackApp, Railtie, UninitializedRuntimeSettings, WebView, YamlConfig

Constant Summary collapse

VALID_NAME_PATTERN = 
/\A[a-z_][a-zA-Z0-9_]*\z/
VERSION = 
File.read(File.expand_path("../../VERSION", __dir__)).strip.freeze

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.runtime_settings=(value) ⇒ void (writeonly)

This method returns an undefined value.

Set the object to use for runtime settings. This can be any object that responds to the [] method. If you are using the super_settings gem, you can set this to SuperSettings.

Parameters:

  • value (#[]) —

    The object to use for runtime settings.



175
176
177
 
# File 'lib/ultra_settings.rb', line 175

def runtime_settings=(value)
  @runtime_settings = value
end

.runtime_settings_secure=(value) ⇒ void (writeonly)

This method returns an undefined value.

Set whether or not the runtime settings engine is considered secure. If this is set to false, then runtime settings will be disabled for all fields marked as secret. The default value is true.

Parameters:

  • value (Boolean) —

    Whether the runtime settings engine is secure.



267
268
269
 
# File 'lib/ultra_settings.rb', line 267

def runtime_settings_secure=(value)
  @runtime_settings_secure = value
end

.runtime_settings_url(name: nil, type: nil, description: nil) ⇒ String?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Get the URL for changing runtime settings.

Parameters:

  • name (String) (defaults to: nil) —

    The name of the setting.

  • type (String) (defaults to: nil) —

    The type of the setting.

  • description (String) (defaults to: nil) —

    The description of the setting.

Returns:

  • (String, nil) 


252
253
254
255
256
257
258
259
 
# File 'lib/ultra_settings.rb', line 252

def runtime_settings_url(name: nil, type: nil, description: nil)
  url = @runtime_settings_url.to_s
  return nil if url.empty?

  url.gsub("${name}", URI.encode_www_form_component(name.to_s))
    .gsub("${type}", URI.encode_www_form_component(type.to_s))
    .gsub("${description}", URI.encode_www_form_component(description.to_s))
end

.super_settings_api_path ⇒ String?

Get the URL path where the SuperSettings API is mounted.

Returns:

  • (String, nil) 


306
307
308
 
# File 'lib/ultra_settings.rb', line 306

def super_settings_api_path
  @super_settings_api_path
end

Class Method Details

.__configuration_names__ ⇒ Array<String>

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Get the names of all of the configurations that have been added.

Returns:

  • (Array<String>) —

    The names of the configurations.



345
346
347
 
# File 'lib/ultra_settings.rb', line 345

def __configuration_names__
  @configurations.keys
end

.__configurations__ ⇒ Array<UltraSettings::Configuration>

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Get an array of all of the configuration instances that have been loaded into memory.

Returns:



353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
 
# File 'lib/ultra_settings.rb', line 353

def __configurations__
  @configurations.each do |name, class_name|
    __load_config__(name, class_name)
  end

  config_classes = ObjectSpace.each_object(Class).select do |klass|
    next false unless klass < Configuration
    next false if klass.name.nil?
    begin
      constantize(klass.name).equal?(klass)
    rescue NameError
      false
    end
  end
  config_classes.collect(&:instance)
end

.__development_mode__? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns true if the application is running in development mode. This is used by the web UI to decide if templates, stylesheets, and translations can be cached in memory or if they need to be re-read from disk on every request.

Returns:

  • (Boolean) 


231
232
233
234
 
# File 'lib/ultra_settings.rb', line 231

def __development_mode__?
  env = ENV["RAILS_ENV"] || ENV["RACK_ENV"] || ENV["APP_ENV"] || "development"
  env == "development"
end

.__runtime_settings__ ⇒ Object?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Get the object to use for runtime settings.

Returns:

  • (Object, nil) 


181
182
183
 
# File 'lib/ultra_settings.rb', line 181

def __runtime_settings__
  @runtime_settings
end

.add(name, klass = nil) ⇒ void

This method returns an undefined value.

Adds a configuration to the root namespace. The configuration will be available as a method on the UltraSettings module with the provide name.

Parameters:

  • name (Symbol, String) —

    The name of the configuration.

  • klass (Class, String) (defaults to: nil) —

    The class of the configuration. If this is not provided then the class will be inferred from the name by camelizing the name and appending "Configuration" to get the class name.



56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
 
# File 'lib/ultra_settings.rb', line 56

def add(name, klass = nil)
  name = name.to_s
  unless name.match?(VALID_NAME_PATTERN)
    raise ArgumentError.new("Invalid configuration name: #{name.inspect}")
  end

  class_name = klass&.to_s
  class_name ||= "#{classify(name)}Configuration"

  @mutex.synchronize do
    @configurations[name] = class_name

    eval <<-RUBY, binding, __FILE__, __LINE__ + 1 # rubocop:disable Security/Eval
      def #{name}
        __load_config__(#{name.inspect}, #{class_name.inspect})
      end
    RUBY
  end
end

.added?(class_name) ⇒ Boolean

Returns true if the provided class has been added as a configuration.

Parameters:

  • class_name (Class, String) —

    The name of the configuration class.

Returns:

  • (Boolean) 


80
81
82
 
# File 'lib/ultra_settings.rb', line 80

def added?(class_name)
  @configurations.values.collect(&:to_s).include?(class_name.to_s)
end

.env_var_delimiter=(value) ⇒ void

This method returns an undefined value.

Set the delimiter to use when determining environment variable names. By default this is an underscore.

Parameters:

  • value (String) —

    The delimiter to use.



129
130
131
 
# File 'lib/ultra_settings.rb', line 129

def env_var_delimiter=(value)
  Configuration.env_var_delimiter = value.to_s
end

.env_var_upcase=(value) ⇒ void

This method returns an undefined value.

Control if environment variable names should be upcased. By default this is true.

Parameters:

  • value (Boolean) —

    Whether or not to upcase environment variable names.



147
148
149
 
# File 'lib/ultra_settings.rb', line 147

def env_var_upcase=(value)
  Configuration.env_var_upcase = !!value
end

.environment_variables_disabled=(value) ⇒ void

This method returns an undefined value.

Control if settings can be loaded from environment variables. By default environment variables are enabled. This can also be disabled on individual Configuration classes.

Parameters:

  • value (Boolean) —

    Whether or not to load settings from environment variables.



90
91
92
 
# File 'lib/ultra_settings.rb', line 90

def environment_variables_disabled=(value)
  Configuration.environment_variables_disabled = !!value
end

.fields_secret_by_default=(value) ⇒ void

This method returns an undefined value.

Set whether fields should be considered secret by default.

Parameters:

  • value (Boolean) —

    Whether fields should be secret by default.



312
313
314
 
# File 'lib/ultra_settings.rb', line 312

def fields_secret_by_default=(value)
  Configuration.fields_secret_by_default = value
end

.override!(settings, &block) ⇒ Object

Explicitly set values for setting within a block. This is useful for testing or other situations where you want hard code a specific set of values.

Parameters:

  • settings (Hash) —

    The settings to set.

Returns:

  • (Object) —

    The result of the block.



321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
 
# File 'lib/ultra_settings.rb', line 321

def override!(settings, &block)
  settings = settings.to_a
  config_name, values = settings.first
  config_name = config_name.to_s
  other_settings = settings[1..]

  unless @configurations.include?(config_name)
    raise ArgumentError.new("Unknown configuration: #{config_name.inspect}")
  end

  config = send(config_name)
  config.override!(values) do
    if other_settings.empty?
      yield
    else
      override!(other_settings, &block)
    end
  end
end

.runtime_setting_delimiter=(value) ⇒ void

This method returns an undefined value.

Set the delimiter to use when determining setting names. By default this is a period.

Parameters:

  • value (String) —

    The delimiter to use.



138
139
140
 
# File 'lib/ultra_settings.rb', line 138

def runtime_setting_delimiter=(value)
  Configuration.runtime_setting_delimiter = value.to_s
end

.runtime_setting_upcase=(value) ⇒ void

This method returns an undefined value.

Control if setting names should be upcased. By default this is false.

Parameters:

  • value (Boolean) —

    Whether or not to upcase setting names.



155
156
157
 
# File 'lib/ultra_settings.rb', line 155

def runtime_setting_upcase=(value)
  Configuration.runtime_setting_upcase = !!value
end

.runtime_settings_disabled=(value) ⇒ void

This method returns an undefined value.

Control if settings can be loaded from runtime settings. By default runtime settings are enabled. This can also be disabled on individual Configuration classes.

Parameters:

  • value (Boolean) —

    Whether or not to load settings from runtime settings.



100
101
102
 
# File 'lib/ultra_settings.rb', line 100

def runtime_settings_disabled=(value)
  Configuration.runtime_settings_disabled = !!value
end

.runtime_settings_secure? ⇒ Boolean

Check if the runtime settings engine is considered secure.

Returns:

  • (Boolean) 


272
273
274
 
# File 'lib/ultra_settings.rb', line 272

def runtime_settings_secure?
  @runtime_settings_secure
end

.with_runtime_settings_reloaded ⇒ Object

Reload the runtime settings cache and then yield to the block. The web views call this when rendering so that a setting changed from the UI is displayed on the next page load rather than whenever the runtime settings engine gets around to refreshing itself.

The runtime settings object is reloaded if it responds to load_settings. The super_settings gem does, as does anything that delegates to it.

Calls are reentrant, so a block that renders several views only reloads once. Wrap a page that embeds more than one ConfigurationView in this method to avoid reloading the runtime settings once per view.

Errors are not fatal; the page can still show values from the other sources.

Examples:

Rendering several configurations with a single reload.

UltraSettings.with_runtime_settings_reloaded do
  configurations.each { |config| output << UltraSettings::ConfigurationView.new(config).render }
end

Returns:

  • (Object) —

    The result of the block.



205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
 
# File 'lib/ultra_settings.rb', line 205

def with_runtime_settings_reloaded
  return yield if Thread.current[RELOAD_GUARD_KEY]

  Thread.current[RELOAD_GUARD_KEY] = true
  begin
    settings = __runtime_settings__
    if settings.respond_to?(:load_settings)
      begin
        settings.load_settings
      rescue => e
        warn("UltraSettings: unable to reload runtime settings: #{e.class}: #{e.message}")
      end
    end

    yield
  ensure
    Thread.current[RELOAD_GUARD_KEY] = nil
  end
end

.yaml_config_disabled=(value) ⇒ void

This method returns an undefined value.

Control if settings can be loaded from YAML configuration files. By default YAML configuration is enabled. This can also be disabled on individual Configuration classes.

Parameters:

  • value (Boolean) —

    Whether or not to load settings from YAML configuration.



110
111
112
 
# File 'lib/ultra_settings.rb', line 110

def yaml_config_disabled=(value)
  Configuration.yaml_config_disabled = !!value
end

.yaml_config_env=(value) ⇒ void

This method returns an undefined value.

Set the environment to use when loading YAML configuration files. In a Rails application this will be the current Rails environment. Defaults to "development".

Parameters:

  • value (String) —

    The environment name to use.



120
121
122
 
# File 'lib/ultra_settings.rb', line 120

def yaml_config_env=(value)
  Configuration.yaml_config_env = value
end

.yaml_config_path=(value) ⇒ void

This method returns an undefined value.

Set the directory to use when loading YAML configuration files. In a Rails application this will be the config directory. Otherwise it will be the current working directory.

Parameters:

  • value (String, Pathname) —

    The directory to use.



165
166
167
 
# File 'lib/ultra_settings.rb', line 165

def yaml_config_path=(value)
  Configuration.yaml_config_path = value.to_s
end