my_annotations 0.5.0 → 0.5.1

data/lib/annotations/acts_as_annotation_value.rb

@@ -0,0 +1,115 @@
+# ActsAsAnnotationValue
+module Annotations
+  module Acts #:nodoc:
+    module AnnotationValue #:nodoc:
+
+      def self.included(base)
+        base.send :extend, ClassMethods  
+      end
+
+      module ClassMethods
+        def acts_as_annotation_value(options)
+          cattr_accessor :ann_value_content_field, :is_annotation_value
+          
+          if options[:content_field].blank?
+            raise ArgumentError.new("Must specify the :content_field option that will be used as the field for the content")
+          end
+          
+          self.ann_value_content_field = options[:content_field] 
+          
+          has_many :annotations,
+                   :as => :value
+                   
+          has_many :annotation_value_seeds,
+                   :as => :value
+           
+          __send__ :extend, SingletonMethods
+          __send__ :include, InstanceMethods
+          
+          self.is_annotation_value = true
+        end
+      end
+      
+      # Class methods added to the model that has been made acts_as_annotation_value (the mixin target class).
+      module SingletonMethods
+        
+        # This class level method is used to determine whether there is an existing 
+        # annotation on an annotatable object, regardless of source. So, it is used to 
+        # determine whether a "duplicate" exists (but the notion of "duplicate"
+        # may vary between annotation value classes).
+        #
+        # This method may be redefined in your model.
+        # A default implementation is provided that may suffice for most cases.
+        # But note that it makes certain assumptions that may not be valid for all 
+        # kinds of annotation value models:
+        # - the joins for the value model use +ActiveRecord::Base::table_name+ to
+        #   determine the name of the table to join on.
+        # - the field used make the comparison on the content is defined by the 
+        #   ':content_field' option passed into acts_as_annotation_value.
+        # 
+        # Note: A precondition to this method is: this expects a valid 
+        # +annotation+ object (i.e. one that contains a valid +value+ 
+        # object, valid +annotatable+ object, valid +attribute+ and so on).
+        def has_duplicate_annotation?(annotation)
+          return false unless annotation.value.is_a?(self)
+          
+          val_table_name = self.table_name
+          
+          existing = Annotation.find(:all,
+                                     :joins => "INNER JOIN annotation_attributes ON annotation_attributes.id = annotations.attribute_id
+                                                INNER JOIN #{val_table_name} ON annotations.value_type = '#{self.name}' AND #{val_table_name}.id = annotations.value_id",
+                                     :conditions => [ "annotations.annotatable_type = ? AND 
+                                                       annotations.annotatable_id = ? AND
+                                                       annotation_attributes.name = ? AND
+                                                       #{val_table_name}.#{self.ann_value_content_field} = ?",
+                                                       annotation.annotatable_type,
+                                                       annotation.annotatable_id,
+                                                       annotation.attribute_name,
+                                                       annotation.value.send(self.ann_value_content_field) ])
+      
+          if existing.length == 0 || existing.first.id == annotation.id
+            return false
+          else
+            return true
+          end
+          
+        end
+
+        #A set of all values that have been used, or seeded, with one of the provided attribute names
+        def with_attribute_names attributes
+          attributes = Array(attributes)
+          annotations = Annotation.with_attribute_names(attributes).with_value_type(self.name).include_values.collect{|ann| ann.value}
+          seeds = AnnotationValueSeed.with_attribute_names(attributes).with_value_type(self.name).include_values.collect{|ann| ann.value}
+          (annotations | seeds).uniq
+        end
+      end
+      
+      # This module contains instance methods
+      module InstanceMethods
+
+        #Whether this value exists with a given attribute name
+        def has_attribute_name? attr
+          !annotations.with_attribute_name(attr).empty? || !annotation_value_seeds.with_attribute_name(attr).empty?
+        end
+
+        #The total number of annotations that match one or more attribute names.
+        def annotation_count attributes
+          attributes = Array(attributes)
+          annotations.with_attribute_names(attributes).count
+        end
+        
+        # The actual content of the annotation value
+        def ann_content
+          self.send(self.class.ann_value_content_field)
+        end
+        
+        # Set the actual content of the annotation value
+        def ann_content=(val)
+          self.send("#{self.class.ann_value_content_field}=", val)
+        end
+
+      end
+      
+    end
+  end
+end

