archive_tree 1.0.0.rc

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Diogo Almeida
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,77 @@
+## Introduction
+
+ArchiveTree is a plugin for your Ruby on Rails application that makes it easy for you to generate structured trees of your records.
+
+Since it makes use of your model's _created_at_ column, ArchiveTree is ultimately compatible with most ActiveRecord Models out there.
+
+
+## Installation
+
+You can install ArchiveTree can be installed as a Ruby gem. This is specially made easy with Bundler. Just add this to your Gemfile
+
+<pre>
+gem 'archive_tree'
+</pre>
+
+It's also possible to install ArchiveTree as a Rails plugin
+
+<pre>
+rails plugin install git://github.com/GnomesLab/archive_tree.git
+</pre>
+
+
+## Examples
+
+Imagine that you have a blog application with Posts. Great!
+
+Now let's say that you wish to allow your users to sweep through your posts in a chronologically accurate tree view. Enters ArchiveTree!
+
+### API
+
+#### Default usage:
+
+<pre>
+Post.archive_tree #=> { 2010 => { 1 => [Post], 2 => [Post] },
+                        2011 => { 1 => [Post], 4 => [Post], 8 => [Post] } }
+</pre>
+
+#### Sweep all months of the current year:
+
+<pre>
+Post.archive_tree(:years => [Time.now.year]) #=> { 2010 => { 1 => [Post], 2 => [Post] } }
+</pre>
+
+#### Skip all months other than January (1):
+
+<pre>
+Post.archive_tree(:months => [1]) #=> { 2010 => { 1 => [Post] },
+                                      { 2011 => { 1 => [Post] } } }
+</pre>
+
+#### Only sweep January 2010:
+
+<pre>
+Post.archive_tree(:years_and_months => { 2010 => [1] }) #=> { 2010 => { 1 => [Post] } }
+</pre>
+
+### Views
+
+TODO: add view examples
+
+## Documentation
+
+This gem's documentation documentation is available at http://yardoc.org/docs/GnomesLab-archive_tree
+
+
+## License
+
+Copyright (c) 2010 Diogo Almeida, released under the MIT license. For more information regarding MIT license, please check our [MIT license file](http://github.com/GnomesLab/archive_tree/blob/master/MIT-LICENSE)
+
+
+## Feedback, issues and contributions
+
+If you have an issue with ArchiveTree please create a ticket in our [issue tracker](http://gnomeslab.lighthouseapp.com/projects/57307-archive_tree/overview).
+
+Feel free to fork this project at any time and submit your changes (along with their respective tests).
+
+Should you just wish to provide feedback or say hi, you can always contact us directly through diogo (dot) almeida (at) gnomeslab (dot) com

data/lib/archive_tree/action_view_extensions/draw_archive_tree.rb

@@ -0,0 +1,68 @@
+module ArchiveTree
+  module ActionViewExtensions
+
+    # Defines the helper methods that will be included in the ActionView::Base in order to return the html representation of the archive tree
+    module DrawArchiveTree
+
+      # In the presence of records for a given model it draws the archive tree. Otherwise, returns an empty string
+      #
+      # This method relies on the following private methods:
+      #   * +draw_years+
+      #   * +draw_months+
+      #
+      # Default behavior
+      #   * It will attempt to create a tree of your Post model
+      #   * Will use the post_published_at_path route
+      #   * Will display a toggle link
+      #   * Will use "[ + ]" as the link text
+      #
+      # Example using the default settings:
+      #   <%= draw_archive_tree %>
+      #
+      # Overriding the defaults example:
+      #   <%= draw_archive_tree :archive, :archive_published_at_path %>
+
+      def draw_archive_tree(model_sym = :post, route = :posts_path, toggle = true, toggle_text = '[ + ]')
+        model = model_sym.to_s.capitalize.constantize
+
+        raw model.count > 0 ? draw_years(model_sym, route, toggle, toggle_text) : ""
+      end # draw_archive_tree
+
+      private
+        def draw_years(model_sym, route, toggle, toggle_text) # :nodoc:
+          model = model_sym.to_s.capitalize.constantize
+          route = :posts_path unless self.respond_to? route
+
+          content_tag :ul do
+            ul_body = ""
+
+            model.archived_years.each_key do |year, count|
+              ul_body << content_tag(:li, :class => year == Time.now.year ? 'active' : 'inactive') do
+                (toggle ? link_to(toggle_text, "#", :class => "toggle") : '') + " " +
+                  link_to(year, self.send(route, year)) +
+                  draw_months(model_sym, route, year)
+              end
+            end
+
+            ul_body
+          end
+        end
+
+        def draw_months(model_sym, route, year) # :nodoc:
+          model = model_sym.to_s.capitalize.constantize
+
+          content_tag :ul do
+            ul_body = ""
+
+            model.archived_months(:year => year).each_pair do |month, count|
+              ul_body << content_tag(:li, link_to("#{Date::MONTHNAMES[month]} (#{count})",
+                                                  self.send(route, year, month < 10 ? "0#{month}" : month)))
+            end
+
+            ul_body
+          end
+        end
+    end # DrawArchiveTree
+
+  end # ActionViewExtensions
+end # ArchiveTree

data/lib/archive_tree/action_view_extensions.rb

@@ -0,0 +1,8 @@
+module ArchiveTree
+
+  module ActionViewExtensions
+    require 'archive_tree/action_view_extensions/draw_archive_tree'
+    ::ActionView::Base.send :include, DrawArchiveTree
+  end # ActionViewExtensions
+
+end # ArchiveTree

data/lib/archive_tree/core.rb

@@ -0,0 +1,153 @@
+module ArchiveTree
+
+  module Core #:nodoc:
+    
+    # Named scope that retrieves the records for a given year and month.
+    #
+    # Note: This scope can be chained, e.g. Post.archive_node.where('id > 100')
+    #
+    # Default behaviors
+    #   * :year  #=> defaults to the current year (e.g. 2010)
+    #   * :month #=> all
+    #
+    # Example using default values:
+    #   Post.archive_node
+    #
+    # Example overridding values:
+    #   Post.archive_node(:year => 2010, :month => 1)
+    def archive_node(options={})
+      options.reverse_merge! ({ :year => Time.now.year })
+
+      where("#{date_field} IS NOT NULL").
+      where("YEAR(#{date_field}) = ?", options[:year]).
+      where("MONTH(#{date_field}) = :month OR :month IS NULL", :month => options[:month])
+    end
+
+    # Constructs a single-level hash of years using the defined +date_field+ column.
+    #
+    # The returned hash is a key-value-pair of integers. The key represents the year (in integer) and the value
+    # represents the number of records for that year (also in integer).
+    #
+    # This method executes a SQL query of type COUNT, grouping the results by year.
+    #
+    # Note: the query makes use of the YEAR sql command, which might not be supported by all RDBMs.
+    #
+    # Exampe:
+    #   Post.years_hash #=> { 2009 => 8, 2010 => 30 }
+    def archived_years
+      years = {}
+      where("#{date_field} IS NOT NULL").
+      group("YEAR(#{date_field})").size.each { |year, count| years[year.to_i] = count }
+
+      years
+    end # archived_years
+
+    # For a given year, constructs a single-level hash of months using the defined +date_field+ column.
+    #
+    # The returned hash is a key-value-pair representing the number of records for a given month, within a given years.
+    # This hash can have string or integer keys, depending on the value of :month_names option,
+    # which can be passed in the options hash.
+    #
+    # Default behaviors
+    #   * By default the months are returned in their integer representation (eg.: 1 represents January)
+    #   * The current year is assumed to be the default scope of the query
+    #
+    # Options
+    #   * :year #=> Integer representing the year to sweep. Defaults to the current year.
+    #   * :month_names #=> Null, or absent will result in months represented as integer (default). Also accepts :long
+    # and :short, depending on the desired lenght length for the month name.
+    #
+    # *Considerations*
+    # Given the way the queries are currently constructed and executed this method suffers from poor performance.
+    #
+    # TODO: Optimize the queries.
+    def archived_months(options = {})
+      months  = {}
+      month_format = options.delete(:month_names) || :int
+
+      where("YEAR(#{date_field}) = #{options[:year] || Time.now.year}").
+      group("MONTH(#{date_field})").size.each do |month, c|
+        key = case month_format
+        when :long
+          Date::MONTHNAMES[month.to_i]
+        when :short
+          Date::ABBR_MONTHNAMES[month.to_i]
+        else
+          month.to_i
+        end
+
+        months[key] = c
+      end
+
+      months
+    end #archived_months
+
+    # Constructs an archive tree in the form of a nested Hash.
+    #
+    # Hash levels
+    #   1. Years  (integer)
+    #   2. Months (integer)
+    #   3. Your records (ActiveRecord::Relation)
+    #
+    # Default behaviors to take note:
+    #   * All records are sweeped by default based on their +date_field+ column
+    #   * Years without records are not returned
+    #   * Months without records are not returned
+    #   * The keys are integers, thus they will likely require conversion
+    #
+    # Options
+    #   * :years => Array of years to sweep
+    #   * :months => Array of months to sweep of each year
+    #   * :years_and_months => Hash of years, each containing an Array of months to sweep
+    #   * :month_names => Accepts one of two symbols :long and :short. Please note that this overrides the default value
+    #
+    # Examples context
+    #   Please note that for the sake of simplicity these examples assume that any given year has only one +Post+
+    #   record for any given month and will be represented in the following format:
+    #     { 2010 => {1 => [post]} }
+    #
+    # Default usage:
+    #   Post.archive_tree #=> { 2010 => { 1 => [Post], 2 => [Post] },
+    #                           2011 => { 1 => [Post], 4 => [Post], 8 => [Post] } }
+    #
+    # Sweep all months of the current year:
+    #   Post.archive_tree(:years => [Time.now.year]) #=> { 2010 => { 1 => [Post], 2 => [Post] } }
+    #
+    # Skip all months other than January (1):
+    #   Post.archive_tree(:months => [1]) #=> { 2010 => { 1 => [Post] },
+    #                                         { 2011 => { 1 => [Post] } } }
+    #
+    # Only sweep January 2010:
+    #   Post.archive_tree(:years_and_months => { 2010 => [1] }) #=> { 2010 => { 1 => [Post] } }
+    #
+    # *Considerations*
+    # This method has poor performance due to the 'linear' way in which the queries are being constructed and executed.
+    #
+    # TODO: Optimize the queries.
+    def archive_tree(options = {})
+      tree = {}
+      years = options[:years_and_months] ? options[:years_and_months].keys : nil || options[:years] ||
+        archived_years.keys || []
+
+      years.each do |year|
+        tree[year] = {}
+        months = archived_months(:year => year).keys
+
+        if options[:years_and_months]
+          months.reject! { |m| !options[:years_and_months][year].include?(m) }
+        elsif options[:months]
+          months.reject! { |m| !options[:months].include?(m) }
+        end
+
+        months.each do |month|
+          tree[year][month] = {}
+          tree[year][month] = archive_node year, month
+        end
+      end
+
+      tree
+    end # archive_tree
+
+  end # Core
+
+end # ArchiveTree

data/lib/archive_tree.rb

@@ -0,0 +1,37 @@
+# +ArchiveTree+ is responsible for the creation of hashes that cronologically represent your model
+# based on a provided field
+#
+# If you wish to take advantage of its functionalities, please use the acts_as_archive method in your ActiveRecord Model.
+#
+# Examples
+#   class Post < ActiveRecord::Base
+#     acts_as_archive # uses +created_at+ by default
+#   end
+#
+#   class Post < ActiveRecord::Base
+#     acts_as_archive :published_at # uses +published_at+ instead of +created_at+ (default)
+#   end
+#
+#   Post.archive_tree(:years_and_months => { 2010 => [1] }) #=> { 2010 => { 1 => [Post] } }
+#
+# TODO: This module should undergo a query optimization. Furthermore, an ORM abstraction.
+module ArchiveTree
+
+  require 'archive_tree/action_view_extensions'
+  autoload :Core, 'archive_tree/core'
+
+  def acts_as_archive(date_field = :created_at)
+    raise ::ArgumentError, "undefined parameter #{date_field.to_s}" unless column = columns_hash[date_field.to_s]
+    raise ::ArgumentError, "invalid parameter #{date_field.to_s}"   unless column.type == :datetime
+
+    self.date_field = date_field # Stores the date column
+
+    extend Core
+  end
+
+  private
+    attr_accessor :date_field
+
+end # ArchiveTree
+
+ActiveRecord::Base.send :extend, ArchiveTree if defined?(ActiveRecord::Base)

metadata

@@ -0,0 +1,114 @@
+--- !ruby/object:Gem::Specification 
+name: archive_tree
+version: !ruby/object:Gem::Version 
+  prerelease: true
+  segments: 
+  - 1
+  - 0
+  - 0
+  - rc
+  version: 1.0.0.rc
+platform: ruby
+authors: 
+- Diogo Almeida
+- Miguel Teixeira
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-10-30 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activerecord
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 3
+        - 0
+        - 0
+        version: 3.0.0
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: database_cleaner
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id003
+description: ArchiveTree is a Ruby Gem that makes it easy for you to create beautiful chronological archive trees of your models. For instance, you can create a tree for your blog posts.
+email: 
+- mail@gnomeslab.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/archive_tree/action_view_extensions/draw_archive_tree.rb
+- lib/archive_tree/action_view_extensions.rb
+- lib/archive_tree/core.rb
+- lib/archive_tree.rb
+- MIT-LICENSE
+- README.md
+has_rdoc: true
+homepage: http://github.com/GnomesLab/archive_tree/
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 1
+      - 3
+      - 7
+      version: 1.3.7
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Creates chronological trees of your models based on their created_at column value.
+test_files: []
+