meskyanichi-is_listable

= Is Listable

"Is Listable" is a gem that provides a way to implement a simple listing method by using generated view helpers to create up and down buttons. This will allow you to very quickly get the "Move Up" and "Move Down" button functionality to move your database records up and down in order.

This plugin depends on the acts_as_list plugin. I have created a gem version out of it for convenience when installing this gem.

== Installation

gem sources -a http://gems.github.com sudo gem install meskyanichi-is_listable

== Simple Setup

==== Initializing the gems inside "environment.rb" config.gem "meskyanichi-is_listable", :lib => "is_listable", :source => 'http://gems.github.com' config.gem "meskyanichi-acts_as_list", :lib => "acts_as_list", :source => 'http://gems.github.com'

==== PostModel class Post < ActiveRecord::Base acts_as_list end

==== PostsController class PostsController < ApplicationController is_listable end

==== PostsController#index

<% @posts.each do |post| %> <% end %>

Position	Name
<%= up_button_for_posts(post)	<%= down_button_for_posts(post)	<%= post.name %>

This is basically all it takes to already get the gems working their magic. This will by default assume the posts table in the database has a "position" column which will determine the records position.

== Additional Options

Here's what additional options you can pass to the methods provided by the Is Listable gem.

=== is_listable

The is_listable method takes a hash of options. These are the following options you can provide:

• :column (default: 'position')
• :controller (default: the invoked methods' controller name)
• :model (default: the invoked methods' controller name, pluralized and camelcased)
• :scope (default: nil)
• :redirect_to (default: :back)

View the implementation examples below:

==== :column Specify the column name that represents the position in the database class PostsController < ApplicationController is_listable :column => 'position' end

==== :controller Specify the controller name which the is_listable should be invoked on. 99% of the time you do not need to provide it, as the is_listable method knows what controller invoked it. class PostsController < ApplicationController is_listable :controller => "posts" end

==== :model Specify the model name which the is_listable should be invoked on. By default it will try to use (in this case) the Post model, since it's the singular and camelcased "posts". If Post is not the model you wish to the PostController make listable, just provide the :model hash value of the model you would like to sort. class PostsController < ApplicationController is_listable :model => "Post" end

==== :scope Pass in an ActiveRecord object that's associated to the model. It is mainly to prevent user's from haxing the web app and then updating other users' record position. So this is a very simple solution that'll prevent it from happening. class PostsController < ApplicationController is_listable :scope => current_user end

==== :redirect_to This option will allow you to specify a location to redirect to after the sort process has completed. By default it will redirect back to the page the request came from. class PostsController < ApplicationController is_listable :redirect_to => {:controller => "posts", :action => "index"} end

==== :permalink Let's say that you are using permalinks to allow pretty URL's. This would normally conflict since is_listable only accepts objects as a parameter in the view helpers that are provided. However, the :permalink option will fix this problem! If you are using, for example, the plugin "permalink_fu" and let it handle the creation of permalinks, you will most likely have permalinks stored in the "permalink" attribute inside your database. If this is the case, you can let is_listable work together with it like so. Note: Of course, if the permalink attribute inside the database is called, for example, "perm", you just replace the string "permalink" with "perm". class PostsController < ApplicationController is_listable :permalink => "permalink" end

=== up_button_for_object and down_button_for_object

Once the is_listable method is invoked on a controller, it will generate two view helpers which will be available to all views. This is a very simple implementation, and the arguments taken are similar to those of the link_to and button_to methods provided by Rails.

up_button_for_posts(post, options)

The first argument you must provide, should be the ActiveRecord object that's, for example, currently inside a @objects.each loop. The second argument takes a hash of options. Like the link_to() and button_to() they will accept "url" and "html" attributes.

up_button_for_posts(post, { :url => { :controller => 'posts , :action => 'position', :direction => 'higher', :id => post}, :html => { :id => "posts_up_button_#{post.id}", :class => "posts_up_button" } })

So like the example above, you can add any additional, or overwrite existing attributes/options inside the second argument as a hash. Note that, by default, the view helpers will automatically render out the id/class attributes on the html button tag the same as in the example above. So you can easily apply styles to the provided classes and perform javascript calls on these unique ids namings.

down_button_for_posts(post, { :url => { :controller => 'posts , :action => 'position', :direction => 'lower', :id => post}, :html => { :id => "posts_down_button_#{post.id}", :class => "posts_down_button" } })

So the work is basically done unless you are trying to accomplish something a little more complex that the defaults do not provide. But, usually this is not the case and you can just call the simple method like so:

up_button_for_posts(post)

However, what you might want to change frequently is the name/label of the button. By default the up_button_for_objects and the down_button_for_objects will either name the button "up" or "down" depending on which was called. To overwrite the defaults, you simply provide a name key/value of "name" like so:

up_button_for_posts(post, :name => "Move Up")

This will change the "Up" label to "Move Up".

== Copyright

Copyright (c) 2009 Michael van Rooijen. See LICENSE for details.