ramaze 0.1.3 → 0.1.4

data/lib/ramaze/helper/auth.rb

@@ -8,7 +8,7 @@ module Ramaze
   # A really, really, totally stupid way to do authentication. It has no
   # roles and only a single password without usernames.
   #
-  # It is intended to be a simple way to protect various partions of a page
+  # It is intended to be a simple way to protect various portions of a page
   # when you start working on it. Also it is a nice way to see how you could
   # implement your own authentication.
 
@@ -100,7 +100,7 @@ module Ramaze
     #
     #   # The method to be called.
     #   trait :auth_table => :auth_table
-    #   trait :auth_tagle => 'auth_table'
+    #   trait :auth_table => 'auth_table'
     #
     #   # Lambda that will be called upon demand
     #   trait :auth_table => lambda{ {'manveru' => Digest::SHA1.hexdigest 'password'} }

data/lib/ramaze/helper/cache.rb

@@ -7,6 +7,8 @@ module Ramaze
   # smaller amounts of data.
 
   module CacheHelper
+
+    # Create the Cache.value_cache on inclusion if it doesn't exist yet.
     def self.included(klass)
       Cache.add(:value_cache) unless Cache::CACHES.has_key?(:value_cache)
     end

data/lib/ramaze/helper/identity.rb

@@ -7,27 +7,34 @@ require 'openid'
 module Ramaze
 
   openid_store_file = File.join(Dir.tmpdir, 'openid-store')
+
+  # Constant for storing meta-information persistent
   OpenIDStore = OpenID::FilesystemStore.new(openid_store_file)
 
   # This is called Identity to avoid collisions with the original openid.rb
+  # It provides a nice and simple way to provide and control access over the
+  # OpenID authentication model.
 
   module IdentityHelper
-    def self.included(klass)
-      klass.send(:helper, :flash)
-    end
 
+    # Simple form for use or overwriting.
+    # Has to provide the same functionality when overwritten or directly
+    # embedded into a page.
     def openid_login_form
       %{
-<form method="GET" action="#{R(self, :openid_begin)}">
+<form method="GET" action="#{Rs(:openid_begin)}">
   Identity URL: <input type="text" name="url" />
   <input type="submit" />
 </form>
       }
     end
 
+    # We land here from the openid_login_form and if we can find a matching
+    # OpenID server we redirect the user to it, the browser will return to
+    # openid_complete when the authentication is complete.
     def openid_begin
       url = request['url']
-      redirect_referrer if url.nil? or url.empty?
+      redirect_referrer if url.to_s.empty?
       session[:openid_entry] = request.referrer
 
       openid_request = openid_consumer.begin(url)
@@ -38,13 +45,20 @@ module Ramaze
         redirect_referrer
       when OpenID::SUCCESS
         root         = "http://#{request.http_host}/"
-        return_to    = root[0..-2] + R(self, :openid_complete)
+        return_to    = root[0..-2] + Rs(:openid_complete)
         redirect_url = openid_request.redirect_url(root, return_to)
 
         redirect(redirect_url)
       end
     end
 
+    # After having authenticated at the OpenID server browsers are redirected
+    # back here and on success we set the session[:openid_identity] and a little
+    # default flash message. Then we redirect to wherever session[:openid_entry]
+    # points us to, which was set on openid_begin to the referrer
+    #
+    # TODO:
+    #   - maybe using StackHelper, but this is a really minimal overlap?
     def openid_complete
       openid_response = openid_consumer.complete(request.params)
 
@@ -63,6 +77,7 @@ module Ramaze
 
     private
 
+    # Fetch/Create a OpenID::Consumer for current session.
     def openid_consumer
       OpenID::Consumer.new(session, Ramaze::OpenIDStore)
     end

data/lib/ramaze/helper/link.rb

@@ -4,7 +4,7 @@
 module Ramaze
   # LinkHelper is included into the Controller by default
   #
-  # Usage is pretty much shown in test/tc_helper and the rdocs below.
+  # Usage is shown in spec/ramaze/helper/link.rb and the rdocs below.
 
   module LinkHelper
 

data/lib/ramaze/helper/pager.rb

