assoc_whisperer 2.0.3 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ca1ca5cce6d22e7055f31b9b78882841b189f566
-  data.tar.gz: 1c70ae286a41c2dc043d2c5473a4637c53cac426
+  metadata.gz: 809af461432f6d16ecf7c37cebefa320a0357a69
+  data.tar.gz: e938b814f1fe952c697c9118f2ccd7cc1069f6ca
 SHA512:
-  metadata.gz: ec3f05c46e88412964b0184c6ce8629accca9e8c54bb5ed363b3c810e4f0b69a8ad138f94c558f2117bca923512fc9d3b88e81d35efdafc5710cb5aa1d9cbbf4
-  data.tar.gz: 8724e1498fe5d2b3ac71a1a61f15e5bb6172b8010b3f78bbb32910d9e2f4d5b72da3abba55d101d413e033ccd74f00678b904449aaf339bb6a5be6f707292aa8
+  metadata.gz: a297dd703d02ba14ec9a31494fa42a9d3c454b663d5076e3fec44f0955b54de902abe598a3cd9869b0c17bcc09d7a145d86e691b1fac503ec15bfa3c7759eb80
+  data.tar.gz: 43766aeabec37ae636a8248aaff0bb2a8da670ae82b87a29247abde90887b5c1b70259602288e6a223c71d5c680f7a324eab1d94a945e61de52c8f1aa98d68ae

data/.gitignore

@@ -1,4 +1,3 @@
-*.gem
 *.rbc
 .bundle
 .config

data/Gemfile

@@ -2,3 +2,5 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in assoc_whisperer.gemspec
 gemspec
+
+gem 'yard'

data/README.md

@@ -1,24 +1,229 @@
 # AssocWhisperer
 
-TODO: Write a gem description
+This library served me to bring together some code that was scatered around multiple projects build upon Ruby on Rails. 
+Many times I needed a way to let user enter an associated model into form, but users don't know the exact IDs,
+they know a title or some part of name, etc. But a server needs exact ID. There comes whisperer, common input field,
+using AJAX to show user a narrowed list of desired records.
+This is my version build upon Rails form helpers syntax, encapsulating everything needed but beeing smallest possible.
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'assoc_whisperer'
+    gem 'assoc_whisperer', '~> 2.1.0'
+    
+## Documentation
 
-And then execute:
+Start up yard server and browse the documentation on local:
 
-    $ bundle
+    bundle exec yard doc && bundle exec yard server 
 
-Or install it yourself as:
+## Usage
+
+Let's say you have a bussines where to each project can be assigned only on of your many employees. Having a form
+of a project you'd have to know IDs of those people id database to fill in. Using this whisperer:
+
+```
+<%= form_for @project do |f| %>
+  assigned employee: <%= f.whisperer :employee, whisperer_template('get_employees') %>
+<% end %>
+```
+
+It will render the form with whisperer div that includes a hidden field for desired value and a text field for user input.
+(And optionaly a drop down button).
+
+For more generice use (i. e. without form builder), there's another helper:
+
+```
+<%= form_tag create_project_path %>
+  assigned employee: <%= whisperer_tag :employee_id, whisperer_template('get_employees').from_params(params, :employee_id) %>
+<% end %>
+```
+
+There's quite a lot to adjust on the background so let's go step by step.  
+
+## Basic case background
+
+There's two things needed to set up - the path for that AJAX querry:
+
+```rb
+# set up a controller
+class WhispererController < ApplicationController
+  def get_employees
+    user_input = params[:input]
+    return render(nothing: true, status: :bad_request) unless user_input
+    @objects = Employee.limit 10
+    @objects = @objects.where Employee.arel_table[:surname].matches("%#{user_input}%") unless user_input.empty?
+    render 'assoc_whisperer/list', layout: false
+  end
+end
+# add to routes.rb
+get 'whisp/:action', to: 'whisperer'
+```
+
+And a way to include assets (js and css) on the page
+
+```
+# add to application.js
+//= require assoc_whisp
+# add to application.css
+*= require assoc_whisp_example
+```
+
+Again, the most simple whisperer tag:
+
+```
+<%= form_for @project do |f| %>
+  assigned employee: <%= f.whisperer :employee, whisperer_template('get_employees') %>  
+<% end %>
+```
+
+User fills in 'mori', waits for options to pop up, selects from list the desired person and submits the form:
+
+```rb
+# you'll receive these params
+{'employee_id' => '5', 'employee_txt' => 'Dean Moriarty'}
+# given this record exists:
+Employee.find(5).to_s
+# => "Dean Moriarty"
+```
+
+### Changing default settings
+
+In the basic case, we were stuck with default options. First there's that you get ID behind #id of the object 
+and user sees string that returns #to_s method. 
+
+```rb
+AssocWhisperer.def_value = :my_id           # def: :id
+AssocWhisperer.def_text = :to_my_string     # def: :to_s
+```
+
+You can modify the path for AJAX request. reflect the change also in routes.rb  
+
+```rb
+AssocWhisperer.def_url = '/whisperer/path'  # def: '/whisp'
+```
+
+If you don't want to attach whisperers assets for every page (i.e. in application.js), there's option to define a method
+that whisperer helpers call internally so it'll be attached only whether whisperer is present on the page.
+
+```rb
+# in application_helper.rb
+def attach_whisperer_assets
+  content_for :addon_assets, javascript_include_tag('assoc_whisp')
+  content_for :addon_assets, stylesheet_link_tag('assoc_whisp_example')
+end
+# to change the helper method
+AssocWhisperer.attach_assets = :custom_whisperer_attach_method 
+```
+
+To make this work, you need insert that content into your layout file, within <head> preferably:
+
+```
+<%= content_for :addon_assets %>
+```
+
+### Templates
+
+If you wanth to whisper the same fing on multiple forms, you can save somewhere the template. The template is there 
+even for change things around.
+
+```rb
+whisperer_template('action') # is just wrapper for AssocWhisperer::Template constructor
+# you can change methods of text and value
+f.whisperer :employee ,whisperer_template('get_employees', text: :full_name, value: :personal_key)
+# you can show up the drop down button
+f.whisperer :employee ,whisperer_template('get_employees', button: true)
+# or define exact path
+f.whisperer :employee ,whisperer_template('/whisperer/get_employees')
+```
+
+### Another way to set up path for AJAX:
+ 
+There a way to send custom params with that particular whisperer. That's usefull if you want to completly
+change controller side of AJAX calls.
+ 
+```rb
+f.whisperer :employee ,whisperer_template('/whisperer').params('get' => 'employees')
+# routes.rb
+get 'whisperer', to: 'whisperer#whisper'
+```
+
+## More complex examples
+
+For sequent examples we're going to use this controller set up:
+
+```rb
+class WhispererController < ApplicationController
+  layout false
+  before_filter :get_input
+  
+  def get_employees
+    @objects = Employee.limit 10
+    @objects = @objects.where deparatment: params[:department] if params[:department].present?     
+    @objects = @objects.where Employee.arel_table[:surname].matches("%#{user_input}%") unless user_input.empty?
+    render 'assoc_whisperer/list', locales: {text: :full_name} # THIS IS IMPORTANT to show right text in list
+  end
+  
+  private
+  
+  def get_input
+    @input = params[:input]
+    render nothing: true, status: :bad_request unless @input
+  end
+  
+end
+```
+
+### Using the most convenient rails form building syntax
+
+If it's the case that can use form builder for given object, it's easy to make things work. This way values will be filled
+even if you return the form to user because some validation errors, for example. Since params will include following,
+you can simply create object of Project and input field will fill automaticaly with what employee user selected:
+
+```rb
+# params include:
+{"project" => {"employee_id" => 5, "employee_txt" => "Dean Moriarty"}}
+
+# in controller's particular action
+@project = Project.new params.require(:project).permit(:employee_id)
+```
+
+And whisperer tag only needs this:
+
+```
+<%= form_for @project do |f| %>
+  assigned employee: <%= f.whisperer :employee, whisperer_template('get_employees', text: :full_name).
+                         params(department: 'management') %>  
+<% end %>
+```
+
+### Use without form builder
+
+Since whisperer tag is not bound to a project that holds association to selected employee, you have to fill in values 
+of that employee back manually. If you have the employee object or it's nil:
+
+```rb
+whisperer_tag :employee_id, whisperer_template('get_employees', text: :full_name).
+  params(department: 'management').for_object(@selected_employee)  
+```
+
+Or set particular values:
+
+```rb
+whisperer_tag :employee_id, whisperer_template('get_employees', text: :full_name).
+  params(department: 'management').value_text(params[:employee_id], params[:employee_id_text])  
+```
+
+There's this short cut for when those values are in some hash, that paramas exactly is:
+
+```rb
+whisperer_tag :employee_id, whisperer_template('get_employees', text: :full_name).
+  params(department: 'management').from_params(params, :employee_id)  
+``` 
 
-    $ gem install assoc_whisperer
 
-## Usage
 
-TODO: Write usage instructions here
 
 ## Contributing
 

data/app/helpers/action_view/helpers/assoc_whisperer_helper.rb

@@ -3,6 +3,43 @@ module ActionView
 
     module AssocWhispererHelper
 
+      # This gets called for the most common case of using {FormBuilder#whisperer}, but directly useful for those situations
+      # when you have a custom class that has a model as an attribute and you cannot use +form_for+ for this class.
+      #
+      #   # Borrow helper class:
+      #   class Borrow
+      #     attr_accessor :book_id, :client
+      #     def book
+      #       @book ||= Book.find_by(id: book_id)
+      #     end
+      #   end
+      #
+      #   # Book model:
+      #   class Book < ActiveRecord::Base
+      #     validates_presence_of :title
+      #   end
+      #
+      #   # in controller
+      #   def request_borrow
+      #     @borrow = Borrow.new
+      #     @borrow.client = Client.find_by id: params[:client_id]
+      #     @borrow.book_id = params[:book_id]
+      #     # do what ever you want with the @borrow
+      #   end
+      #
+      #   # the form
+      #   <%= form_tag request_borrow_path do %>
+      #     <%= hidden_field_tag :client_id, @borrow.client.id %>
+      #     book: <%= whisperer :borrow, :book, whisperer_template('get_books', text: :title) %>
+      #   <% end %>
+      #
+      #   #params will look like this: {"borrow" => {"client_id" => 1, "book_id" => 5, "book_title" => "On the road"}}
+      #
+      # @param [Symbol, String] object_name name of variable that holds the object
+      # @param [Symbol, String] method name of method to get desired model
+      # @param [AssocWhisperer::Template] template whisperer template that specifies resulting tags.
+      # @param [Hash] field_attrs additional attributes for text field input.
+      # @return [String] a html content of asscociation whisperer
       def whisperer(object_name, method, template, field_attrs={})
         raise "Helper '#whisperer' cannot be used in Rails < 4.x. Use '#whisperer_tag' instead." if Rails::VERSION::STRING.to_i < 4
         wrapper_whisperer_assets
@@ -10,6 +47,32 @@ module ActionView
         Tags::AssocWhispererField.new(object_name, method, self, template, field_attrs).render
       end
 
