Yacht
Yacht is an application configuration gem that lets you define settings for multiple environments in YAML files. It is similar to AppConfig with additional features like:
-
use of ClassyStruct for improved performance over OpenStruct
-
protection of sensitive settings by specifying a whitelist in a YAML file
-
easy override of nested keys (not pretty with YAML references)
-
no need for an initializer or constant to store loaded values (just use Yacht.my_key)
Installation
-
Rails: Add this to your Gemfile and run the
bundle
command.gem "yacht"
-
Outside of rails, just require the gem as usual:
require 'rubygems' require 'yacht'
Getting Started
Step 1: YAML files
First create one or more of the following YAML files in the same directory to define your settings:
# config/yacht/base.yml (required)
production:
public_info:
copyright_year: 2011
company_name: AT&T Interactive
cdn_host: 1.2.3.4
super_secret_info:
aws_key: foofoo
twitter_key: barbar
test:
cdn_host: localhost
super_secret_info:
# you can safely overwrite a single value in a nested key
# YAML references (& and *) don't let you do this
# see https://gist.github.com/979804 for an explanation
aws_key: bazbaz
# config/yacht/whitelist.yml (optional)
# any keys specified here can be used as a whitelist filter:
# Yacht::Loader.to_hash(:apply_whitelist? => true)
# or
# Yacht::Loader.to_classy_struct(:apply_whitelist? => true)
# (by default the whitelist is ignored)
# NOTE: the whitelist is ignored when using Yacht.my_key or Yacht['my_key']
# you have to use Yacht::Loader#to_hash or
# Yacht::Loader#to_classy_struct to use the whitelist
- public_info
# config/yacht/local.yml (optional)
# any values set in local.yml will override values set in base.yml
# useful for development and testing
production:
cdn_host: localhost
Step 2: Use Yacht.my_key or Yacht in ruby
-
Rails:
# now you can access any key set in your YAML files with: Yacht.my_key # => "my_value"
-
Outside of rails, you need to tell
Yacht
where your YAML files are stored, and what environment you want to use.Yacht::Loader.dir = '/path/to/YAML/dir' Yacht::Loader.environment = 'my_environment' Yacht.my_key
Other features
Yacht::Loader.to_js_snippet export to javascript
If you would like to access values stored in Yacht inside of javascript, there is a helper for that. First, create a YAML file to tell Yacht which keys should be exported:
# config/yacht/base_keys.yml
# only keys listed here will be available in javascript
# remember that any values exported to javascript will be visible to all visitors to your site
-
Then use Yacht::Loader#to_js_snippet to create a string that can be eval’d or included in the DOM:
Yacht::Loader.to_js_snippet
# => ";var Yacht = {\"cookie_domain\":\"example.com\"};"
You can also add in extra values from outside of Yacht using the :merge option, like so:
Yacht::Loader.to_js_snippet(:merge => {:current_time => Time.now.to_s})
# => ";var Yacht = {\"cookie_domain\":\"example.com\",\"current_time\":\"06/29/2011\"};"
yacht_js_snippet Rails helper
When using Yacht inside of a Rails application, you can use the yacht_js_snippet method to wrap the string from Yacht::Loader#to_js_snippet in a script tag using Rails’ javascript_tag helper.
Yacht.rails_env
# => "development" # Yacht automatically adds the current Rails environment in ruby
# If you want rails_env included in javascript, just add it to js_keys.yml
# inside a view or helper:
yacht_js_snippet
# => "<script type=\"text/javascript\">\n//<![CDATA[\n;var Yacht = {\"cookie_domain\":\"localhost\",\"rails_env\":\"development\"};\n//]]>\n</script>"
# you can also pass options to yacht_js_snippet:
yacht_js_snippet(:merge => {:current_time => Time.now.to_s})
# => "<script type=\"text/javascript\">\n//<![CDATA[\n;var Yacht = {\"cookie_domain\":\"localhost\",\"rails_env\":\"development\",\"current_time\":\"06/29/2011\"};\n//]]>\n</script>"
License
Yacht is licensed under the MIT License with one addition: The Software shall be used for Good, not Evil.