raw 0.49.0

data/lib/raw/helper/pager.rb

@@ -0,0 +1,305 @@
+require 'facets/more/settings'
+
+require 'og/collection'
+
+module Raw
+
+# Displays a collection of entitities in multiple pages.
+#
+# === Design
+#
+# This pager is carefully designed for scaleability. It stores 
+# only the items for one page. The key parameter is needed, 
+# multiple pagers can coexist in a single page. The pager 
+# leverages the SQL LIMIT option to optimize database 
+# interaction.
+
+class Pager
+  # Items per page.
+  
+  setting :per_page, :default => 10, :doc => 'Items per page'  
+  
+  # The request key.
+  
+  setting :key, :default => '_page', :doc => 'The request key'
+
+  # The current page.
+  
+  attr_accessor :page
+
+  # Items per page.
+  
+  attr_accessor :per_page 
+  
+  # The total number of pages.
+  
+  attr_accessor :page_count 
+  
+  # Total count of items.
+  
+  attr_accessor :total_count
+    
+  def initialize(request, per_page, total_count, key = Pager.key)
+    raise 'per_page should be > 0' unless per_page > 0
+  
+    @request, @key = request, key
+    @page = (request.query[key] || 1).to_i
+    @per_page = per_page
+    set_count(total_count)
+    @start_idx = (@page - 1) * per_page    
+  end
+
+  def set_count(total_count)
+    @total_count = total_count
+    @page_count = (@total_count.to_f / @per_page).ceil
+  end
+
+  # Return the first page index.
+  
+  def first_page
+    return 1
+  end
+  
+  # Is the first page displayed?
+  
+  def first_page?
+    @page == 1
+  end
+  
+  # Return the last page index.
+  
+  def last_page 
+    return @page_count
+  end
+  
+  # Is the last page displayed?
+  
+  def last_page?
+    @page == @page_count
+  end
+  
+  # Return the index of the previous page.
+  
+  def previous_page
+    return [@page - 1, 1].max()
+  end
+
+  # Return the index of the next page.
+  
+  def next_page
+    return [@page + 1, @page_count].min()
+  end
+
+  # A set of helpers to create links to common pages.
+  
+  for target in [:first, :last, :previous, :next]
+    eval %{
+      def link_#{target}_page
+        target_uri(#{target}_page)
+      end
+      alias_method :#{target}_page_uri, :link_#{target}_page
+      alias_method :#{target}_page_href, :link_#{target}_page
+    }
+  end
+  
+  # Iterator
+  
+  def each(&block)
+    @page_items.each(&block)
+  end
+  
+  # Iterator
+  # Returns 1-based index.
+  
+  def each_with_index
+    idx = @start_idx
+    for item in @page_items
+      yield(idx + 1, item)
+      idx += 1
+    end
+  end
+  
+  # Is the pager empty, ie has one page only?
+  
+  def empty?
+    return @page_count < 1
+  end
+  
+  # The items count.
+  
+  def size
+    return @total_count
+  end
+  
+  # Returns the range of the current page.
+  
+  def page_range
+    s = @idx
+    e = [@idx + @items_per_page - 1, all_total_count].min
+    
+    return [s, e]
+  end
+  
+  # Override if needed.
+  
+  def nav_range
+    # effective range = 10 pages.
+    s = [@page - 5, 1].max()
+    e = [@page + 9, @page_count].min()
+    
+    d = 9 - (e - s)
+    e += d if d < 0
+    
+    return (s..e)
+  end
+
+  # To be used with Og queries.
+    
+  def limit
+    if @start_idx > 0
+      { :limit => @per_page, :offset => @start_idx }
+    else
+      { :limit => @per_page }
+    end
+  end
+
+  def offset 
+    @start_idx
+  end
+
+  # Create an appropriate SQL limit clause.
+  # Returns postgres/mysql compatible limit.
+  
+  def to_sql
+    if @start_idx > 0
+      return "LIMIT #{@per_page} OFFSET #{@start_idx}"
+    else
+      # gmosx: perhaps this is optimized ? naaaaaah...
+      return "LIMIT #{@per_page}"
+    end
+  end  
+
+  # Override this method in your application if needed.
+  #--
+  # TODO: better markup.
+  #++
+  
+  def navigation
+    nav = ""
+    
+    unless first_page?
+      nav << %{
+        <div class="first"><a href="#{first_page_href}">First</a></div>
+        <div class="previous"><a href="#{previous_page_href}">Previous</a></div>
+      }
+    end
+    
+    unless last_page?
+      nav << %{
+        <div class="last"><a href="#{last_page_href}">Last</a></div>
+        <div class="next"><a href="#{next_page_href}">Next</a></div>
+      }
+    end
+
+    nav << %{<ul>}
+    
+    for i in nav_range()
+      if i == @page
+        nav << %{
+          <li class="active">#{i}</li>
+        }
+      else
+        nav << %{
+          <li><a href="#{target_uri(i)}">#{i}</a></li>
+        }      
+      end
+    end
+    
+    nav << %{</ul>}
+    
+    return nav
+  end
+  alias_method :links, :navigation
+
+  def navigation_needed?
+    @page_count > 1
+  end
+  alias_method :navigation?, :navigation_needed?
+
+private
+
+  # Generate the target URI.
+   
+  def target_uri(page)
+    uri = @request.uri.to_s
+    
+    if uri =~ /[?;]#{@key}=(\d*)/
+      return uri.gsub(/([?;]#{@key}=)\d*/) { |m| "#$1#{page}" }
+    elsif uri =~ /\?/
+      return "#{uri};#{@key}=#{page}"
+    else
+      return "#{uri}?#{@key}=#{page}"
+    end   
+  end
+
+end
+
+# Pager related helper methods.
+
+module PagerHelper
+
+private
+  
+  # Helper method that generates a collection of items and the
+  # associated pager object.
+  #
+  # === Example
+  #
+  # entries, pager = paginate(Article, :condition => 'title LIKE %Ab%', :per_page => 10)
+  # 
+  # or 
+  #
+  # items = [ 'item1', 'item2', ... ]
+  # entries, pager = paginate(items, :per_page => 10)
+  # 
+  # or
+  #
+  # entries, pager = paginate(article.comments, :per_page => 10)
+  #
+  # <ul>
+  # <?r for entry in entries ?>
+  #    <li>#{entry.to_link}</li>
+  # <?r end ?>
+  # </ul>
+  # #{pager.links}
+  
+  def paginate(items, options = {})
+    per_page = options.delete(:per_page) || options[:limit] || Pager.per_page
+    pager_key = options.delete(:pager_key) || Pager.key
+    
+    case items
+      when Array
+        items = items.dup
+        pager = Pager.new(request, per_page, items.size, pager_key)
+        items = items.slice(pager.offset, pager.per_page) || []
+        return items, pager      
+      
+      when Og::Collection
+        collection = items
+        pager = Pager.new(request, per_page, collection.count, pager_key)
+        options.update(pager.limit)
+        items = collection.reload(options)
+        return items, pager
+      
+      when Class
+        klass = items
+        pager = Pager.new(request, per_page, klass.count(options), pager_key)
+        options.update(pager.limit)
+        items = klass.all(options)
+        return items, pager
+    end
+  end
+  
+end
+
+end

data/lib/raw/helper/table.rb

@@ -0,0 +1,247 @@
+require "facets/more/settings"
+
+require "glue/uri"
+
+module Raw
+
+# The TableBuilder is a helper class that automates the creation
+# of tables from collections of objects. The resulting html
+# can be styled using css.
+#
+# === Example
+#
+# <?r
+# users = User.all.map { |u| [u.name, u.first_name, u.last_name, u.email] }
+# headers = ['Username', 'First name', 'Last name', 'Email']
+# ?>
+# 
+# <div class="custom-table-class">
+#   #{table :values => users, :headers => header}
+# </div>
+# 
+# 
+# === Extended Example
+# 
+#  <?r
+#  users = User.all.map { |u| [u.name, u.first_name, u.last_name, u.email] }
+#  headers = ['Username', 'First name', 'Last name', 'Email']
+#  order_opts = { :right => true, # right align the order controls
+#       :values => [nil, 'first_name', 'last_name'], # column names from DB
+#       :asc_pic => "/images/asc.png", 
+#       :desc_pic => "/images/desc.png" }
+#  ?>
+#  
+#  <div class="custom-table-class">
+#    #{table :values => users, :headers => header, 
+#     :order => order_opts, :alternating_rows => true }
+#  </div>
+# 
+#--
+# TODO: legend, verbose... ?
+# TODO, gmosx: Remove crappy, bloatware additions.
+#++
+
+module TableHelper
+  
+  # The order by key.
+  
+  setting :order_by_key, :default => '_order_by', :doc => 'The order key'
+  
+  # The order by key.
+  
+  setting :order_direction_key, :default => '_order_direction', :doc => 'The order direction key'
+
+  # [+options+]
+  #    A hash of options.
+  # 
+  # :id = id of the component.
+  # :class = class of the component
+  # :headers = an array of the header values
+  # :values = an array of arrays.
+  # :order = options hash (:left, :right, :asc_pic, :desc_pic, :values)
+  # :alternating_rows = alternating rows, use css to color row_even / row_odd
+  # :footers = an array of tfooter values
+  
+  def table(options)
+    str = '<table'
+    str << %| id="#{options[:id]}"| if options[:id]
+    str << %| class="#{options[:class]}"| if options[:class]
+    str << '>'
+    
+    str << table_rows(options)
+    
+    str << '</table>'
+  end
+  alias_method :build_table, :table
+  
+  # [+options+]
+  #    A hash of options.
+  # 
+  # :headers = an array of the header values
+  # :values = an array of arrays.
+  # :order = options hash (:left, :right, :asc_pic, :desc_pic, :values)
+  # :alternating_rows = alternating rows, use css to color row_even / row_odd
+  # :footers = an array of tfooter values
+  
+  def table_rows(options)
+    # also accept :items, :rows
+    options[:values] = options[:values] || options[:items] || options[:rows]
+
+    str = ''
+    str << table_header(options) if options[:headers]
+    str << table_footer(options) if options[:footers]
+    
+    items = options[:values]
+    
+    row_state = 'odd' if options[:alternating_rows]
+    
+    # when items is an array of arrays of arrays (meaning, several
+    # arrays deviding the table into several table parts (tbodys))
+    
+    if create_tbody?(options)
+      for body in items
+        str << '<tbody>'
+        
+        for row in body
+          str << '<tr'
+          
+          if options[:alternating_rows]
+            str << %| class="row_#{row_state}"|
+            row_state = (row_state == "odd" ? "even" : "odd")
+          end
+          
+          str << '>'
+          
+          for value in row
+            str << %|<td>#{value}</td>|
+          end
+          
+          str << '</tr>'
+        end
+        
+        str << '</tbody>'
+      end
+    else
+      for row in items
+        str << '<tr'
+        
+        if options[:alternating_rows]
+          str << %| class="row_#{row_state}"|
+          row_state = (row_state == "odd" ? "even" : "odd")
+        end
+        
+        str << '>'
+        
+        for value in row
+          str << %|<td>#{value}</td>|
+        end
+        
+        str << '</tr>'
+      end
+    end
+    
+    return str
+  end
+  
+  private
+  
+  # [+options+]
+  #    A hash of options.
+  # 
+  # :id = id of the component.
+  # :headers = an array of the header values
+  # :values = an array of arrays.
+  # :order = options hash (:left, :right, :asc_pic, :desc_pic, :values)
+  # :alternating_rows = alternating rows, use css to color row_even / row_odd
+  # :footers = an array of tfooter values
+  
+  def table_header(options)
+    str = ''
+    str << '<thead>' if create_tbody?(options) || options[:footers]
+    str << '<tr>'
+    
+    options[:headers].each_with_index do |header, index|
+      if (options[:order] && options[:order][:values] &&
+                            options[:order][:values][index])
+        order_by = options[:order][:values][index]
+        
+        asc_val = if options[:order][:asc_pic]
+           %|<img src="#{options[:order][:asc_pic]}" alt="asc" />|
+        else
+          '^'
+        end
+        desc_val = if options[:order][:desc_pic]
+           %|<img src="#{options[:order][:desc_pic]}" alt="desc" />|
+        else
+          'v'
+        end
+        
+        order_asc = "<a href='#{target_uri(order_by, 'ASC')}'>#{asc_val}</a>"
+        order_desc = "<a href='#{target_uri(order_by, 'DESC')}'>#{desc_val}</a>"
+        
+        str << '<th><table width="100%" cellspacing="0" cellpadding="0"><tr>'
+        
+        if options[:order][:left] || !options[:order][:right]
+          str << "<th>#{order_asc}<br />#{order_desc}</th>"
+        end
+        
+        str << %|<th>#{header}</th>|
+        
+        if options[:order][:right]
+          str << "<th>#{order_asc}<br />#{order_desc}</th>"
+        end
+        
+        str << '</tr></table></th>'
+      else
+        str << %|<th>#{header}</th>|
+      end
+    end
+    
+    str << '</tr>'
+    str << '</thead>' if create_tbody?(options) || options[:footers]
+    
+    return str
+  end
+  
+  # [+options+]
+  #    A hash of options.
+  # 
+  # :id = id of the component.
+  # :headers = an array of the header values
+  # :values = an array of arrays.
+  # :order = options hash (:left, :right, :asc_pic, :desc_pic, :values)
+  # :alternating_rows = alternating rows, use css to color row_even / row_odd
+  # :footers = an array of tfooter values
+  
+  def table_footer(options)
+    str = '<tfoot><tr>'
+    
+    for footer in options[:footers]
+      str << %|<td>#{footer}</td>|
+    end
+    
+    str << '</tr></tfoot>'
+    
+    return str
+  end
+  
+  # Generate the target URI.
+  
+  def target_uri(order_by, direction)
+    params = { TableHelper.order_by_key => order_by, 
+              TableHelper.order_direction_key => direction }
+    
+    return Glue::UriUtils.update_query_string(request.uri.to_s, params)
+  end
+  
+  #--
+  # gmosx: Arrgh!! dangerous method, who added this?
+  #++
+  
+  def create_tbody?(options)
+    options[:values][0][0].respond_to?(:to_ary)
+  end
+
+end
+
+end