+      # Form helper for generic associaction whisperer tag. It includes a hidden value field, a text field for user input
+      # and optionaly a dropdown button. The list with options that server returns is appended into this tag.
+      #
+      # This generic version is suitable for most situations. For Rails 3 there's no other option anyway.
+      # Arguments sets html name of the value field (the text field has suffix +_txt+ by default),
+      # {AssocWhisperer::Template a whisperer template}
+      # and additional custom attributes for the text field. Thus the latter example overrides text field
+      # name to +book_title+ instead +book_id_txt+ as in the former.
+      #
+      #   my_book_template = AssocWhisperer::Template.new 'get_books'
+      #   whisperer_tag :book_id, my_book_template
+      #   whisperer_tag :book_id, my_book_template, name: :book_title, placeholder: "book's title outset"
+      #
+      # If you want to send additional parametrs with the request please refer to {AssocWhisperer::Template#params}.
+      # If you want to preset some value, e.g. in the case you're returning a form back to user, use either
+      # {AssocWhisperer::Template#from_params} or {AssocWhisperer::Template#value_text} or {AssocWhisperer::Template#for_object}.
+      # The last case depends on what text and value methods are set for given {AssocWhisperer::Template template}.
+      #
+      #   whisperer_tag :book_id, whisperer_tempate('get_books').from_params(params, 'book_id') # params or any Hash
+      #   whisperer_tag :book_id, whisperer_tempate('get_books').value_text(@book.id, @book.to_s)
+      #   whisperer_tag :book_id, whisperer_tempate('get_books').for_object(@book)
+      #
+      # @param [String, Symbol] name base name for the html form inputs.
+      # @param [AssocWhisperer::Template] template whisperer template that specifies resulting tags.
+      # @param [Hash] field_attrs additional attributes for text field input.
+      # @return [String] a html content of asscociation whisperer
       def whisperer_tag(name, template, field_attrs={})
         wrapper_whisperer_assets
 
@@ -17,12 +80,16 @@ module ActionView
                     'data-opts' => template.whisperer_settings.to_json
       end
 
+      # Wrapper for {AssocWhisperer::Template} constructor
+      # @return [AssocWhisperer::Template]
       def whisperer_template(action, opts={})
         AssocWhisperer::Template.new action, opts
       end
 
       private
 
+      # This is wraper for attaching assets (calls a method specified by {AssocWhisperer.attach_assets} - default
+      # is +attach_whisperer_assets+). Gets be called by every whisperer helper but only once assets are attached.
       def wrapper_whisperer_assets
         unless @assoc_whisp_attached
           attach_method = AssocWhisperer.attach_assets
@@ -34,6 +101,37 @@ module ActionView
     end
 
     class FormBuilder
+      # Wraps {AssocWhispererHelper#whisperer} for defaul +FormBuilder+. This enables standard Rails
+      # form building syntax for nested models.
+      #
+      #   # Borrow model:
+      #   class Borrow < ActiveRecord::Base
+      #     belongs_to :client
+      #     belongs_to :book
+      #     validates_presence_of :client, :book
+      #   end
+      #
+      #   # Book model:
+      #   class Book < ActiveRecord::Base
+      #     has_many :borrow
+      #     validates_presence_of :title
+      #   end
+      #
+      #   # in controller
+      #   @borrow = Borrow.new params.require(:borrow).permit(%i(client_id, book_id))
+      #
+      #   # A form for request new borrow in library
+      #   <%= form_for @borrow do |f| %>
+      #     <%= f.hidden_field :client_id %>
+      #     book: <%= f.whisperer :book, whisperer_template('get_books', text: :title) %>
+      #   <% end %>
+      #
+      #   #params will look like this: {"borrow" => {"client_id" => 1, "book_id" => 5, "book_title" => "On the road"}}
+      #
+      # @param [Symbol, String] method name of form object's nested object
+      # @param [AssocWhisperer::Template] template whisperer template that specifies resulting tags.
+      # @param [Hash] field_attrs additional attributes for text field input.
+      # @return [String] a html content of asscociation whisperer
       def whisperer(method, template, field_attrs={})
         @template.whisperer @object_name, method, template, objectify_options(field_attrs)
       end

data/app/helpers/action_view/helpers/tags/assoc_whisperer_field.rb

@@ -9,7 +9,7 @@ module ActionView
         end
 
         def render
-          @whisp_template.value_text whispered_object
+          @whisp_template.for_object whispered_object
 
           contents = @whisp_template.value_field_tag value_tag_id, value_tag_name
           contents += @whisp_template.text_field_tag text_tag_id, text_tag_name, @options

data/assoc_whisperer.gemspec

