Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
A simple and straightforward settings solution that uses an ERB enabled YAML file and a singleton design pattern.
Ruby
branch: master

This branch is 10 commits behind santuxus:master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
lib
rails
spec
.gitignore
CHANGELOG.rdoc
LICENSE
README.rdoc
Rakefile
VERSION.yml
init.rb
santuxus-settingslogic.gemspec
settingslogic.gemspec

README.rdoc

Settingslogic

Settingslogic is a simple configuration / settings solution that uses an ERB enabled YAML file. It has been great for our apps, maybe you will enjoy it too. Settingslogic works with Rails, Sinatra, or any Ruby project.

So here is my question to you.….is Settingslogic a great settings solution or the greatest?

Helpful links

* Documentation: rdoc.info/projects/binarylogic/settingslogic * Repository: github.com/binarylogic/settingslogic/tree/master

Installation

Install from rubyforge/gemcutter:

sudo gem install settingslogic

Or as a Rails plugin:

script/plugin install git://github.com/binarylogic/settingslogic.git

Settingslogic does not have any dependencies on Rails. Installing as a gem is recommended.

Usage

1. Define your class

Instead of defining a Settings constant for you, that task is left to you. Simply create a class in your application that looks like:

class Settings < Settingslogic
  source "#{Rails.root}/config/application.yml"
  namespace Rails.env
end

Name it Settings, name it Config, name it whatever you want. Add as many or as few as you like. A good place to put this file in a rails app is app/models/settings.rb

I felt adding a settings file in your app was more straightforward, less tricky, and more flexible.

2. Create your settings

Notice above we specified an absolute path to our settings file called “application.yml”. This is just a typical YAML file. Also notice above that we specified a namespace for our environment. A namespace is just an optional string that corresponds to a key in the YAML file.

Using a namespace allows us to change our configuration depending on our environment:

# app/config/application.yml
defaults: &defaults
  cool:
    saweet: nested settings
  neat_setting: 24
  awesome_setting: <%= "Did you know 5 + 5 = #{5 + 5}?" %>

development:
  <<: *defaults
  neat_setting: 800

test:
  <<: *defaults

production:
  <<: *defaults

3. Access your settings

>> Rails.env
=> "development"

>> Settings.cool
=> "#<Settingslogic::Settings ... >"

>> Settings.cool.saweet
=> "nested settings"

>> Settings.neat_setting
=> 800

>> Settings.awesome_setting
=> "Did you know 5 + 5 = 10?"

You can use these settings anywhere, for example in a model:

class Post < ActiveRecord::Base
  self.per_page = Settings.pagination.posts_per_page
end

4. Optional / dynamic settings

Often, you will want to handle defaults in your application logic itself, to reduce the number of settings you need to put in your YAML file. You can access an optional setting by using Hash notation:

>> Settings.messaging.queue_name
=> Exception: Missing setting 'queue_name' in 'message' section in 'application.yml'

>> Settings.messaging['queue_name']
=> nil

>> Settings.messaging['queue_name'] ||= 'user_mail'
=> "user_mail"

>> Settings.messaging.queue_name
=> "user_mail"

Modifying our model example:

class Post < ActiveRecord::Base
  self.per_page = Settings.posts['per_page'] || Settings.pagination.per_page
end

This would allow you to specify a custom value for per_page just for posts, or to fall back to your default value if not specified.

Note on Sinatra / Capistrano / Vlad

Each of these frameworks uses a set convention for settings, which actually defines methods in the global Object namespace:

set :application, "myapp"  # does "def application" globally

This can cause collisions with Settingslogic, since those methods are global. Luckily, the solution is to just add a call to load! in your class:

class Settings < Settingslogic
  source "#{Rails.root}/config/application.yml"
  namespace Rails.env
  load!
end

It's probably always safest to add load! to your class, since this guarantees settings will be loaded at that time, rather than lazily later via method_missing.

Finally, you can reload all your settings later as well:

Settings.reload!

This is useful if you want to support changing your settings YAML without restarting your app.

Array of source files (Santuxus change)

This change allows you to set multiple source files. The main purpose behind adding it was to avoid the huge size of application.yml. Now you can simply have 'defaults.yml', 'production.yml', 'development.yml' and so on. In your class you can have something like:

class Settings < Settingslogic
  source ["#{Rails.root}/config/settings/defaults.yml", "#{Rails.root}/config/settings/#{Rails.env}.yml"]
end

Sources are merged in the same order as they are positioned in the array; later settings overwrite earlier ones. This solution is somehow equivalent to namespaces, but allows to separate source in different files (thus namespaces don't provide any advantage here).

Author

Copyright © 2008-2010 Ben Johnson of Binary Logic, released under the MIT license. Support for optional settings and reloading by Nate Wiger.

Something went wrong with that request. Please try again.