categoryz3 0.1

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2012 YOURNAME
+
+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.rdoc

@@ -0,0 +1,112 @@
+= Categoryz3
+{<img src="https://secure.travis-ci.org/tscolari/categoryz3.png" />}[http://travis-ci.org/tscolari/categoryz3]
+{<img src="https://gemnasium.com/tscolari/categoryz3.png" />}[https://gemnasium.com/tscolari/categoryz3]
+{<img src="https://codeclimate.com/badge.png" />}[https://codeclimate.com/github/tscolari/categoryz3]
+
+Simple categorization to ActiveRecord models.
+
+Works like a simple tagging system, but instead of tags it has categories, and categories may have an ilimited level of subcategories.
+
+Using an auxiliary table, it's easy and fast to fetch items from any category, including all level of subcategories it may have.
+
+== Motivation
+
+  genres_category      = Categoryz3::Category.create(name: 'genres')
+  horror_category      = Categoryz3::Category.create(name: 'horror', parent: genres_category)
+  cult_horror_category = Categoryz3::Category.create(name: 'horror', parent: horror_category)
+  action_category      = Categoryz3::Category.create(name: 'horror', parent: genres_category)
+
+  horror_movie = Movie.find(1)
+  horror_movie.category = cult_horror_category
+  horror_movie.categories
+  #=> [cult_horror_category]
+
+  action_movie = Movie.find(2)
+  action_movie.category = action_category
+
+  Movie.inside_category(genres_category).all
+  #=> [horror_movie, action_movie]
+  Movie.inside_category(horror_category).all
+  #=> [horror_movie]
+  Movie.inside_category(cult_horror_category).all
+  #=> [horror_movie]
+
+  horror_category.path
+  #=> [movie_category, horror_category]
+
+== Installation
+
+Insert the gem in your Gemfile:
+
+  gem 'categoryz3'
+
+Generate and run the migrations:
+
+  rails g categoryz3:migrations
+  rake db:migrate
+
+Include the categorizable module in the models you want to categorize:
+
+  class Article < ActiveRecord::Base
+    include Categoryz3::Categorizable
+  end
+
+== Usage
+
+=== Listing categories from an object
+
+You can use the method `categories` to list all categories from a model:
+
+  model.categories
+  #=> [category1, category2]
+
+You can also use the `categories_list`, this will return the categories ids:
+
+  model.categories_list
+  #=> "1, 2"
+
+=== Adding categories to an object
+
+There are 2 ways for adding categories to an object:
+
+  model.category = category
+  model.category = [category1, category2, category3]
+  # alias_method :categories=, :category=
+
+Replaces the object categories for the given ones.
+
+  model.categories_list = "1, 2, 3"
+
+Replaces the object categories for the ones with ids 1, 2 and 3.
+
+=== Removing categories from an object
+
+To remove a category from the model, you can use the `remove_category` method:
+
+  model.remove_category category
+  model.remove_categories category1, category2
+
+=== Category Path
+
+Lists all the categories in the path, from the root one, to the category:
+
+  category.path
+  #=> [root_category, some_subcategory, another_subcategory, category]
+
+=== Categorizable Scopes
+
+==== inside_category
+
+Lists all objects that belongs to the category or any subcategory of it
+
+  Article.inside_category(category)
+
+==== having_category
+
+Lists all objects that belongs to the category. (No subcategory objects).
+
+  Article.having_category(category)
+
+= License
+
+This project rocks and uses MIT-LICENSE.

data/Rakefile

@@ -0,0 +1,27 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Categoryz3'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+
+Bundler::GemHelper.install_tasks
+

data/app/models/categoryz3/category.rb

@@ -0,0 +1,30 @@
+module Categoryz3
+  class Category < ActiveRecord::Base
+    belongs_to :parent     , class_name: 'Categoryz3::Category'  , inverse_of: :children
+    has_many :children     , class_name: 'Categoryz3::Category'  , foreign_key: :parent_id , inverse_of: :parent , dependent: :destroy
+    has_many :direct_items , class_name: 'Categoryz3::Item'      , inverse_of: :category   , dependent: :destroy
+    has_many :child_items  , class_name: 'Categoryz3::ChildItem' , inverse_of: :category   , dependent: :destroy
+    validates :name        , presence: true
+
+    scope :parent_categories, -> { where(parent_id: nil) }
+    attr_accessible :name, :parent
+
+    # Public: Returns the full categories path from the root category until this category
+    #
+    # Example:
+    #
+    #   subcategory3.path
+    #   #=> [category, subcategory1, subcategory2, subcategory3]
+    #
+    def path
+      return @path_array if @path_array
+      parent_category = self
+      @path_array = [parent_category]
+      while (parent_category = parent_category.parent) != nil do
+        @path_array.insert(0, parent_category) 
+      end
+      @path_array
+    end
+
+  end
+end

data/app/models/categoryz3/child_item.rb

@@ -0,0 +1,12 @@
+module Categoryz3
+  class ChildItem < ActiveRecord::Base
+    belongs_to :category, inverse_of: :child_items
+    belongs_to :master_item, class_name: 'Categoryz3::Item', inverse_of: :child_items
+    belongs_to :categorizable, polymorphic: true
+
+    validates :category, :master_item, :categorizable, presence: true
+    validates :category_id, uniqueness: { scope: [:categorizable_type, :categorizable_id] }
+    validates_with Categoryz3::Validators::ChildItemCategoryValidator
+    attr_accessible :master_item, :categorizable
+  end
+end

data/app/models/categoryz3/item.rb

@@ -0,0 +1,31 @@
+module Categoryz3
+  class Item < ActiveRecord::Base
+    belongs_to :category, inverse_of: :direct_items
+    belongs_to :categorizable, polymorphic: true
+    has_many   :child_items, foreign_key: 'master_item_id', inverse_of: :master_item, dependent: :destroy
+
+    validates :category, :categorizable, presence: true
+    validates :category_id, uniqueness: { scope: [:categorizable_type, :categorizable_id] }
+
+    after_create :create_child_items
+    attr_accessible :categorizable
+
+    private
+
+    # Private: Creates a child item for the category
+    #
+    def create_child_item_for_category(category)
+      category.child_items.create(categorizable: self.categorizable, master_item: self)
+    end
+
+    # Private: Create a child_item for each subcategory the category from this item have
+    # Also creates a child_item for this category
+    #
+    def create_child_items
+      category.path.each do |category|
+        create_child_item_for_category category
+      end
+    end
+
+  end
+end

data/config/routes.rb

@@ -0,0 +1,2 @@
+Categoryz3::Engine.routes.draw do
+end

data/db/migrate/20121003060539_create_categoryz3_categories.rb

@@ -0,0 +1,14 @@
+class CreateCategoryz3Categories < ActiveRecord::Migration
+  def change
+    create_table :categoryz3_categories do |t|
+      t.string :name
+      t.references :parent
+      t.integer :items_count       , default: 0
+      t.integer :child_items_count , default: 0
+      t.integer :childrens_count   , default: 0
+      t.timestamps
+    end
+    add_index :categoryz3_categories, :parent_id
+    add_index :categoryz3_categories, :name
+  end
+end

data/db/migrate/20121003060933_create_categoryz3_items.rb

@@ -0,0 +1,12 @@
+class CreateCategoryz3Items < ActiveRecord::Migration
+  def change
+    create_table :categoryz3_items do |t|
+      t.references :category, null: false
+      t.references :categorizable, polymorphic: true, null: false
+      t.timestamps
+    end
+    add_index :categoryz3_items, [:category_id, :categorizable_type, :categorizable_id], unique: true, name: 'items_unq_idx'
+    add_index :categoryz3_items, [:category_id, :created_at]
+    add_index :categoryz3_items, [:categorizable_type, :categorizable_id], name: 'items_categorizable_idx'
+  end
+end

data/db/migrate/20121003061056_create_categoryz3_child_items.rb

@@ -0,0 +1,14 @@
+class CreateCategoryz3ChildItems < ActiveRecord::Migration
+  def change
+    create_table :categoryz3_child_items do |t|
+      t.references :category, null: false
+      t.references :categorizable, polymorphic: true, null: false
+      t.references :master_item, null: false
+      t.timestamps
+    end
+    add_index :categoryz3_child_items, [:category_id, :created_at]
+    add_index :categoryz3_child_items, [:category_id, :categorizable_type, :categorizable_id], unique: true, name: 'child_items_unq_idx'
+    add_index :categoryz3_child_items, [:categorizable_type, :categorizable_id], name: 'child_items_categorizable_idx'
+    add_index :categoryz3_child_items, [:master_item_id]
+  end
+end

data/lib/categoryz3/categorizable.rb

@@ -0,0 +1,79 @@
+module Categoryz3
+  # Adds the categorizable behavior to models
+  #
+  # This will give the model 2 scopes:
+  #
+  #   * inside_category(category) : Filter objects that belongs to the category or any of it's subcategories
+  #   * having_category(category) : Filter objects that belongs only to the category
+  #
+  # And 2 new relations:
+  #
+  #   * direct_category_items : This maps the model to the categories it is directly linked
+  #   * child_category_items : This is an auxiliary relation to fast map the objet to any subcategory
+  #
+  module Categorizable
+    extend ActiveSupport::Concern
+    included do
+      has_many :direct_category_items , class_name: 'Categoryz3::Item'      , as: :categorizable
+      has_many :child_category_items  , class_name: 'Categoryz3::ChildItem' , as: :categorizable
+      scope :inside_category , ->(category) { joins(:child_category_items).where('categoryz3_child_items.category_id = ?' , category.id) }
+      scope :having_category , ->(category) { joins(:direct_category_items).where('categoryz3_items.category_id = ?'      , category.id) }
+    end
+
+    # Public: List all object categories
+    # Categories are retrieved from direct_category_items association, no subcategories included
+    #
+    def categories
+      return @categories if @categories
+      category_ids = direct_category_items.all.map { |category| category.id }
+      @categories = Categoryz3::Category.where(id: category_ids)
+    end
+
+    # Public: Adds a category, or categories, to the model
+    #
+    # Examples:
+    #
+    #   categorizable_object.category = dummy_category
+    #   categorizable_object.categories = [dummy_category1, dummy_category2]
+    #
+    def category=(categories)
+      self.direct_category_items.destroy_all
+      [categories].flatten.each do |category|
+        category.direct_items.create(categorizable: self) if category
+      end
+      @categories = nil
+    end
+    alias_method :categories=, :category=
+
+    # Public: Removes a category, or categories, from the model
+    #
+    # Examples:
+    #
+    #   categorizable_object.remove_category dummy_category
+    #   categorizable_object.remove_categories dummy_category1, dummy_category2
+    #
+    def remove_category(*categories)
+      categories.each do |category|
+        direct_category_items.where(category_id: category).destroy_all
+      end
+      @categories = nil
+    end
+    alias_method :remove_categories, :remove_category
+
+    # Public: Returns the id list of the categories linked to the model
+    #
+    def categories_list
+      categories.map(&:id).join(", ")
+    end
+
+    # Public: Accepts an array of category ids as parameter and adds all
+    # of them to the model
+    #
+    def categories_list=(ids)
+      self.categories = ids.split(",").map do |id|
+        Category.where(id: id).first
+      end
+    end
+
+  end
+end

data/lib/categoryz3/engine.rb

@@ -0,0 +1,5 @@
+module Categoryz3
+  class Engine < ::Rails::Engine
+    isolate_namespace Categoryz3
+  end
+end

data/lib/categoryz3/validators/child_item_category_validator.rb

@@ -0,0 +1,11 @@
+module Categoryz3
+  module Validators
+    class ChildItemCategoryValidator < ActiveModel::Validator
+      def validate(record)
+        unless record.master_item.category.path.map{ |category| category.id }.include?(record.category_id)
+          record.errors[:category] << "Must match with master_item.category"
+        end
+      end
+    end
+  end
+end

data/lib/categoryz3/version.rb

@@ -0,0 +1,3 @@
+module Categoryz3
+  VERSION = "0.1"
+end

data/lib/categoryz3.rb

@@ -0,0 +1,8 @@
+require "categoryz3/engine"
+require "categoryz3/categorizable"
+require "categoryz3/validators/child_item_category_validator"
+
+module Categoryz3
+end
+
+

data/lib/generators/categoryz3/migrations/USAGE

@@ -0,0 +1,8 @@
+Description:
+    Explain the generator
+
+Example:
+    rails generate migrations Thing
+
+    This will create:
+        what/will/it/create

data/lib/generators/categoryz3/migrations/migrations_generator.rb

@@ -0,0 +1,22 @@
+require 'rails/generators'
+require 'rails/generators/migration'
+
+class Categoryz3::MigrationsGenerator < Rails::Generators::Base
+  include Rails::Generators::Migration
+  source_root File.expand_path('../../../../../db/migrate', __FILE__)
+
+  def copy_migrations
+    migration_template "20121003060539_create_categoryz3_categories.rb", "db/migrate/create_categoryz3_categories.rb"
+    migration_template "20121003060933_create_categoryz3_items.rb", "db/migrate/create_categoryz3_items.rb"
+    migration_template "20121003061056_create_categoryz3_child_items.rb", "db/migrate/create_categoryz3_child_items.rb"
+  end
+
+  def self.next_migration_number( dirname )
+    next_migration_number = current_migration_number(dirname) + 1
+    if ActiveRecord::Base.timestamped_migrations
+      [Time.now.utc.strftime("%Y%m%d%H%M%S%6N"), "%.20d" % next_migration_number].max
+    else
+      "%.3d" % next_migration_number
+    end
+  end
+end

data/lib/tasks/categoryz3_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :categoryz3 do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,150 @@
+--- !ruby/object:Gem::Specification
+name: categoryz3
+version: !ruby/object:Gem::Version
+  prerelease:
+  version: '0.1'
+platform: ruby
+authors:
+- Tiago Scolari
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2012-10-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.2.8
+    none: false
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.2.8
+    none: false
+  prerelease: false
+  type: :runtime
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+    none: false
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+    none: false
+  prerelease: false
+  type: :development
+- !ruby/object:Gem::Dependency
+  name: database_cleaner
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+    none: false
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+    none: false
+  prerelease: false
+  type: :development
+- !ruby/object:Gem::Dependency
+  name: factory_girl_rails
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+    none: false
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+    none: false
+  prerelease: false
+  type: :development
+- !ruby/object:Gem::Dependency
+  name: ffaker
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+    none: false
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+    none: false
+  prerelease: false
+  type: :development
+description: Works like a simple tagging system, but instead of tags it has categories, and categories may have an ilimited level of subcategories.
+email:
+- tscolari@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- app/models/categoryz3/category.rb
+- app/models/categoryz3/child_item.rb
+- app/models/categoryz3/item.rb
+- config/routes.rb
+- db/migrate/20121003060539_create_categoryz3_categories.rb
+- db/migrate/20121003060933_create_categoryz3_items.rb
+- db/migrate/20121003061056_create_categoryz3_child_items.rb
+- lib/categoryz3.rb
+- lib/categoryz3/categorizable.rb
+- lib/categoryz3/engine.rb
+- lib/categoryz3/version.rb
+- lib/categoryz3/validators/child_item_category_validator.rb
+- lib/generators/categoryz3/migrations/migrations_generator.rb
+- lib/generators/categoryz3/migrations/USAGE
+- lib/tasks/categoryz3_tasks.rake
+- MIT-LICENSE
+- Rakefile
+- README.rdoc
+homepage: https://github.com/tscolari/categoryz3
+licenses: []
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      segments:
+      - 0
+      hash: 2
+      version: '0'
+  none: false
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      segments:
+      - 0
+      hash: 2
+      version: '0'
+  none: false
+requirements: []
+rubyforge_project:
+rubygems_version: 1.8.24
+signing_key:
+specification_version: 3
+summary: Simple categorization to ActiveRecord models.
+test_files: []
+...