selections 0.0.1 → 0.1.1

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+.idea/

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 0.0.1
+
+* Initial release

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in selections.gemspec
+gemspec

data/{MIT-LICENSE → LICENSE.txt}

@@ -1,4 +1,6 @@
-Copyright 2012 YOURNAME
+Copyright (c) 2012 Nigel Rausch
+
+MIT License
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the
@@ -17,4 +19,4 @@ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
 LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,237 @@
+# Selections
+
+Selection list management and form and view helpers.
+
+##Key Features
+
+* Manages one table to hold all selections items/ dropdown lists ( tree )
+* Dynamic lookup to find parent or children ( eg. Selection.priorities )
+* Form helper to display lists ( eg. f.selections :priorities )
+* Model helpers for joining tables ( eg. belongs_to_selection :priority )
+* Handling of archived items ( displaying if selected only )
+* Ordering of lists based on alpha or numbered
+* Default item handling
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'selections'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install selections
+
+## Usage
+
+First, you need to configure your selection model. We typically use `Selection` for this (although you
+can change the name), and should be generated such as:
+
+```ruby
+rails generate model Selection name parent_id:integer system_code position_value:integer is_default:boolean is_system:boolean archived_at:datetime
+```
+
+### Model
+And next, edit this class to look like:
+
+```ruby
+class Selection < ActiveRecord::Base
+  selectable
+end
+```
+
+Selections table can contain one or many lists, it uses the acts_as_tree so each root is a new list
+meta example: (see below for example YAML file)
+ - priority
+   - high
+   - medium
+   - low
+ - user_role
+   - admin
+   - owner
+   - user
+
+From the rails console it is be possible to access these items directly using dynamic lookups
+
+```ruby
+Selection.priority => returns the parent row
+Selection.user_role
+```
+
+Dynamic lookups support pluralization and will then return the children
+
+```ruby
+Selection.priorities => [high,med,low] records
+```
+
+#### Form Helper
+
+if we had a controller for Ticket model with fields of
+- name
+- priority_id
+
+within the _form.html.erb just use the selections helper method
+
+```ruby
+<%= form_for(@ticket) do |f| %>
+
+  <div>
+    <%= f.label :name %><br />
+    <%= f.text_field :name %>
+  </div>
+
+  <div>
+    <%= f.label :priority %><br />
+    <%= f.selections :priority %>
+  </div>
+
+  <div>
+    <%= f.submit %>
+  </div>
+<% end %>
+```
+
+If you have naming conflicts/duplicates eg. user categories and ticket categories within in the selections name the parent/system_code
+user_category & ticket_category. The foreign key within the user and ticket can both be category_id and the form_helper will still be
+
+user form
+```ruby
+f.selections :category
+```
+this will automatically look up the user_category selections.
+
+If you have a selection named differently to the foreign key eg the foreign key is variety_id, you can use a system_code option
+
+```ruby
+f.selections :variety, :system_code => :category
+```
+
+Next, you need to tell models that have a selectable association. These are `belongs_to` associations
+which pull their values from the selections model. Assuming you have a `Ticket` model with a foreign key of priority_id,
+you can set this up like so:
+
+```ruby
+class Ticket < ActiveRecord::Base
+
+  belongs_to_selection :priority
+
+end
+```
+
+From an instance of a ticket within a view the belongs_to selection will return string (to_s).
+eg: show.html.erb
+
+
+```ruby
+  ticket.priority.try(:name) # don't need to do this
+
+  ticket.priority # will default to return name
+```
+
+### Automatic Features
+#### Include Blank
+
+In a new form the selections list will have blank top row unless a default item is set in the selections eg. Medium Priority, then there
+will be no blank row and the default item will be selected
+
+When editing a form, by default the blank row will not be displayed
+
+#### Archived Item
+
+On a new form items that are archived in Selections will not appear in the selection list. When editing an existing record the list will only
+contain un-archived items, unless the item selected is archived it will then appear.
+
+eg. A ticket has a priority set to high, later the high selection list item was archived, when we edit the ticket record again the item will show in the list even though it is archived
+
+#### Order
+
+The list will by default display in alphanumeric order, unless you add position values and then it will display in the values.
+
+## Configuration
+
+If you use a class name other than `Selection` as your selection model, you must
+tell selections so by adding the following to a new file, `config/initializers/selections.rb`:
+
+```ruby
+Selections.model { YourSelectionModel }
+```
+
+# TODO
+
+* Add model generators
+* Add selections management scaffold/generator
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## YAML example
+
+```yaml
+priority:
+  name: Priorities
+  parent:
+  position_value:
+  system_code: priority
+  is_system: false
+priority_high:
+  name: High
+  parent: priority
+  position_value: 30
+  system_code: $LABEL
+  is_system:
+priority_medium:
+  name: Medium
+  parent: priority
+  position_value: 20
+  system_code: $LABEL
+  is_system:
+priority_low:
+  name: Low
+  parent: priority
+  position_value: 10
+  system_code: $LABEL
+  is_system:
+  is_default: true
+
+
+contact_category:
+  name: Contact Categories
+  parent:
+  position_value:
+  system_code: contact_category
+  is_system: false
+contact_category_junior:
+  name: Junior Tech
+  parent: contact_category
+  position_value:
+  system_code: $LABEL
+  is_system:
+contact_category_senior:
+  name: Senior Tech
+  parent: contact_category
+  position_value:
+  system_code: $LABEL
+  is_system:
+contact_category_manager:
+  name: Manager
+  parent: contact_category
+  position_value:
+  system_code: $LABEL
+  is_system:
+  archived_at: <%= Time.now %>
+contact_category_ceo:
+  name: CEO
+  parent: contact_category
+  position_value:
+  system_code: $LABEL
+  is_system:
+```

