rails-settings-manager 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a70c010193fe02c5bf40d844c72d6e308e6b7d2a
-  data.tar.gz: 5dbf55864c160367484428233f0ec45add65554b
+  metadata.gz: 83ed339be4d77461001dfbaefe1dc83517469dc7
+  data.tar.gz: 316a936f3f82a34833e5aae91ca5fb0dcbf579ab
 SHA512:
-  metadata.gz: e2e1a5d2dc1af98ee279a555e8fb002d0efae686c4ea0a66a8f4ad4fa0d2487dcb064111359c69753717eb825d871e60d89cf1212512242e9fc0bf875364d61a
-  data.tar.gz: 595aa8994392a0d1207a9b0ce3ee63c492f0889068e84054a8d24b284a549b3729125849f687b26a596553a5a1a733847768f66ce401bbdc3bfae03a9f9d79fe
+  metadata.gz: 8362af4ec739fae4b6adda5995384ab6fe9928b8a34a59146a050e4401873fac68ff67662d841e412d775e2c4626127f87233b24b79376155c7753f76a01d636
+  data.tar.gz: 35e183443e2d1997033f34e00afbd15ee2307450dbd6561fb91249957a0eebbe1131668904b8b7748d3d0797e7d88a2a2ae3e10344b689d1f2590587cd862c3f

data/README.md

@@ -1,15 +1,26 @@
-# Rails::Settings::Manager
+# rails-settings-manager
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/rails/settings/manager`. To experiment with that code, run `bin/console` for an interactive prompt.
+A simple extension-plugin for Ruby on Rails application for global settings management in the Database with an easy key-value interface. It keeps track of the settings with the help of standard ActiveRecord methods.
 
-TODO: Delete this and the text above, and describe your gem
+## Features
+
+* Simple management of a global settings table (or even multiple if wanted) in Ruby on Rails applications with an easy key-value interface
+* Behaves like a global Hash stored in the database of the app with full-usage of standard ActiveRecord methods for manipulation, queries and validation
+* Support for key limitations and setting-value validations in the setting models
+* Support for any kind of Object (e.g. ` integer `, ` float `, ` string ` or ` array `)
+* Also modular application structures (e.g. ` Rails::Engine `) are supported
+
+## Requirements
+
+* Ruby (Version ` >= 2.1.0 `)
+* Rails (Version ` >= 4.2.0 `) [Note: ` Rails V 5.0.0 ` and above should also work fine, but are not tested yet completly. If any failures might happen with it feel free to report an [Issue](https://github.com/fnitschmann/rails-settings-manager/issues)] 
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'rails-settings-manager'
+gem "rails-settings-manager"
 ```
 
 And then execute:
@@ -19,23 +30,191 @@ And then execute:
 Or install it yourself as:
 
     $ gem install rails-settings-manager
+    
+
+Generate the required settings files:
+
+    $ rails g settings:install
+    
+If wanted with a custom model name:
+
+    $ rails g settings:install CustomName
+
+Then run your migrations:
+
+    $ bundle exec rake db:migrate
 
 ## Usage
 
-TODO: Write usage instructions here
+### Basic syntax
 
-## Development
+The setting syntax is easy. Create some basic settings if wanted:
+
+```ruby
+Setting.admin_username = "admin"
+Setting.admin_password = "superadminpassword"
+Setting.some_numbers = 123
+Setting.other_credentials = { :username => "user", :password => "userpassword" } 
+Setting["array_like_setting"] = []
+```
+
+Read them:
+
+```ruby
+Setting.some_numbers            # returns 123
+Setting["some_numbers"]         # returns 123
+```
+
+Change already existing setting:
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+```ruby
+Setting.some_numbers = 321      # returns 321
+```
+
+Set multiple at once:
+
+```ruby
+Setting.set(:foo => "bar", :bar => "baz") 
+```
+
+Destroy a single setting and read it again:
+
+```ruby
+Setting.destroy!(:some_numbers) # will raise SettingsManager::Errors::SettingNotFoundError 
+                                # if key not set yet
+Setting.some_numbers            # returns nil or (if set) the default value
+```
+
+Get all settings at once:
+
+```ruby
+Setting.get_all                 # returns Hash
+```
+
+### Defaults
+
+The Gem supports ` .yml ` files which can hold default settings.
+
+To set the default to a settings model add the following lines:
+
+```ruby
+class Setting < SettingsManager::Base
+    default_settings_config Rails.root.join("config/default_settings.yml")
+end
+```
+
+The specified file should look like:
+
+```yaml
+defaults: &defaults
+  some_key: "some_value"
+
+development:
+  <<: *defaults
+
+test:
+  <<: *defaults
+
+production:
+  <<: *defaults
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+Test it:
+
+```ruby
+Setting.some_key        # returns "some_value" if nothing in the Database is present
+```
+
+### Key limitations
+
+There is also an option to restrict to usage of certain keys.
+
+```ruby
+class Setting < SettingsManager::Base
+    allowed_settings_keys [:admin_username, :admin_password]
+    ...
+end
+```
+
+Test it:
+
+```ruby
+Setting.foo                     # will raise SettingsManager::Errors::KeyInvalidError
+Setting.foo = "bar"             # will raise SettingsManager::Errors::KeyInvalidError
+Setting.admin_username = "xxx"  # returns "xxx"
+```
+Note: Check the [Errors Module](https://github.com/fnitschmann/rails-settings-manager/blob/master/lib/settings-manager/base.rb) for more details about the exceptions
+
+### Validation
+
+Validations of the setting values for certain keys are also possible. You can use all the [ActiveRecord Validations](http://guides.rubyonrails.org/active_record_validations.html). The only exception currently is, that you can't use an ` if ` block statement in the validation ` options `.
+
+Example:
+
+```ruby
+class Setting < SettingsManager::Base
+    validates_setting :setting_to_validate,
+        :length => { :minimum => 5, :maximum => 100 }
+    ...
+end
+```
+
+Test it out:
+
+```ruby
+Setting.setting_to_validate = "123"     # will raise SettingsManager::Errors::InvalidError
+```
+Note: Check the [Errors Module](https://github.com/fnitschmann/rails-settings-manager/blob/master/lib/settings-manager/base.rb) for more details about the exceptions
+
+### Extension for models
+
+Settings can be bound on any already-existing ActiveRecord object (aka model). 
+Define this association like this:
+
+```ruby
+class User < ActiveRecord::Base
+    include SettingsManager::Extension
+    
+    # Note: the following line is optional if the name of your settings model is 'Setting'
+    # if not so it is obligatory (String or Class)
+    settings_base_class Setting
+end
+```
+
+Usage:
+
+```ruby
+user = User.find(1)
+user.settings.foo = "bar"
+user.settings.foo           # returns "bar"
+user.settings.get_all       # returns { "foo" => "bar" }
+```
+
+Scopes:
+
+```ruby
+User.with_settings
+# => returns all users with any settings
+
+User.with_settings_for(:key)
+# => returns all users with settings for 'key'
+
+User.without_settings
+# => returns all users without any settings
+
+User.without_settings_for(:key)
+# => returns all users without settings for 'key'
+```
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies. Then, run `bundle exec rake rspec` to run the tests.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/rails-settings-manager.
+Bug reports and pull requests are welcome on GitHub at https://github.com/fnitschmann/rails-settings-manager
 
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
-

data/lib/settings-manager/version.rb

@@ -1,3 +1,3 @@
 module SettingsManager
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails-settings-manager
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Florian Nitschmann
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-08-10 00:00:00.000000000 Z
+date: 2016-08-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails