Assignment Lists¶ ↑

Version

0.2

Author

Yuri Leikind

Website

leikind.org/pages/wice-assignment-lists

Email

“Yuri Leikind” <yuri.leikind at gmail dot com>

Assignment Lists makes it dead easy to create a widget consisting of two multiple selection lists with items moveable from one to another, and an ajax filter field for the left list to simplify searching for elements.

Assignment Lists fits well as the UI for has_many and has_and_belongs_to_many relations.

Assignment Lists can work under Prototype or jQuery. See installation instructions.

Assignment Lists works with Rails 2.3.8 with or without rails_xss.

Installation¶ ↑

Install the plugin:

script/plugin install  http://github.com/leikind/wice_assignment_lists.git

If the application is prototype-based:

./script/generate  assignment_lists_prototype

Require the javascript file from your template:

<%= javascript_include_tag 'assignment_lists_prototype' %>

If the application is jquery-based:

./script/generate  assignment_lists_jquery

Require the javascript file from your template:

<%= javascript_include_tag 'assignment_lists_jquery' %>

Require the stylesheet:

<%= stylesheet_link_tag 'assignment_lists' %>

Prototype & jQuery¶ ↑

The plugin works under Prototype and jQuery. There is a separate JS file for each framework. The generators copies the correct file to the public directory.

If you want to change the JS framework manually, copy the correct file and change constant AssignmentLists::Defaults::JS_FRAMEWORK in config/initializers/ass_lists_config.rb

Example¶ ↑

Models:

class Role < ActiveRecord::Base
   has_and_belongs_to_many :users
end

class User < ActiveRecord::Base
   has_and_belongs_to_many :roles
end

Routes:

map.resource :roles, :collection => {:filter => :post}

Controller :

class RolesController < ActionController::Base
  layout 'common'

  def edit
    @administrator_role = Role.find(:first)
    @all_users         = User.find(:all)
  end

  def update
    @administrator_role = Role.find(:first)
    @administrator_role.users = params[:users].blank? ? [] : User.find(params[:users])
    redirect_to :action => 'edit'
  end

  def filter
    assignment_lists_filter(:users) do |str|
      User.find(:all, :conditions => ['name LIKE ?', "%" + str + "%"])
    end
  end
end

View:

<% form_tag roles_path, :method =>:put do %>

  <%= assignment_lists(:users, @all_users, @administrator_role.users,
    :filter_path  => filter_roles_path,
    :label1 => 'All users',
    :label2 => 'Administrators') -%>

  <%= submit_tag 'update' %>
<% end %>

The first argument to assignment_lists is the name of the widget, and this is going to be the name of the HTTP parameter which will be sent from the form. The same string or symbol should be the argument to assignment_lists_filter.

This request parameter will contain a list of IDs of objects in the right column.

To retrieve the label of an item in a list, method name is used by default. If it is needed to use a method other than name, parameter method_to_retrieve_object_name can be used to change the default:

<%= assignment_lists(:users, @all_users, @administrator_role.users,
  :method_to_retrieve_object_name => :some_method_name
  :filter_path  => filter_roles_path,
  :label1 => 'All user groups',
  :label2 => 'Groups of the user') -%>

Filtering can turned off completely by omitting the :filter_path parameter, in this mode the widget consists of only two lists and buttons without the filter field.

No filter action is needed in the controller in this case.

Various defaults can be changed in file lib/ass_lists_config.rb.

Icons¶ ↑

Icons used by the plugin are courtesy of Mark James, the creator of the SILK icon set - www.famfamfam.com/lab/icons/silk/.