@@ -8,9 +8,9 @@ Gem::Specification.new do |spec|
   spec.version       = AssocWhisperer::VERSION
   spec.authors       = ["Ondřej Želazko"]
   spec.email         = ["zelazk.o@email.cz"]
-  spec.summary       = %q{Rails tag assoc_whisperer for forms}
-  spec.description   = %q{You can associate two models together, while user inputs e.g. name and server recieves id}
-  spec.homepage      = ""
+  spec.summary       = %q{Rails whisperer tag for forms}
+  spec.description   = %q{Input associated models directly by id}
+  spec.homepage      = "https://github.com/doooby/assoc_whisperer"
   spec.license       = "MIT"
 
   spec.files         = `git ls-files -z`.split("\x0")

data/lib/assoc_whisperer/template.rb

@@ -1,36 +1,85 @@
 # encoding: utf-8
 
 module AssocWhisperer
+
+  # This object specifies what will a whisperer tag look like. {ActionView::Helpers::AssocWhispererHelper#whisperer_template}
+  # is a markup for this class.
   class Template
     attr_reader :opts
 
+    # Creates a template for whisperer.
+    # @param [String] action can be just a tail of url ({AssocWhisperer.def_url}
+    #   will be prefix) or full path eg.: +'/whisperer/specific_path'+.
+    # Options may include:
+    # +:value+:: a method name that is called on given object to get the value the hidden field will be filled with.
+    #            If not specified then {AssocWhisperer.def_value} is used.
+    # +:text+:: a method name that is called on given object to get the value for the text field.
+    #           If not specified then {AssocWhisperer.def_text} is used.
+    # +:button+:: specifies whether dropdown button will be present. Defaults to false.
     def initialize(action, opts={})
       @action = action[0]=='/' ? action : "#{AssocWhisperer.def_url}/#{action}"
       @opts = opts
       @opts[:value] = AssocWhisperer.def_value unless @opts[:value]
       @opts[:text] = AssocWhisperer.def_text unless @opts[:text]
-      @opts[:button] = true if @opts[:button].nil?
+      @opts[:button] = false if @opts[:button].nil?
     end
 
+    # Sets parameters that will be included to html request. Usefull to specify additional options. Because this returns
+    # the template object itself, it is easy to use in views.
+    #   whisperer_tag :foo, whisperer_template('action').params(bar: 5)
+    # Whisperer will call something like this url +/whisp/action?bar=5+
+    # @param [Hash] params
+    # @return [Template]
     def params(params)
       @params = params
       self
     end
 
-    def value_text(object_or_params, name=nil)
-      if object_or_params.is_a?(Hash) && name
-        @value = object_or_params[name]
-        @text = object_or_params["#{name}_txt"]
-      elsif object_or_params
-        @value = (object_or_params.send @opts[:value] if object_or_params.respond_to? @opts[:value])
-        @text = (object_or_params.send @opts[:text] if object_or_params.respond_to? @opts[:text])
-      else
-        @value = nil
-        @text = nil
+    # Sets value and text for given object and returns tepmlate object itself for ease of use.
+    #   whisperer_tag :foo, whisperer_template('action', text: :to_readable_text).value_text(@foo_object)
+    #   # value => FooObject#id (since :id is default method for value specified in AssocWhisperer.def_value)
+    #   # text => FooObject#to_readable_text
+    # @param [Object] object from which will be the value and text taken.
+    # @return [Template]
+    def for_object(object)
+      if object
+        @value = (object.send @opts[:value] if object.respond_to? @opts[:value])
+        @text = (object.send @opts[:text] if object.respond_to? @opts[:text])
       end
       self
     end
 