@@ -1,3 +1,5 @@
+module Ramaze
+
 # The BSD License
 #
 # Copyright (c) 2004-2007, George K. Moschovitis. (http://www.gmosx.com)
@@ -31,17 +33,53 @@
 # SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 #
 
-module Ramaze
-
 # 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
+# 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.
+#
+#
+# === Example
+#
+#   class MyController
+#     def index
+#       objs = (0..200).to_a
+#       @entries, @pager = paginate(objs, :limit => 20)
+#     end
+#   end
+#
+#
+#   <html>
+#     <head><title>Pager</title></head>
+#     <body>
+#       <?r if pager.navigation? ?>
+#         <div class="pager">#{@pager.navigation}</div>
+#       <?r end ?>
+#       <ul>
+#       <?r @entries.each do |entry| ?>
+#         <li>#{entry}</li>
+#       <?r end ?>
+#       </ul>
+#     </body>
+#   </html>
+#
+# === Styling
+#
+# The following classes can be used for styling with CSS (provided you put the
+# pager in a element with class 'pager' like shown above):
+#
+#   .pager {}
+#   .pager .first {}
+#   .pager .previous {}
+#   .pager .next {}
+#   .pager .last {}
+#   .pager ul {}
+#   .pager li {}
+#   .pager li.active {}
 
 class Pager
   include Ramaze::LinkHelper
@@ -56,19 +94,29 @@ class Pager
 
   # The current page.
 
-  attr_accessor :page
+  attr_reader :page
 
   # Items per page.
 
-  attr_accessor :limit
+  attr_reader :limit
 
   # The total number of pages.
 
-  attr_accessor :page_count
+  attr_reader :page_count
 
   # Total count of items.
 
-  attr_accessor :total_count
+  attr_reader :total_count
+
+  # Create a new Pager object.
+  #
+  # request:: Ramaze::Request object providing access to GET parameters
+  # limit:: how many elements go to one page
+  # total_count:: total element count
+  # key:: key used for getting the current page from GET paramaters
+  #
+  # Note:  You never have to create this class yourself, use the `paginate()`
+  # convenience method from the PagerHelper.
 
   def initialize(request, limit, total_count, key = trait[:key])
     raise 'limit should be > 0' unless limit > 0
@@ -80,11 +128,6 @@ class Pager
     @start_idx = (@page - 1) * limit
   end
 
-  def set_count(total_count)
-    @total_count = total_count
-    @page_count = (@total_count.to_f / @limit).ceil
-  end
-
   # Return the first page index.
 
   def first_page
@@ -121,12 +164,7 @@ class Pager
     [@page + 1, @page_count].min
   end
 
-  def link_first_page; target_uri(first_page); end
-  def link_last_page; target_uri(last_page); end
-  def link_prev_page; target_uri(prev_page); end
-  def link_next_page; target_uri(next_page); end
-
-  # Iterator
+  # Returns each element for the current page
 
   def each(&block)
     @page_items.each(&block)
@@ -135,60 +173,27 @@ class Pager
   # Iterator
   # Returns 1-based index.
 
-  def each_with_index
-    idx = @start_idx
-    for item in @page_items
-      yield(idx + 1, item)
-      idx += 1
-    end
+  def each_with_index(&block)
+    @page_items.each_with_index(&block)
   end
 
   # Is the pager empty, ie has one page only?
 
   def empty?
-    @page_count < 1
+    @page_count < 2
   end
 
-  # The items count.
+  # Returns true if a navigation is necessary (meaning there is more than one
+  # page)
 
-  def size
-    @total_count
-  end
-
-  # Returns the range of the current page.
-
-  def page_range
-    s = @idx
-    e = [@idx + @items_limit - 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)
+  def navigation?
+    !empty?
   end
 
-  # To be used with Og queries.
-
-  def limit
-    if @start_idx > 0
-      { :limit => @limit, :offset => @start_idx }
-    else
-      { :limit => @limit }
-    end
-  end
+  # Returns the amount of all elements in all pages.
 
-  def offset
-    @start_idx
+  def size
+    @total_count
   end
 
   # Override this method in your application if needed.
@@ -217,13 +222,9 @@ class Pager
 
     for i in nav_range()
       if i == @page
