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
:
gem 'configurable_engine'
Then run the configurable_engine:install
generator:
$ rails generate configurable_engine:install
this will - add config/configurable.yml - create a migration for your configurable table - mount the UI in your routes (defaulting to admin/configurables)
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
:
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:
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:
$ bundle exec rails generate controller admin/configurables
include ConfigurableEngine::ConfigurablesController
, eg.
class Admin::ConfigurablesController < ApplicationController # include the engine controller actions include ConfigurableEngine::ConfigurablesControllerMethods # add your own filter(s) / layout before_filter :protect_my_code layout 'admin' end
and replace
route 'mount ConfigurableEngine::Engine, at: "/admin/configurable", as: "configurable"'
with
namespace :admin do resource :configurable, only: [:show, :update] end
To ensure text areas are rendered correctly, ensure that your layout preserves whitespace. In haml, use the ~
operator
%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:
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
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:
$ 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.
Copyright¶ ↑
Copyright © 2011 Paul Campbell. See LICENSE.txt for further details.