data/lib/annotations/config.rb

@@ -0,0 +1,148 @@
+module Annotations
+  module Config
+    # List of attribute name(s) that need the corresponding value to be downcased (made all lowercase).
+    # 
+    # NOTE: The attribute names specified MUST all be in lowercase.
+    @@attribute_names_for_values_to_be_downcased = [ ]
+    
+    # List of attribute name(s) that need the corresponding value to be upcased (made all uppercase).
+    #
+    # NOTE: The attribute names specified MUST all be in lowercase.
+    @@attribute_names_for_values_to_be_upcased = [ ]
+    
+    # This defines a hash of attributes, and the characters/strings that need to be stripped (removed) out of values of the attributes specified.
+    # Regular expressions can also be used instead of characters/strings.
+    # ie: { attribute_name => [ array of characters to strip out ] }    (note: doesn't have to be an array, can be a single string)
+    #
+    # e.g: { "tag" => [ '"', ','] } or { "tag" => '"' }
+    # 
+    # NOTE: The attribute name(s) specified MUST all be in lowercase. 
+    @@strip_text_rules = { }
+    
+    # This allows you to specify a different model name for users in the system (if different from the default: "User").
+    @@user_model_name = "User"
+    
+    # This allows you to limit the number of annotations (of specified attribute names) per source per annotatable.
+    #
+    # Key/value pairs in hash should follow the spec:
+    # { attribute_name => max_number_allowed }
+    #
+    # e.g: { "rating" =>1 } - will only ever allow 1 "rating" annotation per annotatable by each source.
+    #
+    # NOTE (1): The attribute name(s) specified MUST all be in lowercase.
+    @@limits_per_source = { }
+    
+    # By default, duplicate annotations CANNOT be created (same value for the same attribute, on the same annotatable object, regardless of source). 
+    # For example: a user cannot add a description to a specific book that matches an existing description for that book.
+    # 
+    # This config setting allows exceptions to this rule, on a per attribute basis. 
+    # I.e: allow annotations with certain attribute names to have duplicate values (per annotatable).
+    #
+    # e.g: [ "tag", "rating" ] - allows tags and ratings to have the same value more than once.
+    #
+    # NOTE (1): The attribute name(s) specified MUST all be in lowercase.
+    # NOTE (2): This setting can be used in conjunction with the limits_per_source setting to allow 
+    #           duplicate annotations BUT limit the number of annotations (per attribute) per user.
+    @@attribute_names_to_allow_duplicates = [ ]
+    
+    # This allows you to restrict the content of the values for annotations with a specific attribute name.
+    #
+    # Key/value pairs in the hash should follow the spec:
+    # { attribute_name => { :in => array_or_range, :error_message => error_msg_to_show_if_value_not_allowed }
+    #
+    # e.g: { "rating" => { :in => 1..5, :error_message => "Please provide a rating between 1 and 5" } }
+    #
+    # NOTE (1): The attribute name(s) specified MUST all be in lowercase.
+    # NOTE (2): values will be checked in a case insensitive manner.
+    @@content_restrictions = { }
+
+    # This determines what template to use to generate the unique 'identifier' for new AnnotationAttribute objects.
+    #
+    # String interpolation will be used to place the 'name' of the annotation within the template,
+    # in order to generate a unique identifier (usually a URI).
+    #
+    # This uses the @@attribute_name_transform_for_identifier defined below when performing the substitution.
+    #
+    # For more info on this substitution algorithm, see AnnotationAttribute#before_validation.
+    @@default_attribute_identifier_template = "http://www.example.org/attribute#%s"
+
+    # Defines a Proc that will be used to transform the value of AnnotationAttribute#name when generating the
+    # AnnotationAttribute#identifier value. See AnnotationAttribute#before_validation for more info.
+    @@attribute_name_transform_for_identifier = Proc.new { |name| name.to_s }
+    
+    # This stores the factory Procs that are used to generate the value objects
+    # for annotations, based on the attribute name.
+    #
+    # - Keys should be attribute names (as Strings, in lowercase).
+    # - Values should either be a Proc that takes in one argument - the raw value object, that is then used 
+    # to output the actual value to be stored. IMPORTANT: the Procs must be exhibit consistent data behaviour. 
+    # I.e. should be able to run them over and over again without causing data inconsistencies or harmful side effects.
+    #
+    # NOTE (1): this is run BEFORE the default value generation logic in the +Annotation+ model.
+    # The default value generation logic will still run after the Proc.
+    # NOTE (2): The attribute name(s) specified MUST all be in lowercase.
+    @@value_factories_for_attributes = { }
+    
+    # This determines the valid value types that are allowed for certain attribute names.
+    #
+    # - Keys should be attribute names (as Strings, in lowercase).
+    # - Values should be an Array of Strings, or single String, of valid class names for the value object type.
+    #
+    # NOTE (1): It is possible to use the above +value_factories_for_attributes+ option to achieve
+    # similar behaviour. However, this config option allows you to state explicitly what types are
+    # allowed as value objects.
+    # NOTE (2): The attribute name(s) specified MUST all be in lowercase.
+    @@valid_value_types = { }
+
+    # This determines whether versioning is enabled.
+    # The default behaviour is true, in which case when a new annotation is created or updated, a copy of the new version
+    # is stored in Annotation::Version and linked to the annotation. Likewise versions of the annotation values are created.
+    # By setting to false, no versions are recorded.
+    @@versioning_enabled = true
+    
+    def self.reset
+      @@attribute_names_for_values_to_be_downcased = [ ]
+      @@attribute_names_for_values_to_be_upcased = [ ]
+      @@strip_text_rules = { }
+      @@user_model_name = "User"
+      @@limits_per_source = { }
+      @@attribute_names_to_allow_duplicates = [ ]
+      @@content_restrictions = { }
+      @@default_attribute_identifier_template = "http://www.example.org/attribute#%s"
+      @@attribute_name_transform_for_identifier = Proc.new { |name| name.to_s }
+      @@value_factories = { }
+      @@valid_value_types = { }
+    end
+    
+    reset
+    
+    # This makes the variables above available externally.
+    # Shamelessly borrowed from the GeoKit plugin.
+    [ :attribute_names_for_values_to_be_downcased,
+      :attribute_names_for_values_to_be_upcased,
+      :strip_text_rules,
+      :user_model_name,
+      :limits_per_source,
+      :attribute_names_to_allow_duplicates,
+      :content_restrictions,
+      :default_attribute_identifier_template,
+      :attribute_name_transform_for_identifier,
+      :value_factories,
+      :valid_value_types,
+      :versioning_enabled].each do |sym|
+      class_eval <<-EOS, __FILE__, __LINE__
+        def self.#{sym}
+          if defined?(#{sym.to_s.upcase})
+            #{sym.to_s.upcase}
+          else
+            @@#{sym}
+          end
+        end
+
+        def self.#{sym}=(obj)
+          @@#{sym} = obj
+        end
+      EOS
+    end
+  end
+end

data/lib/annotations/routing.rb

@@ -0,0 +1,8 @@
+module Annotations #:nodoc:
+  def self.map_routes(map, collection={}, member={}, requirements={})
+    map.resources :annotations,
+                  :collection => { :create_multiple => :post }.merge(collection),
+                  :member => {}.merge(member),
+                  :requirements => { }.merge(requirements)
+  end
+end

data/lib/annotations/util.rb

@@ -0,0 +1,82 @@
+module Annotations
+  module Util
+  
+    # Migrate existing annotations to the v3 db schema.
+    #
+    # Currently it just copies all values over to TextValue entries
+    # and assigns 'value' of the annotation accordingly and fixes up
+    # all the versions of that annotation in a naive way.
+    #
+    # NOTE (1): If you need tdifferent migration behaviour, 
+    # redefine this method in your app (in the same namespace).
+    #
+    # NOTE (2): if individual annotations fail to migrate,
+    # their IDs and error info will be outputted to the console so you 
+    # can inspect the issue.
+    #
+    # NOTE (3): this won't migrate any AnnotationValueSeed entries.
+    # You will need to write another migration script/method for these.
+    #
+    # NOTE (4): this makes some big assumptions about your current set of
+    # annotations. Please look through to make sure the logic applies.
+    def self.migrate_annotations_to_v3
+      Annotation.record_timestamps = false
+      
+      Annotation.all.each do |ann|
+        begin
+          ann.transaction do
+            val = TextValue.new
+            
+            # Handle versions
+            #
+            # NOTE: This will take a naive approach of assuming that
+            # only the 'old_value' field has been changed over time,
+            # nothing else!
+            
+            # Build up the TextValue from the versions
+            ann.versions.each do |version|
+              val.text = version.old_value
+              val.created_at = version.created_at unless val.created_at
+              val.updated_at = version.updated_at
+              val.save!
+              
+              val_version = val.versions(true).last
+              val_version.created_at = version.created_at
+              val_version.updated_at = version.updated_at
+              val_version.save!
+            end
+            
+            # Assign new TextValue to Annotation
+            ann.value = val
+            ann.save!
+            
+            # Only keep second to last version,
+            # deleting others, and resetting version
+            # numbers.
+            ann.versions(true).each do |version|
+              if version == ann.versions[-2]
+                # The one we want to keep
+                version.version = 1
+                version.value = val
+                version.save!
+              else
+                # Delete!
+                version.destroy
+              end
+            end
+            ann.version = 1
+            ann.save!    # This shouldn't result in a new version
+          end
+        rescue Exception => ex
+          puts "FAILED to migrate annotation with ID #{ann.id}. Error message: #{ex.message}"
+        end
+      end
+      
+      # TODO: similar kind of migration for annotation value seeds
+      
+      Annotation.record_timestamps = true    
+    end
+  
+  end
+  
+end

data/lib/annotations_version_fu.rb

@@ -0,0 +1,119 @@
+# Kindly taken from the version_fu plugin (http://github.com/jmckible/version_fu/tree/master)
+
+# Module and file renamed (and modified accordingly) on 2009-01-28 by Jits,
+# to prevent conflicts with an external version_fu plugin installed in the main codebase.
+
+module AnnotationsVersionFu
+  def self.included(base)
+    base.extend ClassMethods
+  end
+
+  module ClassMethods
+    def annotations_version_fu(options={}, &block)
+      return if self.included_modules.include? AnnotationsVersionFu::InstanceMethods
+      __send__ :include, AnnotationsVersionFu::InstanceMethods
+
+      cattr_accessor :versioned_class_name, :versioned_foreign_key, :versioned_table_name, 
+                     :version_column, :versioned_columns
+
+      self.versioned_class_name         = options[:class_name]  || 'Version'
+      self.versioned_foreign_key        = options[:foreign_key] || self.to_s.foreign_key
+      self.versioned_table_name         = options[:table_name]  || "#{table_name_prefix}#{base_class.name.demodulize.underscore}_versions#{table_name_suffix}"
+      self.version_column               = options[:version_column]    || 'version'
+
+      # Setup versions association
+      class_eval do
+        has_many :versions, :class_name  => "#{self.to_s}::#{versioned_class_name}",
+                            :foreign_key => versioned_foreign_key,
+                            :dependent   => :destroy do
+          def latest
+            find :first, :order=>'version desc'
+          end                    
+        end
+
+        before_save :check_for_new_version if Annotations::Config.versioning_enabled
+      end
+      
+      # Versioned Model
+      const_set(versioned_class_name, Class.new(ActiveRecord::Base)).class_eval do
+        # find first version before the given version
+        def self.before(version)
+          find :first, :order => 'version desc',
+            :conditions => ["#{original_class.versioned_foreign_key} = ? and version < ?", version.send(original_class.versioned_foreign_key), version.version]
+        end
+
+        # find first version after the given version.
+        def self.after(version)
+          find :first, :order => 'version',
+            :conditions => ["#{original_class.versioned_foreign_key} = ? and version > ?", version.send(original_class.versioned_foreign_key), version.version]
+        end
+
+        def previous
+          self.class.before(self)
+        end
+
+        def next
+          self.class.after(self)
+        end
+      end
+
+      # Housekeeping on versioned class
+      versioned_class.cattr_accessor :original_class
+      versioned_class.original_class = self
+      versioned_class.set_table_name versioned_table_name
+      
+      # Version parent association
+      versioned_class.belongs_to self.to_s.demodulize.underscore.to_sym, 
+        :class_name  => "::#{self.to_s}", 
+        :foreign_key => versioned_foreign_key
+      
+      # Block extension
+      versioned_class.class_eval &block if block_given?
+      
+      reload_versioned_columns_info
+    end
+    
+    def reload_versioned_columns_info
+      self.reset_column_information
+      self.versioned_class.reset_column_information
+      if self.versioned_class.table_exists?
+        self.versioned_columns = versioned_class.new.attributes.keys - 
+          [versioned_class.primary_key, versioned_foreign_key, version_column, 'created_at', 'updated_at']
+      else
+        ActiveRecord::Base.logger.warn "Version Table not found"
+      end
+    end
+    
+    def versioned_class
+      const_get versioned_class_name
+    end
+  end
+
+
+  module InstanceMethods
+    def find_version(number)
+      versions.find :first, :conditions=>{:version=>number}
+    end
+    
+    def check_for_new_version
+      instatiate_revision if create_new_version?
+      true # Never halt save
+    end
+    
+    # This the method to override if you want to have more control over when to version
+    def create_new_version?
+      # Any versioned column changed?
+      self.class.versioned_columns.detect {|a| __send__ "#{a}_changed?"}
+    end
+    
+    def instatiate_revision
+      new_version = versions.build
+      versioned_columns.each do |attribute|
+        new_version.__send__ "#{attribute}=", __send__(attribute)
+      end
+      version_number = new_record? ? 1 : version + 1
+      new_version.version = version_number
+      self.version = version_number
+    end
+  end
+end

data/lib/app/controllers/annotations_controller.rb

@@ -0,0 +1,162 @@
+class AnnotationsController < ApplicationController
+  
+  before_filter :login_required, :only => [ :new, :create, :edit, :update, :destroy, :create_multiple ]
+  
+  before_filter :find_annotation, :only => [ :show, :edit, :update, :destroy ] 
+  before_filter :find_annotatable, :except => [ :show, :edit, :update, :destroy ]
+  before_filter :authorise_action, :only =>  [ :edit, :update, :destroy ]
+  
+  # GET /annotations
+  # GET /annotations.xml
+  def index
+    params[:num] ||= 50
+    
+    @annotations =  
+    if @annotatable.nil?
+      Annotation.find(:all, :limit => params[:num])      
+    else
+      @annotatable.latest_annotations(params[:num])
+    end
+
+    respond_to do |format|
+      format.html # index.html.erb
+      format.xml  { render :xml => @annotations }
+    end
+  end
+
+  # GET /annotations/1
+  # GET /annotations/1.xml
+  def show
+    respond_to do |format|
+      format.html # show.html.erb
+      format.xml  { render :xml => @annotation }
+    end
+  end
+
+  # GET /annotations/new
+  # GET /annotations/new.xml
+  def new
+    @annotation = Annotation.new
+
+    respond_to do |format|
+      format.html # new.html.erb
+      format.xml  { render :xml => @annotation }
+    end
+  end
+
+  # POST /annotations
+  # POST /annotations.xml
+  def create
+    if params[:annotation][:source_type].blank? and params[:annotation][:source_id].blank?
+      if logged_in?
+        params[:annotation][:source_type] = current_user.class.name
+        params[:annotation][:source_id] = current_user.id
+      end
+    end
+    
+    @annotation = Annotation.new(params[:annotation])
+    @annotation.annotatable = @annotatable
+
+    respond_to do |format|
+      if @annotation.save
+        flash[:notice] = 'Annotation was successfully created.'
+        format.html { redirect_to :back }
+        format.xml  { render :xml => @annotation, :status => :created, :location => @annotation }
+      else
+        format.html { render :action => "new" }
+        format.xml  { render :xml => @annotation.errors, :status => :unprocessable_entity }
+      end
+    end
+  end
+  
+  # POST /annotations/create_multiple
+  # POST /annotations/create_multiple.xml
+  def create_multiple
+    if params[:annotation][:source_type].blank? and params[:annotation][:source_id].blank?
+      if logged_in?
+        params[:annotation][:source_type] = current_user.class.name
+        params[:annotation][:source_id] = current_user.id
+      end
+    end
+    
+    success, annotations, errors = Annotation.create_multiple(params[:annotation], params[:separator])
+
+    respond_to do |format|
+      if success
+        flash[:notice] = 'Annotations were successfully created.'
+        format.html { redirect_to :back }
+        format.xml  { render :xml => annotations, :status => :created, :location => @annotatable }
+      else
+        flash[:error] = 'Some or all annotations failed to be created.'
+        format.html { redirect_to :back }
+        format.xml  { render :xml => annotations + errors, :status => :unprocessable_entity }
+      end
+    end
+  end
+  
+  # GET /annotations/1/edit
+  def edit
+  end
+
+  # PUT /annotations/1
+  # PUT /annotations/1.xml
+  def update
+    @annotation.value = params[:annotation][:value]
+    @annotation.version_creator_id = current_user.id
+    respond_to do |format|
+      if @annotation.save
+        flash[:notice] = 'Annotation was successfully updated.'
+        format.html { redirect_to :back }
+        format.xml  { head :ok }
+      else
+        format.html { render :action => "edit" }
+        format.xml  { render :xml => @annotation.errors, :status => :unprocessable_entity }
+      end
+    end
+  end
+
+  # DELETE /annotations/1
+  # DELETE /annotations/1.xml
+  def destroy
+    @annotation.destroy
+
+    respond_to do |format|
+      flash[:notice] = 'Annotation successfully deleted.'
+      format.html { redirect_to :back }
+      format.xml  { head :ok }
+    end
+  end
+  
+  protected
+  
+  def find_annotation
+    @annotation = Annotation.find(params[:id])
+  end
+  
+  def find_annotatable
+    @annotatable = nil
+    
+    if params[:annotation]
+      @annotatable = Annotation.find_annotatable(params[:annotation][:annotatable_type], params[:annotation][:annotatable_id])
+    end
+    
+    # If still nil try again with alternative params
+    if @annotatable.nil?
+      @annotatable = Annotation.find_annotatable(params[:annotatable_type], params[:annotatable_id])
+    end
+  end
+  
+  # Currently only checks that the source of the annotation matches the current user
+  def authorise_action
+    if !logged_in? or (@annotation.source != current_user)
+      # TODO: return either a 401 or 403 depending on authentication
+      respond_to do |format|
+        flash[:error] = 'You are not allowed to perform this action.'
+        format.html { redirect_to :back }
+        format.xml  { head :forbidden }
+      end
+      return false
+    end
+    return true
+  end
+end

data/lib/app/controllers/application_controller.rb

@@ -0,0 +1,2 @@
+class ApplicationController < ActionController::Base # :nodoc:
+end

data/lib/app/helpers/application_helper.rb

@@ -0,0 +1,2 @@
+module ApplicationHelper # :nodoc:
+end