List Widget

The list widget displays a table with sortable columns and interactive filters. It also allows you browse through a dataset without displaying it all (paginate).

A list within an application can look like this:

The columns are links, clicking on them will change the sort order. The field below the column title are input boxes and allows filtering per columns. The column named 'Virtual' isn't a real database table, it is virtual and can contain any dynamic value that you want to define. Also the 'User' columns is dymically rewritten to be a link. The 1,2,3 links are to browse within the list (it only displays 10 rows at this configuration, but actually contains more rows).

Cuca has two lists, both with BaseListWidget as parent:
* StaticListWidget (static lists from memory)
* DBListWidget (Takes an ActiveRecord Model as DataSource)

Static Data Lists

The following code will produce a StaticDataListWidget with some dummy data:

 class IndexController < ApplicationController
   def run
     mab do 
       StaticList('list_name',
             :columns => [ { :id => 'id',    :display=>'ID' },
                           { :id => 'name',  :display=>'Name' } ],
             :data    => [[ 1, 'Jack'],
                          [ 2, 'Elvis'],
                          [ 3, 'Alice'],
                          [ 4, 'Tarzan'])
     end
   end
 end 

To get more out of StaticList it's always good to create your own widgets derived from StaticDataListWidget. You should use the setup method to initiate the widgets data. The example below creates a 100 row list with useless data and rewrites the id column to be a link. The list remains fully sortable and searchable.

class TestListWidget < StaticDataListWidget
 def setup
   d = []
   (1..100).each do |n| 
      d << [ "User #{n}", n]
    end
    @sd_columns = [ { :id=>'username', :display => "User Name" },
                    { :id=>'id', :display=>'ID #' }
                  ]
    @sd_data = d

   add_rewrite_hook('id') { |row,field| "<a href='/user/#{field}/'>Number #{field}</a>" }
 end
end

Database Lists

class UserlistWidget < DBListWidget
 def setup

   @columns = [    {:id=>'id', :query => 'users.id', :display => "#"},
                   {:id=>'username', :display => "User"},
                   {:id=>'firstname', :display => "First name"},
                   {:id=>'lastname', :display => "Last Name"},
                   {:id=>'test', :display=>"Virtual", :query=>false },
                   {:id=>'agent_name', :query => 'agents.name', :display => "Agent"}]

   @model_class = User
   @joins = 'LEFT JOIN agents on users.agent_id = agents.id'

   add_rewrite_hook('test') { |row,field| "Maybe '#{row[3]}'" }
   add_rewrite_hook('firstname') { |row,field| "<b>#{field}</b>" }
   add_rewrite_hook('username') { |row,field| "<a href='/user/#{field}/'>#{field}</a>" }
 end
end

• The @columns Array takes besides :id (internal id) and :display (how the columns should be displayed) another key: :query. If :query is defined it tries to SELECT the field by using it's value. This is needed for joins and whenever columns names are ambiguous. If :query is false however DBList will not try to fetch this value from the database and it should be filled using rewrite hooks.
• The @joins can contain sql parts for the SELECT to join other tables. This will be passed into ActiveRecord::find - :join parameter.
• The code you pass to add_rewrite_hook will be yielded every time we pass one row. It will contain the complete row data plus the field it was run against. The field will be rewritten to whatever you return from the block.
• This will return a list same as the application screenshot on top of the page.