@@ -1,23 +1,39 @@ -Recordselect +RecordSelect ============ (c) 2007 - Lance Ivy -This ActiveScaffold-inspired plugin is a streamlined listing tool with a -dedicated purpose: to let you select one (or more) records from a possibly -large record set. It will report the selected record(s) to a given method -on the controller. +This plugin is a streamlined listing tool with a dedicated purpose: to let you select a record from a possibly large record set in a friendly fashion. It will report the selected record(s) to a given method on the controller or to a JavaScript function on the client. -RecordSelect can also be used as a JavaScript widget. You can tie into a -JavaScript hook that intercepts the selection report so it reports client- -side instead of server-side. +Included is a +link_to_record_select+ helper to assist with embedding a RecordSelect popup in your page. Also included is a +record_select_field+ helper. This helper ties RecordSelect into your form by making it set a hidden input field. Think of it as a paginated and searchable autocomplete dropdown. Or think of it as a <select> replacement that won't bog down with large recordsets. -To use RecordSelect in a RESTful API, add the following to your routes.rb: +To use RecordSelect RESTfully, add the following to your routes.rb: map.resources :model_id, :collection => {:browse => :get}, :member => {:select => :post} -DEPENDENCIES += INSTALL +1. Install from SVN: -This depends on the excellent Paginator gem by Bruce Williams. This simple -gem is available at paginator.rubyforge.org. \ No newline at end of file + <tt>./script/plugin install http://recordselect.googlecode.com/svn/trunk</tt> + +2. Then add the css and javascript to your layout by including the following line: + + <tt><%= record_select_includes %></tt> + += EXAMPLES +* <tt><%= link_to_record_select 'Try Me!', 'users', :onselect => 'alert("#" + id + ": " + label)' %></tt> + + Creates a link that toggles a list of users. When clicked, it alerts the id and label of the user. + +* <tt><%= record_select_field 'user[user_group]', (@user.user_group || UserGroup.new) %></tt> + + Creates a dropdown of user groups on your user form. + += COMING SOON +* Improved record_select_field UI. Instead of a <span> to hold the label, it will have a text field that acts as the search box. Behind the scenes it will still use a hidden input. +* Better support for multi-select. +* Automated tests. Maybe. Talk about a huge blind spot in my knowledge base... + += DEPENDENCIES +This depends on the excellent Paginator gem by Bruce Williams. This simple gem is available at paginator.rubyforge.org. \ No newline at end of file README @@ -19,4 +19,5 @@ Rake::RDocTask.new(:rdoc) do |rdoc| rdoc.options << '--line-numbers' << '--inline-source' rdoc.rdoc_files.include('README') rdoc.rdoc_files.include('lib/**/*.rb') + rdoc.rdoc_files.include('assets/**/*.js') end Rakefile @@ -10,19 +10,23 @@ module ActionView::Helpers end # Adds a link on the page that toggles a RecordSelect widget from the given controller. - # You may define a client-side handler for the widget using +options[:select]+ + # + # *Options* + # +onselect+:: JavaScript code to handle selections client-side. This code has access to three variables: id, label, and container. + # +params+:: Extra URL parameters. If any parameter is a column name, the parameter will be used as a search term to filter the result set. def link_to_record_select(name, controller, options = {}) options[:params] ||= {} options[:params].merge!(:controller => controller, :action => :browse) - options[:onselect] = "function(id, value, container) {#{options[:onselect]}}" if options[:onselect] + options[:onselect] = "function(id, label, container) {#{options[:onselect]}}" if options[:onselect] link_to_function(name, %|RecordSelect.toggle(this, '#{url_for options[:params]}', #{h options[:onselect]})|) end # Adds a RecordSelect-based form field. The field submits the record's id using a hidden input. # - # Unless you have resource controllers (e.g. UsersController for the User model), you should - # specify options[:controller]. + # *Options* + # +controller+:: The controller configured to provide the result set. Optional if you have standard resource controllers (e.g. UsersController for the User model), in which case the controller will be inferred from the class of +current+ (the second argument) + # +id+:: The id to use for the hidden input. Defaults based on the input's name. def record_select_field(name, current, options = {}) options[:controller] ||= current.class.to_s.pluralize.underscore options[:id] ||= name.gsub(/[\[\]]/, '_') @@ -34,23 +38,26 @@ module ActionView::Helpers html << link_to_record_select( "<span class='record-select-input'>#{h label}</span>", options[:controller], - :onselect => "$('#{options[:id]}').value = id; Element.previous(container).childNodes[0].innerHTML = value; Element.remove(container);", + :onselect => "$('#{options[:id]}').value = id; Element.previous(container).childNodes[0].innerHTML = label; Element.remove(container);", :params => options[:params] ) return html end + # A helper to render RecordSelect partials def render_record_select(options = {}) if options[:partial] render :partial => controller.send(:record_select_path_of, options[:partial]), :locals => options[:locals] end end + # Provides view access to the RecordSelect configuration def record_select_config controller.send :record_select_config end + # The id of the RecordSelect widget for the given controller. def record_select_id(controller = nil) controller ||= params[:controller] "record-select-#{controller}" lib/helpers.rb c7f81fee0155aaede7bf998895850364049888a8 Lance Ivy lance@cainlevy.net http://github.com/edwinmoss/recordselect/commit/bcd0fdc1669b9f2f8fb78cb79b15cae1ad7e12a9 bcd0fdc1669b9f2f8fb78cb79b15cae1ad7e12a9 2007-03-02T15:47:38-08:00 2007-03-02T15:47:38-08:00 documentation acfba56f4a7e58833f7cab8a549419dbc6b873c0 Lance Ivy lance@cainlevy.net