glebtv_mongoid_taggable_with_context 1.1.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9e5d9045dcccb4e3ecbd7967e81ef954ec970a8d2e35e48f201b512f79a3a117
+  data.tar.gz: 596291220d50a02651f0a12ba148d89536c7e2cd951b90a7005fa6653d402253
+SHA512:
+  metadata.gz: 44048b42dcb273e5ba92dc2c4cca427670e1e18c90b0a335bbc16ada5129dd6a815fe2e8d4d58425242ee943f0164781eec65ff217638009dc42e04bbd03c8e8
+  data.tar.gz: a675d4701c60ad10d09947bebbfe99bacbecb9dde36c995406fdf7f2d8ca188cd384b16ad887d6db72735f42afa79c935a8030aeff58ec179ea7f8830c90dd4b

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/.gitignore

@@ -0,0 +1,16 @@
+coverage
+rdoc
+doc
+.yardoc
+.bundle
+Gemfile.lock
+pkg
+.DS_Store
+*.tmproj
+tmtags
+*~
+\#*
+.\#*
+*.swp
+.idea
+.idea/*

data/.travis.yml

@@ -0,0 +1,7 @@
+language: ruby
+bundler_args: --without development
+rvm:
+  - 1.9.3
+  - 2.0.0
+services:
+  - mongodb

data/Gemfile

@@ -0,0 +1,12 @@
+source 'http://rubygems.org'
+
+gem 'mongoid', '>= 3.0.0'
+
+group :test, :development do
+  gem 'rake'
+  gem 'rspec'
+  gem 'yard'
+  gem 'bundler', '>= 1.0.0'
+  gem 'jeweler'
+end
+

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Aaron Qian
+
+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,223 @@
+mongoid_taggable_with_context
+=============================
+
+[![Build Status](https://secure.travis-ci.org/lgs/mongoid_taggable_with_context.png?branch=master)](http://travis-ci.org/lgs/mongoid_taggable_with_context) [![Dependency Status](https://gemnasium.com/lgs/mongoid_taggable_with_context.png?travis)](https://gemnasium.com/lgs/mongoid_taggable_with_context)
+[![Code Climate](https://codeclimate.com/github/lgs/mongoid_taggable_with_context.png)](https://codeclimate.com/github/lgs/mongoid_taggable_with_context)
+
+A tagging lib for Mongoid that allows for custom tagging along dynamic contexts. This gem was originally based on [mongoid_taggable](https://github.com/ches/mongoid_taggable) by Wilker Lúcio and Ches Martin. It has evolved substantially since that point, but all credit goes to them for the initial tagging functionality.
+
+For instance, in a social network, a user might have tags that are called skills, interests, sports, and more. There is no real way to differentiate between tags and so an implementation of this type is not possible with `mongoid_taggable`.
+
+Another example, aggregation such as counting tag occurrences was achieved by map-reduce with `mongoid_taggable`. It was ok for small amount of tags, but when the amount of tags and documents grow, the original `mongoid_taggable` won't be able to scale to real-time statistics demand.
+
+Enter `mongoid_taggable_with_context`. Rather than tying functionality to a specific keyword (namely "tags"), `mongoid_taggable_with_context` allows you to specify an arbitrary number of *tag contexts* that can be used locally or in combination in the same way `mongoid_taggable` was used.
+
+`mongoid_taggable_with_context` also provides flexibility on aggregation strategy. In addition to the map-reduce strategy, this gem also comes with real-time strategy. By using real-time strategy, your document can quickly adjusts the aggregation collection whenever tags are inserted or removed with $inc operator. So performance won't be impacted as the number of tags and documents grow.
+
+Installation
+------------
+
+You can simply install from rubygems:
+
+```
+gem install mongoid_taggable_with_context
+```
+
+or in Gemfile:
+
+```ruby
+gem 'mongoid_taggable_with_context'
+```
+
+
+The "taggable" Macro Function
+-----------------------------
+
+Use the `taggable` macro function in your model to
+declare a tags field. Specify `field name`
+for tags, and `options` for tagging behavior.
+
+Example:
+
+   ```ruby
+   class Article
+     include Mongoid::Document
+     include Mongoid::TaggableWithContext
+     taggable :keywords, separator: ' ', default: ['foobar']
+   end
+   ```
+
+* `@param [ Symbol ] field`
+
+   (Optional) The name of the field for tags. Defaults to "tags"
+
+
+* `@param [ Hash ] options`
+
+   (Optional) Options for taggable behavior.
+
+
+    * `@option [ String ] :separator`
+
+        The delimiter used when converting the tags to and from String format. Defaults to " "
+
+
+    * `@option [ :Symbol ] :group_by_field`
+
+        The Mongoid field to group by when RealTimeGroupBy aggregation is used.
+
+
+    * `@option [ <various> ] :default, :as, :localize, etc.`
+
+        Options for Mongoid #field method will be automatically passed
+        to the underlying Array field (with the exception of `:type`,
+        which is coerced to `Array`).
+
+
+Example Usage
+-------------
+
+To make a document taggable you need to include Mongoid::TaggableOnContext
+into your document and call the *taggable* macro with optional arguments:
+
+```ruby
+class Post
+  include Mongoid::Document
+  include Mongoid::TaggableWithContext
+
+  field :title
+  field :content
+
+  # default context is 'tags'.
+  # This creates #tags, #tags=, #tag_string instance methods
+  # separator is " " by default
+  # #tags method returns an array of tags
+  # #tags= methods accepts an array of tags or a separated string
+  # #tag_string method returns a separated string
+  taggable
+
+  # tagging for 'skills' context.
+  # This creates #skills, #skills=, #skills_string instance methods
+  # changing tag separator to "," (Default is " ")
+  taggable :skills, separator: ','
+
+  # aliased context tagging.
+  # This creates #interests, #interests=, #interests_string instance methods
+  # The tags will be stored in a database field called 'ints'
+  taggable :ints, as: :interests
+end
+```
+
+Then in your form, for example:
+
+```rhtml
+<% form_for @post do |f| %>
+  <p>
+    <%= f.label :title %><br />
+    <%= f.text_field :title %>
+  </p>
+  <p>
+    <%= f.label :content %><br />
+    <%= f.text_area :content %>
+  </p>
+  <p>
+    <%= f.label :tags %><br />
+    <%= text_field_tag 'post[tags]' %>
+  </p>
+  <p>
+    <%= f.label :interests %><br />
+    <%= text_field_tag 'post[interests]' %>
+  </p>
+  <p>
+    <%= f.label :skills %><br />
+    <%= text_field_tag 'post[skills]' %>
+  </p>
+  <p>
+    <button type="submit">Send</button>
+  </p>
+<% end %>
+```
+
+
+Aggregation Strategies
+----------------------
+
+By including an aggregation strategy in your document, tag aggregations will be automatically available to you.
+This lib presents the following aggregation strategies:
+
+* MapReduce
+* RealTime
+* RealTimeGroupBy
+
+The following document will automatically aggregate counts on all tag contexts.
+
+```ruby
+class Post
+  include Mongoid::Document
+  include Mongoid::TaggableWithContext
+
+  # automatically adds real time aggregations to all tag contexts
+  include Mongoid::TaggableWithContext::AggregationStrategy::RealTime
+
+  # alternatively for map-reduce
+  # include Mongoid::TaggableWithContext::AggregationStrategy::MapReduce
+
+  field :title
+  field :content
+
+  taggable
+  taggable :skills, separator: ','
+  taggable :ints, as: interests
+end
+```
+
+When you include an aggregation strategy, your document also gains a few extra methods to retrieve aggregation data.
+In the case of previous example the following methods are included:
+
+```ruby
+Post.tags
+Post.tags_with_weight
+Post.interests
+Post.interests_with_weight
+Post.skills
+Post.skills_with_weight
+```
+
+Here is how to use these methods in more detail:
+
+```ruby
+Post.create!(tags: "food,ant,bee")
+Post.create!(tags: "juice,food,bee,zip")
+Post.create!(tags: "honey,strip,food")
+
+Post.tags # will retrieve ["ant", "bee", "food", "honey", "juice", "strip", "zip"]
+Post.tags_with_weight # will retrieve:
+# [
+#   ['ant', 1],
+#   ['bee', 2],
+#   ['food', 3],
+#   ['honey', 1],
+#   ['juice', 1],
+#   ['strip', 1],
+#   ['zip', 1]
+# ]
+```
+
+
+Contributing to mongoid_taggable_with_context
+-----------------------------------------------
+
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+
+Copyright
+---------
+
+Copyright (c) 2011 Aaron Qian. See LICENSE.txt for
+further details.

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/glebtv_mongoid_taggable_with_context.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "mongoid/taggable_with_context/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "glebtv_mongoid_taggable_with_context"
+  spec.version = Mongoid::TaggableWithContext::VERSION.dup
+
+  spec.homepage = "http://github.com/glebtv/mongoid_taggable_with_context"
+  spec.licenses = ["MIT"]
+  spec.summary = "Mongoid taggable behaviour"
+  spec.authors = ["Aaron Qian", "Luca G. Soave", "John Shields", "Wilker Lucio", "Ches Martin", "glebtv"]
+
+  spec.description = "Add multiple tag fields on Mongoid documents with aggregation capability."
+
+  spec.files         = `git ls-files`.split($/).reject {|f| f.start_with?('mongoid') || f.start_with?('activerecord') }
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_runtime_dependency(%q<mongoid>, "~> 7.0.0")
+
+  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency(%q<rspec>)
+end
+

data/init.rb

@@ -0,0 +1 @@
+require 'mongoid_taggable_with_context'

data/lib/mongoid/taggable_with_context.rb

@@ -0,0 +1,321 @@
+module Mongoid::TaggableWithContext
+  extend ActiveSupport::Concern
+
+  class AggregationStrategyMissing < Exception; end
+  class InvalidTagsFormat < Exception; end
+
+  DEFAULT_FIELD = :tags
+  DEFAULT_SEPARATOR = ' '
+
+  included do
+    class_attribute :taggable_with_context_options
+    self.taggable_with_context_options = {}
+  end
+
+  def tag_string_for(context)
+    self.read_attribute(context).join(self.class.get_tag_separator_for(context)) rescue ""
+  end
+
+  def set_tag_string_for(context, value)
+    self.write_attribute(context, self.class.format_tags_for(context, value))
+  end
+
+  module ClassMethods
+    # Macro to declare a document class as taggable, specify field name
+    # for tags, and set options for tagging behavior.
+    #
+    # @example Define a taggable document.
+    #
+    #   class Article
+    #     include Mongoid::Document
+    #     include Mongoid::TaggableWithContext
+    #     taggable :keywords, separator: ' ', default: ['foobar']
+    #   end
+    #
+    # @param [ Symbol ] field The name of the field for tags. Defaults to :tags if not specified.
+    # @param [ Hash ] options Options for taggable behavior.
+    #
+    # @option options [ String ] :separator
+    #   The delimiter used when converting the tags to and from String format. Defaults to ' '
+    # @option options [ :Symbol ] :group_by_field
+    #   The Mongoid field to group by when RealTimeGroupBy aggregation is used.
+    # @option options [ <various> ] :default, :as, :localize, etc.
+    #   Options for Mongoid #field method will be automatically passed
+    #   to the underlying Array field
+    def taggable(*args)
+      # init variables
+      options = args.extract_options!
+      field = args.present? ? args.shift.to_sym : DEFAULT_FIELD
+      added = add_taggable(field, options)
+      # TODO: test if this is needed
+      # descendants.each do |subclass|
+      #   subclass.add_taggable(field, options)
+      # end
+      added
+    end
+
+    def tag_contexts
+      self.taggable_with_context_options.keys
+    end
+
+    def tag_database_fields
+      self.taggable_with_context_options.keys.map do |context|
+        tag_options_for(context)[:db_field]
+      end
+    end
+
+    def tag_options_for(context)
+      self.taggable_with_context_options[context]
+    end
+
+    def tags_for(context, group_by=nil, conditions={})
+      raise AggregationStrategyMissing
+    end
+
+    def tags_with_weight_for(context, group_by=nil, conditions={})
+      raise AggregationStrategyMissing
+    end
+
+    def get_tag_separator_for(context)
+      self.taggable_with_context_options[context][:separator]
+    end
+
+    def get_tag_group_by_field_for(context)
+      self.taggable_with_context_options[context][:group_by_field]
+    end
+
+    # Find documents tagged with all tags passed as a parameter, given
+    # as an Array or a String using the configured separator.
+    #
+    # @example Find matching all tags in an Array.
+    #   Article.tagged_with(['ruby', 'mongodb'])
+    # @example Find matching all tags in a String.
+    #   Article.tagged_with('ruby, mongodb')
+    #
+    # @param [ String ] :field The field name of the tag.
+    # @param [ Array<String, Symbol>, String ] :tags Tags to match.
+    # @return [ Criteria ] A new criteria.
+    def tagged_with(context, tags)
+      tags = format_tags_for(context, tags)
+      field = tag_options_for(context)[:field]
+      all_in(field => tags)
+    end
+
+    # Helper method to convert a a tag input value of unknown type
+    # to a formatted array.
+    def format_tags_for(context, value)
+      return nil if value.nil?
+      # 0) Tags must be an array or a string
+      raise InvalidTagsFormat unless value.is_a?(Array) || value.is_a?(String)
+      # 1) convert String to Array
+      value = value.split(get_tag_separator_for(context)) if value.is_a? String
+      # 2) remove all nil values
+      # 3) strip all white spaces. Could leave blank strings (e.g. foo, , bar, baz)
+      # 4) remove all blank strings
+      # 5) remove duplicate
+      value.compact.map(&:strip).reject(&:blank?).uniq
+    end
+
+    protected
+
+    # Adds a taggable context to the list of contexts, and creates the underlying
+    # Mongoid field and alias methods for the context.
+    #
+    # @param [ Symbol ] field The name of the Mongoid database field to store the taggable.
+    # @param [ Hash ] options The taggable options.
+    #
+    # @since 1.1.1
+    def add_taggable(field, options)
+      validate_taggable_options(options)
+
+      # db_field: the field name stored in the database
+      options[:db_field] = field.to_sym
+      # field: the field name used to identify the tags. :field will
+      # be identical to :db_field unless the :as option is specified
+      options[:field] = options[:as] || field
+      context = options[:field]
+      options.reverse_merge!(
+          separator: DEFAULT_SEPARATOR
+      )
+
+      # register / update settings
+      self.taggable_with_context_options[options[:field]] = options
+
+      create_taggable_mongoid_field(field, options)
+      create_taggable_mongoid_index(context)
+      define_taggable_accessors(context)
+    end
+
+    # Validates the taggable options and raises errors if invalid options are detected.
+    #
+    # @param [ Hash ] options The taggable options.
+    #
+    # @since 1.1.1
+    def validate_taggable_options(options)
+      if options[:field]
+        raise <<-ERR
+          taggable :field option has been removed as of version 1.1.1. Please use the
+          syntax "taggable <database_name>, as: <tag_name>"
+        ERR
+      end
+      if options[:string_method]
+        raise <<-ERR
+          taggable :string_method option has been removed as of version 1.1.1. Please
+          define an alias to "<tags>_string" in your Model
+        ERR
+      end
+    end
+
+    # Creates the underlying Mongoid field for the tag context.
+    #
+    # @param [ Symbol ] name The name of the Mongoid field.
+    # @param [ Hash ] options Options for the Mongoid field.
+    #
+    # @since 1.1.1
+    def create_taggable_mongoid_field(name, options)
+      field name, mongoid_field_options(options)
+    end
+
+    # Prepares valid Mongoid option keys from the taggable options. Slices
+    # the taggable options to include only valid options for the Mongoid #field
+    # method, and coerces :type to Array.
+    #
+    # @param [ Hash ] :options The taggable options hash.
+    # @return [ Hash ] A options hash for the Mongoid #field method.
+    #
+    # @since 1.1.1
+    def mongoid_field_options(options = {})
+      options.slice(*::Mongoid::Fields::Validators::Macro::OPTIONS).merge!(type: Array)
+    end
+
+    # Creates an index for the underlying Mongoid field.
+    #
+    # @param [ Symbol ] name The name or alias name of Mongoid field.
+    #
+    # @since 1.1.1
+    def create_taggable_mongoid_index(name)
+      index({ name => 1 }, { background: true })
+    end
+
+    # Defines all accessor methods for the taggable context at both
+    # the instance and class level.
+    #
+    # @param [ Symbol ] context The name of the tag context.
+    #
+    # @since 1.1.1
+    def define_taggable_accessors(context)
+      define_class_tags_getter(context)
+      define_class_weighted_tags_getter(context)
+      define_class_separator_getter(context)
+      define_class_tagged_with_getter(context)
+      define_class_group_by_getter(context)
+      define_instance_tag_string_getter(context)
+      define_instance_tag_setter(context)
+    end
+
+    # Create the singleton getter method to retrieve all tags
+    # of a given context for all instances of the model.
+    #
+    # @param [ Symbol ] context The name of the tag context.
+    #
+    # @since 1.1.1
+    def define_class_tags_getter(context)
+      # retrieve all tags ever created for the model
+      self.class.class_eval do
+        define_method context do |group_by = nil|
+          tags_for(context, group_by)
+        end
+      end
+    end
+
+    # Create the singleton getter method to retrieve a weighted
+    # array of tags of a given context for all instances of the model.
+    #
+    # @param [ Symbol ] context The name of the tag context.
+    #
+    # @since 1.1.1
+    def define_class_weighted_tags_getter(context)
+      self.class.class_eval do
+        define_method :"#{context}_with_weight" do |group_by = nil|
+          tags_with_weight_for(context, group_by)
+        end
+      end
+    end
+
+    # Create the singleton getter method to retrieve the tag separator
+    # for a given context for all instances of the model.
+    #
+    # @param [ Symbol ] context The name of the tag context.
+    #
+    # @since 1.1.1
+    def define_class_separator_getter(context)
+      self.class.class_eval do
+        define_method :"#{context}_separator" do
+          get_tag_separator_for(context)
+        end
+      end
+    end
+
+    # Create the singleton getter method to retrieve the all
+    # instances of the model which contain the tag/tags for a given context.
+    #
+    # @param [ Symbol ] context The name of the tag context.
+    #
+    # @since 1.1.1
+    def define_class_tagged_with_getter(context)
+      self.class.class_eval do
+        define_method :"#{context}_tagged_with" do |tags|
+          tagged_with(context, tags)
+        end
+      end
+    end
+
+    # Create the singleton getter method to retrieve the
+    # group_by field
+    #
+    # @param [ Symbol ] context The name of the tag context.
+    #
+    # @since 1.1.1
+    def define_class_group_by_getter(context)
+      self.class.class_eval do
+        define_method :"#{context}_group_by_field" do
+          get_tag_group_by_field_for(context)
+        end
+      end
+    end
+
+    # Create the setter method for the provided taggable, using an
+    # alias method chain to the underlying field method.
+    #
+    # @param [ Symbol ] context The name of the tag context.
+    #
+    # @since 1.1.1
+    def define_instance_tag_setter(context)
+      generated_methods.module_eval do
+        alias_method "#{context}_without_taggable=", "#{context}="
+        re_define_method("#{context}=") do |value|
+          value = self.class.format_tags_for(context, value)
+          self.send("#{context}_without_taggable=", value)
+        end
+        #alias_method_chain "#{context}=", :taggable
+      end
+    end
+
+    # Create the getter method for the joined tags string.
+    #
+    # @param [ Symbol ] context The name of the tag context.
+    #
+    # @since 1.1.1
+    def define_instance_tag_string_getter(context)
+      generated_methods.module_eval do
+        re_define_method("#{context}_string") do
+          tag_string_for(context)
+        end
+
+        re_define_method("#{context}_string=") do |value|
+          set_tag_string_for(context, value)
+        end
+      end
+    end
+  end
+end