listable

With listable you can consolidate fields from several ActiveRecord models
into one, backed up by a database view. It is perfect for e.g. a front page
where you may want to display the most recent additions to your site in a
joint list. By providing scopes for each model you wish to include in a
view, listable will automatically create the database view for you. The
view model and the models it lists will have a polymorphic association for
convenience. Listable currently supports the following connection adapters:
SQLite, PostgreSQL and MySQL2.

Requirements

ActiveRecord >= 3.2

Tested with Rails 4

How to use

This chapter shows some basic examples of all the steps needed to get
started.

Configuring the models

Every model that should be listable in the same context must provide a
scope that select columns of the same name, in the same order and with
compatible data types. Listable extends ActiveRecord with two query methods
to make this easy without being forced to write database specific SQL in
your models. N.B. The timestamps “created_at” and “updated_at” will be
include automatically, so don't include them in the scope.

Here is a basic example:

classEmployee<<ActiveRecord::Base# This model will be listable through the view backed model ListItem,# with the data provided by the "listables" scope listable_through:list_item,:listables# The "first_name" and "last_name" columns will be concatenated and selected as "name" scope:listables,concat_select([:first_name,' ',:last_name],:name)endclassArticle<<ActiveRecord::Base# You can also provide the target model name in plural if that feels more natural for youlistable_through:list_items,:listables# The select_as method takes a hash as argument, the keys are the original column names# and the values are their new namesscope:listables,select_as(title:'name')endclassListItem<<ActiveRecord::Base# This method call is needed to configure the model correctlyacts_as_listable_viewend

Creating the database views

You can create the database views by running the rake task
listable:create. But you will hardly ever need to do that since
all listable views are automatically (re)created when running Rails'
db:migrate.

The views created by listable will also conveniently be dropped and
recreated when running db:setup or db:reset, and dropped
when running db:drop. If you need to drop the views manually, just
run the rake task listable:drop

Why not generate Rails migrations to create the views?

I believe it is very awkward to create views through migrations for several
reasons. The basic role of a migration is to either add or remove columns
where you can store data. When creating a view, you are not adding more
means to store data. You are just creating an alternative view of
what's already there.

Since a view is 100% dependant on your existing columns, you will need to
recreate the view everytime you need to change the columns it depend on.
Because that's the thing with views, everytime you need to change it,
you will have to drop it and create it again from scratch. You can imagine
how ugly, and not so very DRY, your migrations could end up.

There is also not any built in support for creating views in Rails, which
means you would probably end up writing database specific SQL, which could
potentially become a problem along the way.

Migrations is just not a natural place for views. Just let listable handle
it for you instead…

# index.html.erbrender@items# _list_item.html.erbcontent_tag:h1,list_item.namelink_tolist_item.listable# Links to the original model

Contributing to listable

Check out the latest master to make sure the feature hasn't been
implemented or the bug hasn't been fixed yet.

Check out the issue tracker to make sure someone already hasn't
requested it and/or contributed it.

Fork the project.

Start a feature/bugfix branch.

Commit and push until you are happy with your contribution.

Make sure to add tests for it. This is important so I don't break it in
a future version unintentionally.

Please try not to mess with the Rakefile, version, or history. If you want
to have your own version, or is otherwise necessary, that is fine, but
please isolate to its own commit so I can cherry-pick around it.