spreeference 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 681c8829c9221c403c5256195d564a6359958f06
+  data.tar.gz: e75097aa1b067440057d13b11f74acf134f763b4
+SHA512:
+  metadata.gz: 9fdb7b5bb736fd5af14fc6bdff673fa0cbeb61575d90e96595953ca5ace72887bd36e6643be7b351ffa4f1e67028cefcc281dcabb276da11330651095f97f503
+  data.tar.gz: e0b2907110da33fbd032c18591ce35a09534136370a565cb05dc2b08091829633da8d0766e7fabfd9eb95225a65b6dbd0f51db4bf6d9a81a911414cbf9cd5cce

data/LICENSE.md

@@ -0,0 +1,26 @@
+Copyright (c) 2009-2015 Spree Commerce and contributors.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright notice,
+      this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright notice,
+      this list of conditions and the following disclaimer in the documentation
+      and/or other materials provided with the distribution.
+    * Neither the name Spree nor the names of its contributors may be used to
+      endorse or promote products derived from this software without specific
+      prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,233 @@
+## Overview
+The reason for this gem is to extract from Spree Core the Preferences functionality, which can be used in other projects besides Spree and e-commerce, 
+
+Copyright (c) 2009-2015 [Spree Commerce][1] and [Contributors][2], released under the [New BSD License][3]
+
+[1]: https://github.com/spree
+[2]: #
+[3]: #
+
+Spreeference preferences support general application configuration and preferences per model instance. Additional preferences can be added by your application or included extensions.
+
+To implement preferences for a model, simply add a new column called `preferences`. This is an example migration:
+
+```ruby
+class AddPreferencesColumnToProducts < ActiveRecord::Migration[4.2]
+  def up
+    add_column :products, :preferences, :text
+  end
+
+  def down
+    remove_column :products, :preferences
+  end
+end
+```
+This will work if your model is a subclass of `Spreeference::ApplicationRecord`. If found, the `preferences`attribute gets serialized into a `Hash` and merged with the default values.
+
+As another example, you might want to add preferences for users to manage their notification settings. Just make sure your `User` model inherits from `Spreeference::ApplicationRecord` then add the `preferences` column. You'll then be able to define preferences for `User`s without adding extra columns to the database table.
+
+### Motivation
+
+Preferences for models within an application are very common. Although the rule of thumb is to keep the number of preferences available to a minimum, sometimes it's necessary if you want users to have optional preferences like disabling e-mail notifications.
+
+Both use cases are handled by Spreeferences. They are easy to define, provide quick cached reads, persist across restarts and do not require additional columns to be added to your models' tables.
+
+## General Settings
+
+Spreeference comes with many application-wide preferences. They are defined in `app/models/spreeference/app_configuration.rb` and made available to your code through `Spreeference::Config`, e.g., `Spreeference::Config.site_name`.
+
+You can add additional preferences under the `spreeference/app_configuration` namespace or create your own subclass of `Spreeference::Configuration`.
+
+```ruby
+# These will be saved with key: spreeference/app_configuration/hot_salsa
+Spreeference::AppConfiguration.class_eval do
+  preference :hot_salsa, :boolean
+  preference :dark_chocolate, :boolean, default: true
+  preference :color, :string
+  preference :favorite_number
+  preference :language, :string, default: 'English'
+end
+
+# Spreeference::Config is an instance of Spreeference::AppConfiguration
+Spreeference::Config.hot_salsa = false
+
+# Create your own class
+# These will be saved with key: kona/store_configuration/hot_coffee
+Kona::StoreConfiguration < Spreeference::Configuration
+  preference :hot_coffee, :boolean
+  preference :color, :string, default: 'black'
+end
+
+KONA::STORE_CONFIG = Kona::StoreConfiguration.new
+puts KONA::STORE_CONFIG.hot_coffee
+```
+
+## Defining Preferences
+
+You can define preferences for a model within the model itself:
+
+```ruby
+class User < Spreeference::ApplicationRecord
+  preference :hot_salsa, :boolean
+  preference :dark_chocolate, :boolean, default: true
+  preference :color, :string
+  preference :favorite_number, :integer
+  preference :language, :string, default: "English"
+end
+```
+In the above model, five preferences have been defined:
+
+* `hot_salsa`
+* `dark_chocolate`
+* `color`
+* `favorite_number`
+* `language`
+
+For each preference, a data type is provided. The types available are:
+
+* `boolean`
+* `string`
+* `password`
+* `integer`
+* `text`
+* `array`
+* `hash`
+
+An optional default value may be defined which will be used unless a value has been set for that specific instance.
+
+## Accessing Preferences
+
+Once preferences have been defined for a model, they can be accessed either using the shortcut methods that are generated for each preference or the generic methods that are not specific to a particular preference.
+
+### Shortcut Methods
+
+There are several shortcut methods that are generated. They are shown below.
+
+Query methods:
+
+```ruby
+user.prefers_hot_salsa? # => false
+user.prefers_dark_chocolate? # => false
+```
+
+Reader methods:
+
+```ruby
+user.preferred_color      # => nil
+user.preferred_language   # => "English"
+```
+
+Writer methods:
+
+```ruby
+user.prefers_hot_salsa = false         # => false
+user.preferred_language = "English"    # => "English"
+```
+
+Check if a preference is available:
+
+```ruby
+user.has_preference? :hot_salsa
+```
+
+### Generic Methods
+
+Each shortcut method is essentially a wrapper for the various generic methods shown below:
+
+Query method:
+
+```ruby
+user.prefers?(:hot_salsa)       # => false
+user.prefers?(:dark_chocolate)  # => false
+```
+
+Reader methods:
+
+```ruby
+user.preferred(:color)      # => nil
+user.preferred(:language)   # => "English"
+```
+
+```ruby
+user.get_preference :color
+user.get_preference :language
+```
+
+Writer method:
+
+```ruby
+user.set_preference(:hot_salsa, false)     # => false
+user.set_preference(:language, "English")  # => "English"
+```
+### Accessing All Preferences
+
+You can get a hash of all stored preferences by accessing the `preferences` helper:
+
+```ruby
+user.preferences # => {"language"=>"English", "color"=>nil}
+```
+
+This hash will contain the value for every preference that has been defined for the model instance, whether the value is the default or one that has been previously stored.
+
+### Default and Type
+
+You can access the default value for a preference:
+
+```ruby
+user.preferred_color_default # => 'blue'
+```
+
+Types are used to generate forms or display the preference. You can also get the type defined for a preference:
+
+```ruby
+user.preferred_color_type # => :string
+```
+### Configuration Through an Initializer
+
+During the Spreeference installation process, an initializer file is created within your application's source code. The initializer is found under `config/initializers/spreeference.rb`:
+
+```ruby
+Spreeference.config do |config|
+  # Example:
+  # Uncomment to override the default site name.
+  # config.site_name = "Spree Demo Site"
+end
+```
+The `Spreeference.config` block acts as a shortcut to setting `Spreeference::Config` multiple times. If you have multiple default preferences you would like to override within your code you may override them here. Using the initializer for setting the defaults is a nice shortcut, and helps keep your preferences organized in a standard location.
+
+## Site-Wide Preferences
+
+You can define preferences that are site-wide and don't apply to a specific instance of a model by creating a configuration file that inherits from `Spreeference::Configuration`.
+
+```ruby
+class MyApplicationConfiguration < Spreeference::Configuration
+  preference :theme, :string, default: "Default"
+  preference :show_splash_page, :boolean
+  preference :number_of_articles, :integer
+end
+```
+
+In the above configuration file, three preferences have been defined:
+
+* theme
+* show_splash_page
+* number_of_articles
+
+### Configuring Site-Wide Preferences
+
+The recommended way to configure site-wide preferences is through an initializer. Let's take a look at configuring the preferences defined in the previous configuration example.
+
+```ruby
+module Spree
+  MyApp::Config = MyApplicationConfiguration.new
+end
+
+MyApp::Config[:theme] = "blue_theme"
+MyApp::Config[:show_spash_page] = true
+MyApp::Config[:number_of_articles] = 5
+```
+
+The `MyApp` name used here is an example and should be replaced with your actual application's name, found in `config/application.rb`.
+
+The above example will configure the preferences we defined earlier. Take note of the second line. In order to set and get preferences using `MyApp::Config`, we must first instantiate the configuration object.
+

data/Rakefile

@@ -0,0 +1,26 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Spreeference'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path("../spec/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+
+
+load 'rails/tasks/statistics.rake'
+
+
+
+require 'bundler/gem_tasks'
+

data/app/models/spreeference/app_configuration.rb

@@ -0,0 +1,9 @@
+module Spreeference
+  class AppConfiguration < Spreeference::Configuration
+    # preference :checkbox, :boolean,  default: true
+    # preference :input, :string, default:'changeme'
+    # preference :number, :integer, default: 123
+    # preference :list, :array, default:[]
+    preference :is_ok, :string,  default:'Nice!'
+  end
+end

data/app/models/spreeference/application_record.rb

@@ -0,0 +1,16 @@
+module Spreeference
+  class ApplicationRecord < ActiveRecord::Base
+    include Spreeference::Preferable
+    
+    serialize :preferences, Hash
+    
+    after_initialize do
+      if has_attribute?(:preferences) && !preferences.nil?
+        self.preferences = default_preferences.merge(preferences)
+      end
+    end
+
+    self.abstract_class = true 
+    
+  end
+end

data/app/models/spreeference/preference.rb

@@ -0,0 +1,6 @@
+module Spreeference
+  class Preference < Spreeference::ApplicationRecord
+    serialize :value
+    validates :key, presence: true, uniqueness: { allow_blank: true }
+  end
+end

data/config/routes.rb

@@ -0,0 +1,2 @@
+Rails.application.routes.draw do
+end

data/db/migrate/20170217094656_create_spreeference_preferences.rb

@@ -0,0 +1,10 @@
+class CreateSpreeferencePreferences < ActiveRecord::Migration[5.0]
+  def change
+    create_table :spreeference_preferences do |t|
+      t.string    :key
+      t.text      :value
+      t.timestamps
+    end
+    add_index :spreeference_preferences, :key, unique: true
+  end
+end

data/lib/generators/spreeference/install_generator.rb

@@ -0,0 +1,17 @@
+require 'rails/generators'
+module Spreeference::Generators
+  class InstallGenerator < Rails::Generators::Base
+    source_root File.expand_path("../../templates", __FILE__)
+
+    desc 'Add app_configuration.rb'
+    def copy_app_configuration_file
+      copy_file "app_configuration.rb", "app/models/app_configuration.rb"
+    end
+
+    desc 'Add Spreeference configuration in initializers'
+    def copy_configuration_file
+      copy_file "spreeference.rb", "config/initializers/spreeference.rb"
+    end
+
+  end
+end

data/lib/generators/templates/app_configuration.rb

@@ -0,0 +1,6 @@
+class AppConfiguration < Spreeference::Configuration
+  # preference :checkbox, :boolean,  default: true
+  # preference :input, :string, default:'changeme'
+  # preference :number, :integer, default: 123
+  # preference :list, :array, default:[]
+end

data/lib/generators/templates/spreeference.rb

@@ -0,0 +1,12 @@
+# Configure Spree Preferences
+#
+# Note: If a preference is set here it will be stored within the cache & database upon initialization.
+#       Just removing an entry from this initializer will not make the preference value go away.
+#       Instead you must either set a new value or remove entry, clear cache, and remove database entry.
+#
+# In order to initialize a setting do:
+# config.setting_name = 'new value'
+Spreeference.config do |config|
+  # Example:
+  # config.is_ok = 'Nice!'
+end

data/lib/spreeference.rb

@@ -0,0 +1,16 @@
+require 'spreeference/preferable_methods'
+require 'spreeference/preferable'
+require 'spreeference/configuration'
+require 'spreeference/scoped_store'
+require 'spreeference/store'
+require 'spreeference/environment_extension'
+require 'spreeference/environment'
+
+module Spreeference
+
+  def self.config
+    yield(Spreeference::Config)
+  end
+end
+
+require "spreeference/engine"

data/lib/spreeference/configuration.rb

@@ -0,0 +1,48 @@
+module Spreeference
+  class Configuration
+    include Spreeference::Preferable
+    
+    def configure
+      yield(self) if block_given?
+    end
+
+    def preferences
+      Spreeference::ScopedStore.new(self.class.name.underscore)
+    end
+
+    def reset
+      preferences.each do |name, value|
+        set_preference name, preference_default(name)
+      end
+    end
+
+    alias :[] :get_preference
+    alias :[]= :set_preference
+    alias :get :get_preference
+
+    def set(*args)
+      options = args.extract_options!
+      options.each do |name, value|
+        set_preference name, value
+      end
+
+      if args.size == 2
+        set_preference args[0], args[1]
+      end
+    end
+
+    def method_missing(method, *args)
+      name = method.to_s.gsub('=', '')
+      if has_preference? name
+        if method.to_s =~ /=$/
+          set_preference(name, args.first)
+        else
+          get_preference name
+        end
+      else
+        super
+      end
+    end
+
+  end
+end