data/Rakefile

@@ -1,31 +1,5 @@
-#!/usr/bin/env rake
-begin
-  require 'bundler/setup'
-rescue LoadError
-  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
-end
-begin
-  require 'rdoc/task'
-rescue LoadError
-  require 'rdoc/rdoc'
-  require 'rake/rdoctask'
-  RDoc::Task = Rake::RDocTask
-end
-
-RDoc::Task.new(:rdoc) do |rdoc|
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = 'Selections'
-  rdoc.options << '--line-numbers'
-  rdoc.rdoc_files.include('README.rdoc')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
-
-APP_RAKEFILE = File.expand_path("../spec/dummy/Rakefile", __FILE__)
-load 'rails/tasks/engine.rake'
-
-
-Bundler::GemHelper.install_tasks
-
+require "bundler/gem_tasks"
 require 'rspec/core/rake_task'
+
 RSpec::Core::RakeTask.new(:spec)
-task :default => :spec
+task default: :spec

data/lib/selections.rb

@@ -1,7 +1,23 @@
-require "rails"
-require "selections/engine"
-require "acts_as_tree"
-require "selections/selection_select"
+require 'selections/version'
+require 'active_record'
+require 'action_view'
 
-#module Selections
-#end
+module Selections
+
+  require 'selections/belongs_to_selection'
+  require 'selections/form_builder_extensions'
+  require 'selections/selectable'
+
+  # Given a block, will set how we find / detect the current model
+  # used for selections, without a block, will return the value.
+  # Note: Needed iff you are using a model other than Selection.
+  def self.model(&block)
+    if block
+      @model = block
+    else
+      @model ||= lambda { Selection }
+      @model.call
+    end
+  end
+
+end

data/lib/selections/belongs_to_selection.rb

@@ -0,0 +1,20 @@
+module Selections
+  module BelongsToSelection
+
+    # Helper for belongs_to and accepts all the standard rails options
+    #
+    #Example
+    #   belongs_to_selection :priority
+    #
+    # by default adds - class_name: "Selection"
+
+    def belongs_to_selection(target, options={})
+      belongs_to target, options.merge(:class_name => "Selection")
+    end
+
+    ActiveSupport.on_load :active_record do
+      extend Selections::BelongsToSelection
+    end
+
+  end
+end

data/lib/selections/form_builder_extensions.rb

@@ -0,0 +1,86 @@
+module Selections
+  module FormBuilderExtensions
+    # Create a select list based on the field name finding items within Selection.
+    #
+    #
+    # Example
+    #   form_for(@ticket) do |f|
+    #     f. select("priority")
+    #
+    # Uses priority_id from the ticket table and creates options list based on items in Selection table with a system_code of
+    # either priority or ticket_priority
+    #
+    # options = {} and html_options = {} suport all the keys as the rails library select_tag does.
+    #
+    # options
+    # * +system_code+ - Overrides the automatic system_code name based on the fieldname and looks up the list of items in Selection
+
+    def selections(field, options = {}, html_options = {})
+      SelectionTag.new(self, object, field, html_options, options).to_tag
+    end
+
+    class SelectionTag #:nodoc:
+      attr_reader :form, :object, :field, :html_options, :options, :selection, :field_id, :system_code_name
+
+      def initialize(form, object, field, html_options, options)
+        @form = form
+        @object = object
+        @field = field
+        @html_options = html_options || {}
+
+        @system_code_name = options[:system_code] || field
+        @selection = Selections.model
+        @field_id ||= (field.to_s + "_id").to_sym
+        @options = options || {}
+      end
+
+      def include_blank?
+        if options[:include_blank].nil?
+          !!((object.try(:new_record?) || !object.send(field_id))) && default_item.blank?
+        else
+          !!options[:include_blank]
+        end
+      end
+
+      def system_code
+        @system_code ||= selection.where(system_code: system_code_name.to_s).first
+        @system_code ||= selection.where(system_code: "#{form.object_name}_#{system_code_name}").first
+      end
+
+      def items
+        @items ||= system_code.children.filter_archived_except_selected(object.send(field_id))
+      end
+
+      def to_tag
+        if system_code
+          #TODO add default style
+          #html_options[:style] ||=
+          options[:include_blank] = include_blank?
+          options[:selected] = selected_item
+          form.select field_id, items.map { |item| [item.name, item.id] }, options, html_options
+        else
+          "Invalid system_code of '#{system_code_name}'"
+        end
+      end
+
+      def selected_item
+        if object.new_record?
+          default_item
+        else
+          object.send(field_id).to_s
+        end
+      end
+
+      def default_item
+        items.where(:is_default => true).first.try(:id).to_s
+      end
+    end
+
+    ActiveSupport.on_load :action_view do
+      ActionView::Helpers::FormBuilder.class_eval do
+        include Selections::FormBuilderExtensions
+      end
+    end
+
+  end
+end