+    # Sets value and text that is specified in given hash (like params) and returns tepmlate object itself.
+    # In case text is under something else then value name with suffix +_txt+, specify it in last argument.
+    #   params = {'foo' => '15', 'foo_txt' => 'Foo number 15'}
+    #   whisperer_tag :foo, whisperer_template('action').from_params(params, 'foo')
+    #   params = {'foo' => '15', 'foo_bar' => 'Foo number 15'}
+    #   whisperer_tag :foo, whisperer_template('action').from_params(params, 'foo', 'foo_bar')
+    # @param [Hash] hash containing values (like params)
+    # @param [String] value_name the key under which is the value in the hash
+    # @param [String] text_name the key under which is the text in the hash
+    # @return [Template]
+    def from_params(hash, value_name, text_name=nil)
+      @value = hash[value_name]
+      @text = hash[text_name || "#{value_name}_txt"]
+      self
+    end
+
+    # Sets value and text and returns tepmlate object itself.
+    #   whisperer_tag :foo, whisperer_template('action').value_text(foo.id, foo.to_s)
+    # @param [Object] value that will converted to string and filled into hidden input field
+    # @param [String] text that will be filled into text field
+    # @return [Template]
+    def value_text(value, text)
+      @value = value
+      @text = text
+      self
+    end
+
+    # Creates html contents for whisperer (used by {ActionView::Helpers::AssocWhispererHelper#whisperer_tag})
+    # @param [String] input_name for html form name of value and text field tags
+    # @param [Hash] field_attrs additional attributes for text field tag
+    # @return [String] tag html content
     def tag_contents(input_name, field_attrs={})
       input_name = input_name.to_s
       sanitized_id = input_name.dup.delete(']').gsub(/[^-a-zA-Z0-9:.]/, "_")
@@ -42,6 +91,8 @@ module AssocWhisperer
       contents + dropdown_button_tag
     end
 
+    # This is used for whisperer's +data-opts+ html attribute
+    # @return [Hash] whisperer's settings
     def whisperer_settings
       h = {action: @action}
       # h[:cs] = @opts[:client_side] if @opts[:client_side]
@@ -49,10 +100,14 @@ module AssocWhisperer
       h
     end
 
+    # Creates html contents for hidden field that holds a value
+    # @return [String] hidden field html
     def value_field_tag(id, name)
       %(<input type="hidden" id="#{id}" name="#{name}" value="#{@value}" class="value_field">)
     end
 
+    # Creates html contents for text field
+    # @return [String] text field html
     def text_field_tag(id, name, attrs={})
       attrs[:size] = 12 unless attrs.has_key? :size
       keys_whitelist = (attrs.keys & [:size, :placeholder, :maxlength, :title])
@@ -63,6 +118,9 @@ module AssocWhisperer
       %(<input type="text" autocomplete="off" id="#{id}" name="#{name}" value="#{@text}" class="text_field#{' unfilled' unless @value}"#{attrs * ' '}>)
     end
 
+    # Creates html contents for drop down button. If +:button+ option is anything else then TrueClass,
+    # empty string is returned.
+    # @return [String] span html
     def dropdown_button_tag
       return '' unless @opts[:button].is_a? TrueClass
       "<span class=\"dropdown_button querying\">\u25BE</span>"

data/lib/assoc_whisperer/version.rb

@@ -1,5 +1,5 @@
 # encoding: utf-8
 module AssocWhisperer
-  VERSION = "2.0.3"
+  VERSION = "2.1.0"
 
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: assoc_whisperer
 version: !ruby/object:Gem::Version
-  version: 2.0.3
+  version: 2.1.0
 platform: ruby
 authors:
 - Ondřej Želazko
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-12-30 00:00:00.000000000 Z
+date: 2015-01-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -38,8 +38,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: You can associate two models together, while user inputs e.g. name and
-  server recieves id
+description: Input associated models directly by id
 email:
 - zelazk.o@email.cz
 executables: []
@@ -62,7 +61,7 @@ files:
 - lib/assoc_whisperer.rb
 - lib/assoc_whisperer/template.rb
 - lib/assoc_whisperer/version.rb
-homepage: ''
+homepage: https://github.com/doooby/assoc_whisperer
 licenses:
 - MIT
 metadata: {}
@@ -82,8 +81,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.3
+rubygems_version: 2.4.5
 signing_key: 
 specification_version: 4
-summary: Rails tag assoc_whisperer for forms
+summary: Rails whisperer tag for forms
 test_files: []
+has_rdoc: