Configurable

A Rails 4 configuration engine. An update to Behavior for Rails 4.

How it works

Configurable lets you define app-wide configuration variables and values in config/configurable.yml. These can then be accessed throughout your app.

If you or your app users need to change these variables, Configurable stores new values in the database.

Installation

Configurable is available as a Ruby gem. Simply add it to your Rails 4 app’s Gemfile:

ruby gem 'configurable_engine'

Then run the configurable_engine:install generator:

bash $ rails generate configurable_engine:install

Usage

There are two parts to how configurable_engine works. First of all there is a config file, config/configurable.yml. This file controls the variables that are allowed to be set in the app.

For example, if you wanted to have access to a config variable site_title, put this in configurable.yml:

yaml site_title: name: Site Title default: My Site # type: String is the default Now, within your app, you can access Configurable[:site_title] (or Configurable.site_title if you prefer).

Since Configurable is an ActiveRecord model, if you want to update the config, create a Configurable record in the database:

ruby Configurable.create!(:name => 'site_title', :value => 'My New Site') You can set the type attribute to boolean, decimal,integer, or list and it will treat those fields as those types. Lists are comma and/or newline delimeted arrays of strings.

Web Interface

Configurable comes with a web interface that is available to your app straight away at http://localhost:3000/admin/configurable.

If you want to add a layout, or protect the configurable controller, create app/controllers/admin/configurables_controller.rb as such:

bash $ bundle exec rails generate controller admin/configurables

and include ConfigurableEngine::ConfigurablesController, eg.

```ruby class Admin::ConfigurablesController < ApplicationController # include the engine controller actions include ConfigurableEngine::ConfigurablesController

# add your own filter(s) / layout before_filter :protect_my_code layout ‘admin’ end ```

To ensure text areas are rendered correctly, ensure that your layout preserves whitespace. In haml, use the ~ operator

haml %container ~ yield

If you want to control how the fields in the admin interface appear, you can add additional params in your configurable.yml file:

```yaml site_title: name: Name of Your Site # sets the edit label default: My Site # sets the default value type: string # uses input type=”text” site_description: name: Describe Your Site # sets the edit label default: My Site # sets the default value type: text # uses textarea secret: name: A Secret Passphrase # sets the edit label default: passpass # sets the default value type: password # uses input type=”password”

Value: name: A number # sets the edit label default: 10 # sets the default value type: integer # coerces the value to an integer

Price: name: A price # sets the edit label default: “10.00” # sets the default value type: decimal # coerces the value to a decimal ```

Caching

If you want to use rails caching of Configurable updates, simply set

ruby config.use_cache = true

in your config/application.rb (or config/production.rb)

Styling the interface

To style the web interface you are advised to use Sass. Here’s an example scss file that will make the interface bootstrap-3 ready:

``` @import ‘bootstrap’;

.configurable-container { @extend .col-md-6;

.configurable-options { form { @extend .form-horizontal;

  .configurable {
    @extend .col-md-12;
    @extend .form-group;

    textarea, input[type=text], input[type=password] {
      @extend .form-control;
    }
  }

  input[type=submit] {
    @extend .btn;
    @extend .btn-primary;
  }
}   } } ```

Just save this into your rails assets and you’re ready to go.

Running the Tests

The tests for this rails engine are in the spec and features directories. They use the dummy rails app in spec/dummy

From the top level run:

bash $ bundle exec rake app:db:schema:load $ bundle exec rake app:db:test:prepare $ bundle exec rake

Contributing

All contributions are welcome. Just fork the code, ensure your changes include a test, ensure all the current tests pass and send a pull request.