mournful_settings

= Mournful Settings

Adds a settings class to a rails app. The settings are mournful because they can be stored encrypted. Aren't puns wonderful.

== Installation

gem 'mournful_settings'

== Usage

class MySetting < ActiveRecord::Base

  acts_as_mournful_setting

end

=== Fields

Each setting should have five fields:

[name] String: Identifies the setting. Used in 'for' (see below)

[value] String: The value being stored.

[value_type] String: defines how that string should be presented. For example, '1.23' with value_type 'number' will be presented as numeric 1.23. If the value_type was 'text' the value returned would be '1.23'.

[description] String or Text: Information about the setting being stored

[encrypted] Boolean: If set to true, the value will be stored in an encrypted format. Otherwise the value will be stored as plain text.

See db/migrate/001_create_settings.rb for an example migration.

=== Forcing encryption

If you wish to force all settings to be either encrypted or not, you can overwrite the encrypted? method. For example, if you wanted all settings to be encrypted:

def encrypted?
  true
end

=== Retrieving a setting

To use a stored setting, use the 'for' class method:

MySetting.create(:name => 'pi', :value => '3.14159', :value_type => 'number')

MySetting.for(:pi)    -->   3.14159

In this example, MySetting.for(:pi) will return nil if there is no MySetting with a name of 'pi' in the database.

=== Supplying a default

If you wish an alternative value to be returned if no matching setting has been defined, you can add a default to the for declaration.

MySetting.for(:pi, 3.14)

This will return 3.14 until a 'pi' setting has been created.

== Encryption

By default mournful settings are encrypted. You can choose not to encrypt a setting, by setting :encrypted => false.

MySetting.create(
  :name => 'pi', 
  :value => '3.14159', 
  :value_type => 'number',
  :encrypted => false
)

Out of the box, encryption uses a blowfish cipher, and a generic key string.

=== Set key and cipher

If you wish to use your own encryption key, you can define the key like this:

MySetting::Cipher.key = 'your key'

Mournful settings uses Ruby's OpenSSL::Cipher. If you wish to change the cipher from blowfish, you can alter it like this:

MySetting::Cipher.config = 'aes-128-cbc'

To see a list of the available options use:

puts OpenSSL::Cipher.ciphers

See: http://ruby-doc.org/stdlib-1.9.3/libdoc/openssl/rdoc/OpenSSL/Cipher.html

=== Where to set the cipher within your app

If you use a setting in an initializer you need to ensure that your cipher configuration is set before the setting is used. This means you either need to order your initializers putting your mournful_settings initializer first or define the cipher settings in a before_initialize block defined in config/application:

module YourRailsApp
  class Application < Rails::Application

    .....

    config.before_initialize do
      MySetting::Cipher.key = 'your key'
    end
  end
end

See: http://guides.rubyonrails.org/configuring.html#initialization-events

=== Changing key and/or cipher

If you change the cipher configuration, existing encrypted settings will break. Therefore, to make the change after you have started using encrypted settings, you must decrypt your settings, make the change and then re-encrypt the settings again. To ease this task, use the MySetting.recrypt_all method:

MySetting.recrypt_all { MySetting::Cipher.key = 'your key' }

So the process would be:

• Stop the server
• Run the recrypt task
• Add/Update the configuration code in the app
• Start the server

== Add functionality by inheritance

The original design for mournful settings relied on the class in the hosting app, inheriting its functionality from MournfulSettings::Setting. This functionality is still supported.

For example (/app/models/settings.rb)

class Setting < MournfulSettings::Setting 
end

=== Database

When inheriting MournfulSettings::Setting, settings are stored in a database table 'mournful_settings_settings'. This table can be configured via migrations. To add mournful_settings migrations to the host app run this rake task:

rake mournful_settings:install:migrations

Then run 'rake db:migrate' to create the 'mournful_settings_settings' table.

==== Settings before the database is created

If the database table is not present, it will be assumed that the default setting (or nil) should be used until the table is created and the matching setting stored.

=== Updating inherited Setting to use acts_as_mournful_setting

The class Setting above could be modified to work with acts_as_mournful_setting, like this:

class Setting < ActiveRecord::Base

  self.table_name = 'mournful_settings_settings'

  acts_as_mournful_setting

end

This demonstrates the main advantage of using acts_as_mounful_settings, in that you are not restricted as to the table name you wish to use, and it is easier to extend the functionality of the setting class.

== Integration with ActiveAdmin

Mournful settings contains an ActiveAdmin register file, that allows settings to be managed from within the parent app's active_admin space. Of course ActiveAdmin needs to be installed and working in the parent rails application, for this to work.

If your host class is Settings, you can use the Mournful settings' ActiveAdmin register files by adding this to the active_admin initializer in your application.

config.load_paths << MournfulSettings.active_admin_load_path

Alternatively, use lib/active_admin/admin/setting.rb as a template for your own register file.