-        nav << %{
-          <li class="active">#{i}</li>
-        }
+        nav << %{<li class="active">#{i}</li>}
       else
-        nav << %{
-          <li><a href="#{target_uri(i)}">#{i}</a></li>
-        }
+        nav << %{<li><a href="#{target_uri(i)}">#{i}</a></li>}
       end
     end
 
@@ -232,8 +233,20 @@ class Pager
     return nav
   end
 
-  def navigation?
-    @page_count > 1
+  # To be used with Og queries.
+
+  def limit
+    if @start_idx > 0
+      { :limit => @limit, :offset => @start_idx }
+    else
+      { :limit => @limit }
+    end
+  end
+
+  # Returns the index of the first element to go into the current page
+
+  def offset
+    @start_idx
   end
 
 private
@@ -241,10 +254,57 @@ private
   # Generate the target URI.
 
   def target_uri(page)
-    params = Request.current.params.dup.update(@key => page)
+    params = @request.params.merge(@key => page)
     Rs(Action.current.method, params)
   end
 
+  # Generate link for the first page.
+
+  def link_first_page; target_uri(first_page); end
+
+  # Generate link for the last page.
+
+  def link_last_page; target_uri(last_page); end
+
+  # Generate link for the previous page.
+
+  def link_prev_page; target_uri(prev_page); end
+
+  # Generate link for the next page.
+
+  def link_next_page; target_uri(next_page); end
+
+
+  # Returns the range of the current page.
+
+  def page_range
+    s = @idx
+    e = [@idx + @items_limit - 1, all_total_count].min
+
+    return [s, e]
+  end
+
+  # Returns the range of
+  # 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
+
+  # generates total and page count of the pager.
+
+  def set_count(total_count)
+    @total_count = total_count
+    @page_count = (@total_count.to_f / @limit).ceil
+  end
+
 end
 
 # Pager related helper methods.
@@ -258,50 +318,48 @@ private
   #
   # === Example
   #
-  # entries, pager = paginate(Article, :where => 'title LIKE..', :limit => 10)
-  #
-  # or
-  #
   # items = [ 'item1', 'item2', ... ]
   # entries, pager = paginate(items, :limit => 10)
   #
-  # or
-  #
-  # entries, pager = paginate(article.comments, :limit => 10)
-  #
   # <ul>
   # <?r for entry in entries ?>
   #    <li>#{entry.to_link}</li>
   # <?r end ?>
   # </ul>
   # #{pager.navigation}
+  #
+  # === Og Example
+  #
+  # entries, pager = paginate(Article, :where => 'title LIKE..', :limit => 10)
+  #
+  # or
+  #
+  # entries, pager = paginate(article.comments, :limit => 10)
 
   def paginate(items, options = {})
-    limit = options.delete(:limit) || options[:limit] || Pager.trait[:limit]
+    limit = options.delete(:limit) || Pager.trait[:limit]
     pager_key = options.delete(:pager_key) || Pager.trait[:key]
 
     case items
-      when Array
-        pager = Pager.new(request, limit, items.size, pager_key)
-        items = items.slice(pager.offset, pager.limit[:limit])
-        return items, pager
+    when Array
+      pager = Pager.new(request, limit, items.size, pager_key)
+      items = items.slice(pager.offset, pager.limit[:limit])
+      return items, pager
     end
 
-    if defined?(Og)
-      case items
-      when Og::Collection
-        pager = Pager.new(request, limit, items.count, pager_key)
-        options.update(pager.limit)
-        items = items.reload(options)
-        return items, pager
-
-      when Og::Mixin
-        pager = Pager.new(request, limit, items.count(options), pager_key)
-        options.update(pager.limit)
-        items = items.all(options)
-        return items, pager
-      end
+    if defined?(Og) && items.is_a?(Og::Collection)
+      pager = Pager.new(request, limit, items.count, pager_key)
+      options.update(pager.limit)
+      items = items.reload(options)
+      return items, pager
+    elsif defined?(Og) && items.is_a?(Og::Mixin)
+      pager = Pager.new(request, limit, items.count(options), pager_key)
+      options.update(pager.limit)
+      items = items.all(options)
+      return items, pager
     end
+
+    raise "No suitable pagination method for #{items.inspect}"
   end
 
 end