README.md in rails-settings-cached-2.2.0 vs README.md in rails-settings-cached-2.2.1
- old
+ new
@@ -1,81 +1,71 @@
-## Rails Settings Cached
+# Rails Settings Cached
This a plugin that makes managing a table of
а global key, value pairs easy. Think of it like a global Hash stored in your database,
that uses simple ActiveRecord like methods for manipulation. Keep track of any global
setting that you don't want to hard code into your rails app. You can store any kind
of object. Strings, numbers, arrays, or any object.
-> 🚨 BREAK CHANGES WARNING:
-> rails-settings-cached 2.x has redesigned the API, the new version will compatible with the stored setting values by an older version.
-> When you want to upgrade 2.x, you must read the README again, and follow guides to change your Setting model.
-> 0.x stable branch: https://github.com/huacnlee/rails-settings-cached/tree/0.x
+[](https://rubygems.org/gems/rails-settings-cached) [](http://travis-ci.org/huacnlee/rails-settings-cached) [](https://codecov.io/github/huacnlee/rails-settings-cached?branch=master)
-## Status
+## Installation
-[](https://rubygems.org/gems/rails-settings-cached) [](http://travis-ci.org/huacnlee/rails-settings-cached) [](https://codeclimate.com/github/huacnlee/rails-settings-cached) [](https://codecov.io/github/huacnlee/rails-settings-cached?branch=master)
-
-## Setup
-
Edit your Gemfile:
-```ruby
-gem "rails-settings-cached", "~> 2.0"
+```bash
+$ bundle add rails-settings-cached
```
Generate your settings:
```bash
$ rails g settings:install
-```
-If you want custom model name:
-
-```bash
-$ rails g settings:install
+# Or use a custom name:
+$ rails g settings:install AppConfig
```
-Or use a custom name:
-
-```bash
-$ rails g settings:install SiteConfig
-```
-
You will get `app/models/setting.rb`
```rb
class Setting < RailsSettings::Base
# cache_prefix { "v1" }
-
+ field :app_name, default: "Rails Settings Cache Demo"
field :host, default: "http://example.com"
+ field :default_locale, default: "zh-CN"
field :readonly_item, type: :integer, default: 100, readonly: true
field :user_limits, type: :integer, default: 20
field :exchange_rate, type: :float, default: 0.123
field :admin_emails, type: :array, default: %w[admin@rubyonrails.org]
+ field :captcha_enable, type: :boolean, default: true
+
# Override array separator, default: /[\n,]/ split with \n or comma.
field :tips, type: :array, separator: /[\n]+/
- field :captcha_enable, type: :boolean, default: 1
+
field :notification_options, type: :hash, default: {
send_all: true,
logging: true,
sender_email: "foo@bar.com"
}
+
+ # lambda default value
+ field :welcome_message, type: :string, default: -> { "welcome to #{self.app_name}" }
end
```
You must use `field` method to statement the setting keys, otherwise you can't use it.
Now just put that migration in the database with:
```bash
-rake db:migrate
+$ rails db:migrate
```
## Usage
-The syntax is easy. First, let's create some settings to keep track of:
+The syntax is easy. First, let's create some settings to keep track of:
```ruby
irb > Setting.host
"http://example.com"
irb > Setting.host = "https://your-host.com"
@@ -199,11 +189,11 @@
config/routes.rb
```rb
namespace :admin do
- resources :settings
+ resource :settings
end
```
app/controllers/admin/settings_controller.rb
@@ -255,80 +245,52 @@
<%= f.text_area :notification_options, value: YAML.dump(Setting.notification_options), class: "form-control", style: "height: 180px;" %>
<div class="form-text">
Use YAML format to config the SMTP_html
</div>
</div>
+
+ <div>
+ <%= f.submit 'Update Settings' %>
+ </div>
<% end %>
```
-## Backward compatible to support 0.x scoped settings
+## Scoped Settings
-You may used the scoped setting feature in 0.x version. Before you upgrade rails-settings-cached 2.x, you must follow this guide to backward compatible it.
+> 🚨 BREAK CHANGES WARNING:
+> rails-settings-cached 2.x has redesigned the API, the new version will compatible with the stored setting values by an older version.
+> When you want to upgrade 2.x, you must read the README again, and follow guides to change your Setting model.
+> 0.x stable branch: https://github.com/huacnlee/rails-settings-cached/tree/0.x
-For example:
+- [Backward compatible to support 0.x scoped settings](docs/backward-compatible-to-scoped-settings.md)
-```rb
-class User < ApplicationRecord
- include RailsSettings::Extend
-end
+For new project / new user of rails-settings-cached. The [ActiveRecord::AttributeMethods::Serialization](https://api.rubyonrails.org/classes/ActiveRecord/AttributeMethods/Serialization/ClassMethods.html#method-i-serialize) is best choice.
-@user.settings.color = "red"
-@user.settings.foo = 123
-```
+> This is reason of why rails-settings-cached 2.x removed **Scoped Settings** feature.
-create `app/models/concerns/scoped_setting.rb`
+For example:
-```rb
-module ScopedSetting
- extend ActiveSupport::Concern
+We wants a preferences setting for user.
- included do
- has_many :settings, as: :thing
- end
-
- class_methods do
- def scoped_field(name, default: nil)
- define_method(name) do
- obj = settings.where(var: name).take || settings.new(var: name, value: default)
- obj.value
- end
-
- define_method("#{name}=") do |val|
- record = settings.where(var: name).take || settings.new(var: name)
- record.value = val
- record.save!
-
- val
- end
- end
- end
-end
-```
-
-Now include it for your model:
-
```rb
-class User < ApplicationRecord
- include ScopedSetting
-
- scoped_field :color, default: ""
- scoped_field :foo, default: 0
+class User < ActiveRecord::Base
+ serialize :preferences
end
-```
-Now you must to find project with ".setting." for replace with:
-
-Same values will fetch from the `settings` table.
-
-```rb
-@user.color = "red"
-@user.color # => "red"
-@user.foo = 123
-@user.foo # =>
+@user = User.new
+@user.preferences[:receive_emails] = true
+@user.preferences[:public_email] = true
+@user.save
```
## Use cases:
-- [ruby-china/homeland](https://github.com/ruby-china/homeland)
-- [thebluedoc/bluedoc](https://github.com/thebluedoc/bluedoc/blob/master/app/models/setting.rb)
-- [tootsuite/mastodon](https://github.com/tootsuite/mastodon)
-- [helpyio/helpy](https://github.com/helpyio/helpy)
+- [ruby-china/homeland](https://github.com/ruby-china/homeland) - master
+- [forem/forem](https://github.com/forem/forem) - 2.x
+- [siwapp/siwapp](https://github.com/siwapp/siwapp) - 2.x
+- [aidewoode/black_candy](https://github.com/aidewoode/black_candy) - 2.x
+- [thebluedoc/bluedoc](https://github.com/thebluedoc/bluedoc/blob/master/app/models/setting.rb) - 2.x
+- [tootsuite/mastodon](https://github.com/tootsuite/mastodon) - 0.6.x
+- [helpyio/helpy](https://github.com/helpyio/helpy) - 0.5.x
+
+
+And more than [1K repositories](https://github.com/huacnlee/rails-settings-cached/network/dependents) used.