tagalong 0.0.4 → 0.0.5

data/.travis.yml

@@ -0,0 +1,7 @@
+language: ruby
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3
+  - ruby-head
+  - ree

data/README.md

@@ -1,14 +1,19 @@
 # Tagalong
 
-Tagalong is a Rails plugin that is intended to be clean, efficient, and simple. I have tried very hard to have the API make sense in terms of OOP as I have seen many other tagging libraries that I don't think do a great job of this.
+[![Build Status](https://secure.travis-ci.org/cyphactor/tagalong.png?branch=master)](http://travis-ci.org/cyphactor/tagalong)
 
-The other key differentiation between Tagalong and many of the other tagging libraries out there is the relational database structure behind the scenes. This allows us to differentiate this tagging plugin in the following ways:
+[Tagalong](http://github.com/cyphactor/tagalong) is a Rails tagging plugin that is intended to be clean, efficient, and simple. I have tried hard to keep the API slim and intelligable in terms of Object Oriented Programming. I focused heavily on this as I feel most other Rails tagging plugins seriously neglect OO in their APIs.
 
-* clean object oriented API
-* does NOT require saving of the model being tagged
+The other key differentiation between [Tagalong](http://github.com/cyphactor/tagalong) and other tagging libraries is the relational database structure behind the scenes. This database structure allows [Tagalong](http://github.com/cyphactor/tagalong) to provide not only an Object Oriented API, but also a set of features that help differentiate it from other Rails tagging plugins.
+
+## Feature Overview
+
+* clean Object Oriented API
+* does NOT require saving of the model when tagging/untagging
 * keeps history of tags Taggers have used
 * allows defining multiple Taggers and Taggables
-* tracks number of times tags are used
+* tracks the number of times tags are used
+* returns tag lists in alphabetical order (imporant for UI)
 
 ## Installation
 
@@ -20,23 +25,39 @@ And then execute:
 
     $ bundle
 
-Or install it yourself as:
+Or manually install it:
 
     $ gem install tagalong
 
+## API Concepts
+
+There are three major concepts that one should understand before reading the documentation for the API, the Tag, Tagger, and Taggable.
+
+### Tag
+
+A Tag in the [Tagalong](http://github.com/cyphactor/tagalong) API is represented by a string. Conceptually it is simply a textual label that is associated with a Taggable and a Tagger.
+
+### Tagger
+
+A Tagger is an object that will be performing the action of applying a tag to a Taggable. In most Rails apps this is the a User object.
+
+### Taggable
+
+A Taggable is an object that will be having the tags applied to it. In a Rails app this could be a Task object, Contact object, or any type of object that you want to be able to tag.
+
 ## Usage
 
 ### Migration Setup
 
-In order to use `tagalong` you have to generate the proper migrations so that the tags can be stored in the database. You can do this with the following command:
+In order to use [Tagalong](http://github.com/cyphactor/tagalong), generate the proper migrations so that the tags can be stored in the database. This can be done with the following command:
 
     rails generate tagalong:migration
 
-The above will generate the migration and place it appropriately in the db/migrate/ project path so that the next time you `rake db:migrate` it will make the changes to the database.
+The above will generate the migration and place it appropriately in the `db/migrate/` project path.
 
 ### Declaring Taggers and Taggables
 
-In order to use `tagalong` you need to first declare at least one Tagger and at least one Taggable. You do this as follows:
+It is necessary to declare at least one Tagger and Taggable in addition to generating and running the migrations. This is done as follows:
 
     class Contact < ActiveRecord::Base
       tagalong_taggable
@@ -46,58 +67,76 @@ In order to use `tagalong` you need to first declare at least one Tagger and at
       tagalong_tagger
     end
 
-### Tag things
+Once Taggers and Taggables are declared, they can be used in numerous ways as outlined below.
 
-To tag things you must use the Tagger object and hand it a persisted Taggable object with the given tag that you want to apply as follows:
+### Tagging
+
+To tag, call the `tag` method on a Tagger object and hand it a persisted Taggable object with the given label that you want to apply.
 
     @user.tag(@contact, "sometag")
 
-### Untag things
+### Untagging
 
-To untag things you must use the Tagger object and hand it a persisted Taggable object with the given tag that you want to untag as follows:
+To untag, call the `untag` method on a Tagger object and hand it a persisted Taggable object with the given label that you want to untag.
 
     @user.untag(@contact, "sometag")
 
-### List tags
-
-You can get the list of tags for either a Tagger or a Taggable.
+### Deleting
 
-When you get the tags from a Tagger you are getting a list of all tags that tagger has ever used. This can be done as follows:
+To delete a tag, call the `delete_tag` method on a Tagger object and hand it the label of the tag you want to delete. This will remove the tag from the Tagger, as well as all Taggables that might be using it.
 
-    @user.tags
-    # => ['some_tag', 'another_tag', 'woot_tag']
+    @user.delete_tag("sometag")
 
-When you get the tags from a Taggable you are getting a list of all the tags that taggable currently has applied. This can be done as follows:
+### List Tagger tags
 
-    @contact.tags
-    # => ['some_tag', 'woot_tag']
+To list Tagger tags, call the `tags` method on a Tagger object. This will return an array of all tags that Tagger has ever used in ascending alphabetical order.
 
-Tags are returned ordered by how often the tags are used.
+    @user.tags
+    # => ['another_tag', 'some_tag', 'woot_tag']
 
-### List tags with usage info
+### List Tagger tags with usage info
 
-Passing a taggable object to the tags method on the Tagger will return a list of hash objects containing the tag (`tag`), a boolean representing if the tag is applied to the passed taggable (`used`), and the number of applications of that tag by the Tagger (`number_of_references`).
+To list Tagger tags with usage info, call the `tags` method on a Tagger object passing in a Taggable object. This will return a list of hash objects containing the tag ( **:tag** ), a boolean representing if the Taggable passed in is currently tagged with that tag ( **:used** ), and the number of references of that tag by the Tagger ( **:number_of_references** ). The resulting list of hashes is ordered by tag in ascending alphabetical order.
 
     @user.tags(@contact)
     # => [
+           { tag: 'another_tag', :used => false, :number_of_references => 42 },
            { tag: 'some_tag', :used => true, :number_of_references => 23 },
-           { tag: 'another_tag', :used => false, :number_of_references => 42 }
+           { tag: 'woot_tag', :used => true, :number_of_references => 2 }
          ]
 
-### List taggables that have a tag
+### List Taggable tags
+
+To list Taggable tags, call the `tags` method on a Taggable object. This will return an array of all tags that Taggable is currently tagged with in ascending alphabetical order.
+
+    @contact.tags
+    # => ['some_tag', 'woot_tag']
 
-You can acquire an array of taggable objects that have a given tag using the `taggables_with` method on the Tagger object as follows:
+### List Taggables that have a tag
+
+To list Taggables that have a tag, call the `taggables_with` method on a Tagger object as follows. This will return an array of Taggable objects that are currently tagged with the given tag.
 
     @user.taggables_with('some_tag')
-    # => [Taggable Object, Taggable Object] (in this case Taggable Objects would be Contacts)
+    # => [Contact Object, Contact Object]
+
+### Check if Taggable is tagged with a tag
+
+To check if a Taggable is tagged with a tag, call the `tagged_with?` method on a Taggable object as follows. This will return `true` in the case that the Taggable IS currently tagged with the given tag, and `false` in the case where the Taggable is NOT currently tagged with the given tag.
+
+    @contact.tagged_with?('some_tag')
+    # => true
 
 ## Credits
 
-I just wanted to thank all of the other open source Rails tagging plugins out there. Especially, acts-as-taggable-on, I learned a lot from you all. Thanks!
+I just wanted to thank all of the other open source Rails tagging plugins out there. Especially, [acts-as-taggable-on](http://github.com/mbleigh/acts-as-taggable-on), [is_taggable](http://github.com/jamesgolick/is_taggable), and [rocket_tag](http://github.com/bradphelan/rocket_tag). I learned a lot from you all.
+
+I also want to thank [RealPractice, Inc.](http://realpractice.com) for donating some developer hours to the project as well as being our initial user.
+
+Beyond that I want to specifically thank [@cyoungberg](http://github.com/cyoungberg) and [@russCloak](http://github.com/russCloak) for discussing the API decissions with me. It definitely helped having you guys as a sounding board.
 
 ## Contributing
 
-If you are interested in contributing code please follow the process below and please include tests. Also, please fill out issues if you have discovered a bug or simply want to request a feature on our GitHub issues page.
+If you are interested in contributing code please follow the process below and include tests. Also, please fill out issues on our GitHub [issues](http://github.com/cyphactor/tagalong/issues) page if you have discovered a bug or simply want to request a feature.
 
 1. Fork it
 2. Create your feature branch (`git checkout -b my-new-feature`)

data/Rakefile

@@ -1,2 +1,5 @@
 #!/usr/bin/env rake
 require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+task :default => :spec

data/lib/tagalong/tagger.rb

@@ -26,6 +26,13 @@ module Tagalong
         tag_manager.remove_tag(tag_name)
       end
 
+      def delete_tag(tag_name)
+        tag = tagalong_tags.find_by_name(tag_name)
+        if tag.present?
+          tag.destroy
+        end
+      end
+
       def tags(taggable = nil)
         if taggable == nil
           return self.tagalong_tags.order("name ASC").map { |r| r.name }

data/lib/tagalong/version.rb

@@ -1,3 +1,3 @@
 module Tagalong
-  VERSION = "0.0.4"
+  VERSION = "0.0.5"
 end

data/spec/database.yml

@@ -1,4 +1,5 @@
 sqlite3:
   adapter: sqlite3
-  database: tagalong.sqlite3
+  database: ":memory:"
+  timeout: 500
 

data/spec/lib/tagalong/tagger_spec.rb

@@ -25,6 +25,28 @@ describe "Tagger" do
       end
     end
 
+    describe "#delete_tag" do
+      before(:each) do
+        @user.tag(@contact, "tag1")
+      end
+
+      it "should disassociate the tag that belongs to it" do
+        @user.delete_tag('tag1')
+        @user.tags.should_not include("tag1")
+      end
+
+      it "should destroy the tag record from the db" do
+        @user.delete_tag('tag1')
+        Tagalong::TagalongTag.find_by_name('tag1').should_not be_present
+      end
+
+      it "should not destroy tags it does not have" do
+        Tagalong::TagalongTag.create(:tagger_type => 'FakeTagger', :tagger_id => 1, :name => 'badTag')
+        @user.delete_tag('badTag')
+        Tagalong::TagalongTag.find_by_name('badTag').should be_present
+      end
+    end
+
     describe "#tags" do
       context "without a taggable" do
         it "returns list of tags the tagger has used" do

data/tagalong.gemspec

@@ -18,4 +18,5 @@ Gem::Specification.new do |gem|
   gem.add_dependency "activerecord"
   gem.add_development_dependency "sqlite3"
   gem.add_development_dependency "rspec"
+  gem.add_development_dependency "rake"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tagalong
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-15 00:00:00.000000000 Z
+date: 2012-05-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
-  requirement: &70166717593920 !ruby/object:Gem::Requirement
+  requirement: &70195968616540 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70166717593920
+  version_requirements: *70195968616540
 - !ruby/object:Gem::Dependency
   name: sqlite3
-  requirement: &70166717593440 !ruby/object:Gem::Requirement
+  requirement: &70195968616100 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70166717593440
+  version_requirements: *70195968616100
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70166717592940 !ruby/object:Gem::Requirement
+  requirement: &70195968615680 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,7 +43,18 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70166717592940
+  version_requirements: *70195968615680
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &70195968615240 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70195968615240
 description: A Rails tagging plugin that makes sense.
 email:
 - cyphactor@gmail.com
@@ -53,6 +64,7 @@ extra_rdoc_files: []
 files:
 - .gitignore
 - .rvmrc
+- .travis.yml
 - Gemfile
 - LICENSE
 - README.md