Sync Test

Note for Rails 2.3.x users¶ ↑

Check out the branch rails_2_3_x.

Master is Rails 3 compatible only.

AppConstants¶ ↑

It’s funny how every (non)Rails application I work on ends up needing some sort of per-environment global constants.

Examples may include the application url - It might be used in account activation emails and thus should be different between the development and production environments.

Or perhaps your application depends on external services that, depending on the environment, are available in different URIs.

One common approach is to define these constants in your environment files:

# in environment.rb
Rails::Initializer.run do |config|
  ...
  ACTIVATION_URL = "http://www.example.com/activate"
end

#and then in development.rb
  ACTIVATION_URL = "http://localhost:3000/activate"

But in my experience constants end up being scattered all around, people don’t know where to look for them and much less where new ones should be defined.

AppConstants can be used as a gem or as a plugin. It provides a clean way to handle this need.

Usage¶ ↑

Installing AppConstants as a gem¶ ↑

Add it to your Gemfile:

gem 'app_constants'

Then bundle install and run the generator:

$ bundle install

$ rails generate app_constants
  exists  config
  create  config/constants.yml
  exists  config/initializers
  create  config/initializers/load_app_constants.rb

Installing AppConstants as a plugin¶ ↑

Just install the plugin as you normally would and run the generator

$ rails plugin install git://github.com/leonardoborges/app_constants.git

$ rails generate app_constants
  exists  config
  create  config/constants.yml
  exists  config/initializers
  create  config/initializers/load_app_constants.rb

Now use the constants.yml file to define your own constants and the load_app_constants.rb initializer to customize the plugin. e.g: Change the default location for the constants.yml file.

Using AppConstants without Rails¶ ↑

After installing the gem - either using bundler or otherwise - you’ll be responsible for initializing it, like so:

#somewhere in your non-Rails app
AppConstants.config_path = "#{File.dirname(__FILE__)}/config/constants.yml"
AppConstants.environment = "development"
AppConstants.load!

Optionally you can set raise_error_on_missing which will raise a runtime error 1) during load if the environment doesn’t exist and 2) all other times if a constant doesn’t exist:

AppConstants.raise_error_on_missing = true

Example¶ ↑

If you have a constants.yml file that looks like this:

# Enter your per-environment constants below

development: &default
  activation_url:  "http://localhost:3000/activate"
  max_upload_in_bytes: <%= 1.megabyte %>

production:
  <<: *default
  activation_url:  "http://www.example.com/activate"

Then you can use the AppConstant class to retrieve your constants anywhere in your app:

# somewhere in the activation email view
Visit this url to activate your account:
  <%= "#{AppConstants.activation_url}/#{activation_code}" %>

Notice how I used embedded ruby code in the second constant. It works just fine:

# somewhere in your upload handling code
max_size = AppConstants.max_upload_in_bytes # 1048576

Contributing to app_constants¶ ↑

• Check out the latest master to make sure the feature hasn’t been implemented or the bug hasn’t been fixed yet

• Check out the issue tracker to make sure someone already hasn’t requested it and/or contributed it

• Fork the project

• Start a feature/bugfix branch

• Commit and push until you are happy with your contribution

• Make sure to add tests for it. This is important so I don’t break it in a future version unintentionally.

• Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

Copyright¶ ↑

Copyright © 2010-2011 Leonardo Borges, released under the MIT license