radiant-taggable-extension 1.2.0

data/README.md

@@ -0,0 +1,125 @@
+# Taggable
+
+This is another way to apply tags to objects in your radiant site and retrieve objects by tag. If you're looking at this you will also want to look at the [tags](http://github.com/jomz/radiant-tags-extension/tree) extension, which does a good job of tag-clouding and may be all you need, and at our [library](https://github.com/spanner/radiant-library-extension) which uses this functionality to make an image gallery and document library and may be a useful starting point for other extensions.
+
+## Why?
+
+This extension differs from `tags` in a few ways that matter to me but may not to you:
+
+* We're not so focused on tag clouds - though you can still make them - but more on archival and linking functions.
+* We replace the keywords mechanism on pages rather than adding another one.
+* Anything can be tagged. By default we only do pages but other extensions can participate with a single line in a model class. See the [taggable_events](https://github.com/spanner/radiant-taggable_events-extension) extension for a minimal example or just put `is_taggable` at the top of a model class and see what happens.
+* We don't use `has_many_polymorphs` (it burns!)
+* Or any of the tagging libraries: it only takes a few named_scopes
+* it's multi-site compatible: if our fork is installed then you get site-scoped tags and taggings.
+
+When you first install the extension you shouldn't see much difference: all we do out of the box is to take over (and make more prominent) the keywords field in the page-edit view.
+
+## New
+
+I've just stripped out quite a lot of display clutter in order to focus on the basic tagging mechanism here. Retrieval and display is now handled by the [library](http://example.com/) extension. The core radius tags remain here. Anything that used to refer to a tag page is probably now handled by the library page.
+
+## Status 
+
+The underlying code is fairly well broken-in and has been in production for a couple of years, but I've rearranged it quite drastically and the interface is all new. There are tests now: not detailed but with reasonable coverage. Silly mistakes are getting less likely.
+
+## Efficiency
+
+Not too bad, I think. Most of the heavy retrieval functions have been squashed down into single queries. Each of these:
+
+	Tag.most_popular(50)
+	Tag.coincident_with(tag1, tag2, tag3)
+	Page.tagged_with(tag1, tag2, tag3)
+	Page.related_pages 								# equivalent to Page.tagged_with(self.attached_tags) - [self]
+
+is handled in a single pass. 
+
+The exception is the `r:tag_cloud` tag: there we have to gather a list of descendant pages first. It's done in a fairly frugal way (by generation rather than individual) but still likely to involve several preparatory queries as well as the cloud computation.
+
+## Radius tags
+
+This extension creates several radius tags. There are two kinds:
+
+### presenting tag information
+
+are used in the usual to display the properties and associations of a given tag (which can be supplied to a library as a query parameter or just specified in the radius tag)
+
+	<r:tag:title />
+	<r:tag:description />
+	<r:tag:pages:each>...</r:tag:pages:each>
+
+currently only available in a tag cloud (or a `top_tags` list):
+
+	<r:tag:use_count />
+
+### presenting page information
+
+These display the tag-associations of a given page.
+
+	<r:if_tags>...</r:if_tags>
+	<r:unless_tags>...</r:unless_tags>
+	<r:tags:each>...</r:tags:each>
+	<r:related_pages:each>...</r:related_pages:each>
+	<r:tag_cloud [url=""] />
+
+The library extension adds a lot more ways to retrieve lists of tags and tagged objects, and to work with assets in the same way as we do here with pages.
+	
+## Note about tag cloud prominence
+
+The calculation of prominence here applies a logarithmic curve to create a more even distribution of weight. It's continuous rather than banded, and sets the font size and opacity for each tag in a style attribute.
+
+## Usage examples
+
+Add tags to your pages by putting a comma-separated list in the 'keywords' box. That's about to get more helpful.
+
+### To show related pages:
+
+Put this in your layout:
+
+	<r:if_tags>
+	  <h3>See also</h3>
+	  <ul>
+	    <r:related_pages.each>
+	      <li><r:link /></li>
+	    <r:related_pages.each>
+	  </ul>
+	</r:if_tags>
+
+### To display a tag cloud on a section front page:
+
+Include the sample tagcloud.css in your styles and put this somewhere in the page or layout:
+
+	<r:tag_cloud />
+
+Seek venture capital immediately.
+	
+## Next steps
+
+* auto-completer to improve tagging consistency.
+	
+## Requirements
+
+* Radiant 0.8.1
+* `will_paginate` gem
+
+This is no longer compatible with 0.7 because we're doing a lot of :having in the scopes and you need rails 2.3 for that.
+
+## Installation
+
+As usual:
+
+	git clone git://github.com/spanner/radiant-taggable-extension.git vendor/extensions/taggable
+	rake radiant:extensions:taggable:migrate
+	rake radiant:extensions:taggable:update
+
+The update task will bring over a couple of CSS files for styling tags but you'll want to improve those.
+
+## Bugs
+
+Very likely. [Github issues](http://github.com/spanner/radiant-taggable-extension/issues), please, or for little things an email or github message is fine.
+
+## Author and copyright
+
+* William Ross, for spanner. will at spanner.org
+* Copyright 2009 spanner ltd
+* released under the same terms as Rails and/or Radiant

data/Rakefile

@@ -0,0 +1,136 @@
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "radiant-taggable-extension"
+    gem.summary = %Q{Taggable Extension for Radiant CMS}
+    gem.description = %Q{General purpose tagging extension: more versatile but less focused than the tags extension}
+    gem.email = "will@spanner.org"
+    gem.homepage = "http://github.com/spanner/radiant-taggable-extension"
+    gem.authors = ["spanner"]
+    gem.add_dependency "radiant", ">= 0.9.0"
+  end
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. This is only required if you plan to package taggable as a gem."
+end
+
+# In rails 1.2, plugins aren't available in the path until they're loaded.
+# Check to see if the rspec plugin is installed first and require
+# it if it is.  If not, use the gem version.
+
+# Determine where the RSpec plugin is by loading the boot
+unless defined? RADIANT_ROOT
+  ENV["RAILS_ENV"] = "test"
+  case
+  when ENV["RADIANT_ENV_FILE"]
+    require File.dirname(ENV["RADIANT_ENV_FILE"]) + "/boot"
+  when File.dirname(__FILE__) =~ %r{vendor/radiant/vendor/extensions}
+    require "#{File.expand_path(File.dirname(__FILE__) + "/../../../../../")}/config/boot"
+  else
+    require "#{File.expand_path(File.dirname(__FILE__) + "/../../../")}/config/boot"
+  end
+end
+
+require 'rake'
+require 'rake/rdoctask'
+require 'rake/testtask'
+
+rspec_base = File.expand_path(RADIANT_ROOT + '/vendor/plugins/rspec/lib')
+$LOAD_PATH.unshift(rspec_base) if File.exist?(rspec_base)
+require 'spec/rake/spectask'
+require 'cucumber'
+require 'cucumber/rake/task'
+
+# Cleanup the RADIANT_ROOT constant so specs will load the environment
+Object.send(:remove_const, :RADIANT_ROOT)
+
+extension_root = File.expand_path(File.dirname(__FILE__))
+
+task :default => :spec
+task :stats => "spec:statsetup"
+
+desc "Run all specs in spec directory"
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.spec_opts = ['--options', "\"#{extension_root}/spec/spec.opts\""]
+  t.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+task :features => 'spec:integration'
+
+namespace :spec do
+  desc "Run all specs in spec directory with RCov"
+  Spec::Rake::SpecTask.new(:rcov) do |t|
+    t.spec_opts = ['--options', "\"#{extension_root}/spec/spec.opts\""]
+    t.spec_files = FileList['spec/**/*_spec.rb']
+    t.rcov = true
+    t.rcov_opts = ['--exclude', 'spec', '--rails']
+  end
+  
+  desc "Print Specdoc for all specs"
+  Spec::Rake::SpecTask.new(:doc) do |t|
+    t.spec_opts = ["--format", "specdoc", "--dry-run"]
+    t.spec_files = FileList['spec/**/*_spec.rb']
+  end
+
+  [:models, :controllers, :views, :helpers].each do |sub|
+    desc "Run the specs under spec/#{sub}"
+    Spec::Rake::SpecTask.new(sub) do |t|
+      t.spec_opts = ['--options', "\"#{extension_root}/spec/spec.opts\""]
+      t.spec_files = FileList["spec/#{sub}/**/*_spec.rb"]
+    end
+  end
+  
+  desc "Run the Cucumber features"
+  Cucumber::Rake::Task.new(:integration) do |t|
+    t.fork = true
+    t.cucumber_opts = ['--format', (ENV['CUCUMBER_FORMAT'] || 'pretty')]
+    # t.feature_pattern = "#{extension_root}/features/**/*.feature"
+    t.profile = "default"
+  end
+
+  # Setup specs for stats
+  task :statsetup do
+    require 'code_statistics'
+    ::STATS_DIRECTORIES << %w(Model\ specs spec/models)
+    ::STATS_DIRECTORIES << %w(View\ specs spec/views)
+    ::STATS_DIRECTORIES << %w(Controller\ specs spec/controllers)
+    ::STATS_DIRECTORIES << %w(Helper\ specs spec/views)
+    ::CodeStatistics::TEST_TYPES << "Model specs"
+    ::CodeStatistics::TEST_TYPES << "View specs"
+    ::CodeStatistics::TEST_TYPES << "Controller specs"
+    ::CodeStatistics::TEST_TYPES << "Helper specs"
+    ::STATS_DIRECTORIES.delete_if {|a| a[0] =~ /test/}
+  end
+
+  namespace :db do
+    namespace :fixtures do
+      desc "Load fixtures (from spec/fixtures) into the current environment's database.  Load specific fixtures using FIXTURES=x,y"
+      task :load => :environment do
+        require 'active_record/fixtures'
+        ActiveRecord::Base.establish_connection(RAILS_ENV.to_sym)
+        (ENV['FIXTURES'] ? ENV['FIXTURES'].split(/,/) : Dir.glob(File.join(RAILS_ROOT, 'spec', 'fixtures', '*.{yml,csv}'))).each do |fixture_file|
+          Fixtures.create_fixtures('spec/fixtures', File.basename(fixture_file, '.*'))
+        end
+      end
+    end
+  end
+end
+
+desc 'Generate documentation for the taggable extension.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'TaggableExtension'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+# For extensions that are in transition
+desc 'Test the taggable extension.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+# Load any custom rakefiles for extension
+Dir[File.dirname(__FILE__) + '/tasks/*.rake'].sort.each { |f| require f }

data/VERSION

@@ -0,0 +1 @@
+1.2.0

data/app/controllers/admin/taggings_controller.rb

@@ -0,0 +1,8 @@
+class Admin::TaggingsController < Admin::ResourceController
+  
+  def destroy
+    model.destroy
+    render :nothing => true
+  end
+
+end

data/app/controllers/admin/tags_controller.rb

@@ -0,0 +1,17 @@
+class Admin::TagsController < Admin::ResourceController
+  
+  def index 
+    @tags = Tag.with_count
+    response_for :plural
+  end
+  
+  def show
+    @tag = load_model
+  end
+  
+  def cloud
+    @tags = Tag.sized(Tag.with_count)
+    response_for :plural
+  end
+    
+end

data/app/models/tag.rb

@@ -0,0 +1,200 @@
+class Tag < ActiveRecord::Base
+
+  attr_accessor :cloud_band, :cloud_size
+  
+  belongs_to :created_by, :class_name => 'User'
+  belongs_to :updated_by, :class_name => 'User'
+  has_many :taggings, :dependent => :destroy
+  is_site_scoped if respond_to? :is_site_scoped
+  has_site if respond_to? :has_site
+
+  # this is useful when we need to go back and add popularity to an already defined list of tags
+  
+  named_scope :in_this_list, lambda { |tags|
+    {
+      :conditions => ["tags.id IN (#{tags.map{'?'}.join(',')})", *tags.map{|t| t.is_a?(Tag) ? t.id : t}]
+    }
+  }
+  
+  # this is normally used to exclude current tags from a cloud or list
+  
+  named_scope :except, lambda { |tags|
+    if tags.any?
+      { :conditions => ["tags.id NOT IN (#{tags.map{'?'}.join(',')})", *tags.map{|t| t.is_a?(Tag) ? t.id : t}] }
+    end
+  }
+  
+  # NB unused tags are omitted
+  
+  named_scope :with_count, {
+    :select => "tags.*, count(tt.id) AS use_count", 
+    :joins => "INNER JOIN taggings as tt ON tt.tag_id = tags.id", 
+    :group => "tags.id",
+    :order => 'title ASC'
+  }
+  
+  named_scope :most_popular, lambda { |count|
+    {
+      :select => "tags.*, count(tt.id) AS use_count", 
+      :joins => "INNER JOIN taggings as tt ON tt.tag_id = tags.id", 
+      :group => "tags.id",
+      :limit => count,
+      :order => 'use_count DESC'
+    }
+  }
+  
+  # this takes a list and returns all the tags attached to any item in that list
+  # NB. won't work with a heterogeneous group: all items must be of the same class
+  
+  named_scope :attached_to, lambda { |these|
+    klass = these.first.is_a?(Page) ? Page : these.first.class
+    {
+      :joins => "INNER JOIN taggings as tt ON tt.tag_id = tags.id", 
+      :conditions => ["tt.tagged_type = '#{klass}' and tt.tagged_id IN (#{these.map{'?'}.join(',')})", *these.map(&:id)],
+    }
+  }
+  
+  # this takes a class name and returns all the tags attached to any object of that class
+  
+  named_scope :attached_to_a, lambda { |klass|
+    klass = klass.to_s.titleize
+    {
+      :joins => "INNER JOIN taggings as tt ON tt.tag_id = tags.id", 
+      :conditions => "tt.tagged_type = '#{klass}'",
+    }
+  }
+  
+  def to_s
+    title
+  end
+  
+  # Standardises formatting of tag name in urls
+  
+  def clean_title
+    Rack::Utils.escape(title)
+  end
+  
+  # Returns a list of all the objects tagged with this tag. We can't do this in SQL because it's polymorphic (and has_many_polymorphs makes my skin itch)
+  
+  def tagged
+    taggings.map {|t| t.tagged}
+  end
+  
+  def pages
+    Page.from_tags([self])
+  end
+  
+  # Returns a list of all the tags that have been applied alongside this one.
+  
+  def coincident_tags
+    tags = []
+    self.tagged.each do |t|
+      tags += t.attached_tags if t
+    end
+    tags.uniq - [self]
+  end
+  
+  # Returns a list of all the tags that have been applied alongside _all_ of the supplied tags.
+  # used to offer reductive facets on library pages
+  # not very efficient at the moment, largely thanks to polymorphic tagging relationship
+  # TODO: omit tags with no reductive power (ie applied to all the tagged items)
+  
+  def self.coincident_with(tags)
+    related_tags = []
+    tagged = Tagging.with_all_of_these(tags).map(&:tagged)
+    tagged.each do |t|
+      related_tags += t.attached_tags if t
+    end
+    related_tags.uniq - tags
+  end
+  
+  # returns true if tags are site-scoped
+  
+  def self.sited?
+    !reflect_on_association(:site).nil?
+  end
+  
+  # turns an array or comma-separated string of tag titles into a list of tag objects, creating if specified
+
+  def self.from_list(list=[], or_create=true)
+    list = list.split(/[,;]\s*/) if String === list
+    list.uniq.map {|t| self.for(t, or_create) }.select{|t| !t.nil? } if list && list.any?
+  end
+  
+  def self.to_list(tags=[])
+    tags.uniq.map(&:title).join(',')
+  end
+  
+  # finds or creates a tag with the supplied title
+  
+  def self.for(title, or_create=true)
+    if or_create
+      self.sited? ? self.find_or_create_by_title_and_site_id(title, Page.current_site.id) : self.find_or_create_by_title(title)
+    else
+      self.sited? ? self.find_by_title_and_site_id(title, Page.current_site.id) : self.find_by_title(title)
+    end
+  end
+  
+  # applies the usual cloud-banding algorithm to a set of tags with use_count
+  
+  def self.banded(tags=Tag.most_popular(100), bands=6)
+    if tags
+      count = tags.map{|t| t.use_count.to_i}
+      if count.any? # urgh. dodging named_scope count bug
+        max_use = count.max
+        min_use = count.min
+        divisor = ((max_use - min_use) / bands) + 1
+        tags.each do |tag|
+          tag.cloud_band = (tag.use_count.to_i - min_use) / divisor
+        end
+        tags
+      end
+    end
+  end
+  
+  # derived from here:
+  # http://stackoverflow.com/questions/604953/what-is-the-correct-algorthm-for-a-logarthmic-distribution-curve-between-two-poin
+  
+  def self.sized(tags=Tag.most_popular(100), threshold=0, biggest=1.0, smallest=0.4)
+    if tags
+      counts = tags.map{|t| t.use_count.to_i}
+      if counts.any?
+        max = counts.max
+        min = counts.min
+        if max == min
+          tags.each do |tag|
+            tag.cloud_size = sprintf("%.2f", biggest/2 + smallest/2)
+          end
+        else
+          steepness = Math.log(max - (min-1))/(biggest - smallest)
+          tags.each do |tag|
+            offset = Math.log(tag.use_count.to_i - (min-1))/steepness
+            tag.cloud_size = sprintf("%.2f", smallest + offset)
+          end
+        end
+        tags
+      end
+    end
+  end
+  
+  # takes a list of tags and reaquires it from the database, this time with incidence.
+  
+  def self.for_cloud(tags)
+    return tags if tags.empty? || tags.first.cloud_size
+    sized(in_this_list(tags).with_count)
+  end
+  
+  def self.cloud_from(these)
+    for_cloud(attached_to(these))
+  end
+  
+  # adds retrieval methods for a taggable class to this class and to Tagging.
+  
+  def self.define_class_retrieval_methods(classname)
+    Tagging.send :named_scope, "of_#{classname.downcase.pluralize}".intern, :conditions => { :tagged_type => classname.to_s }
+    define_method("#{classname.downcase}_taggings") { self.taggings.send "of_#{classname.downcase.pluralize}".intern }
+    define_method("#{classname.downcase.pluralize}") { self.send("#{classname.to_s.downcase}_taggings".intern).map{|l| l.tagged} }
+  end
+      
+end
+

data/app/models/tagging.rb

@@ -0,0 +1,50 @@
+class Tagging < ActiveRecord::Base
+
+  belongs_to :tag
+  belongs_to :tagged, :polymorphic => true
+
+  named_scope :with, lambda { |tag|
+    {
+      :conditions => ["taggings.tag_id = ?", tag.id]
+    }
+  }
+  named_scope :with_any_of_these, lambda { |tags| 
+    {
+      :select => "taggings.*", 
+      :conditions => ["taggings.tag_id IN (#{tags.map{'?'}.join(',')})", *tags.map{|t| t.is_a?(Tag) ? t.id : t}],
+      :group => "taggings.tagged_type, taggings.tagged_id"
+    }
+  }
+  
+  # this scope underpins a lot of the faceting:
+  # it returns a list of taggings of objects to whom all the supplied tags have been applied
+  # and is always used with map(&:tagged) to get a list of objects
+  
+  named_scope :with_all_of_these, lambda { |tags| 
+    {
+      :select => "taggings.*", 
+      :conditions => ["taggings.tag_id IN (#{tags.map{'?'}.join(',')})", *tags.map{|t| t.is_a?(Tag) ? t.id : t}],
+      :group => "taggings.tagged_type, taggings.tagged_id",
+      :having => "COUNT(taggings.tag_id) >= #{tags.length}"
+    }
+  }
+  
+  # this takes a class name and returns all the taggings of that class
+  # eg. @tag.taggings.of_a('page')
+  
+  named_scope :of_a, lambda { |klass|
+    klass = klass.to_s.titleize
+    {
+      :conditions => "tagged_type = '#{klass}'",
+    }
+  }
+  
+  
+  # good housekeeping idea from tags extension.
+  # if all the taggings for a particular tag are deleted, we want to delete the tag too
+  
+  def before_destroy
+    tag.destroy_without_callbacks if Tagging.with(tag).count < 1
+  end    
+  
+end

data/app/views/admin/pages/_edit_title.html.haml

@@ -0,0 +1,28 @@
+- content_for :page_css do
+  :sass 
+    p.title
+      :width 70%
+    p.keywords
+      :width 28%
+      :float right
+      :margin 0 1% 0 0
+    #content 
+      form
+        .keywords 
+          .textbox
+            :font-family Georgia, Palatino, "Times New Roman", Times, serif
+            :font-size 200%
+            :width 100%
+            :color #c00
+            :margin-top 4px
+    #attributes
+      :clear both
+            
+- fields_for :page, @page do |fields|
+  %p.keywords
+    %label{:for=>"page_keywords"}
+      Tags
+    = fields.text_field :keywords, :class => 'textbox'
+  %p.title
+    %label{:for=>"page_title"}= t('page_title')
+    = fields.text_field :title, :class => 'textbox', :maxlength => 255

data/app/views/admin/tags/_form.html.haml

@@ -0,0 +1,23 @@
+= render_region :form_top
+- render_region :form do |form_region|
+  .form-area
+    - form_region.edit_name do
+      %p.title
+        = form.label :title
+        = form.text_field :title, :class => 'textbox', :maxlength => 255
+
+    - form_region.edit_description do
+      %div
+        = form.label :description
+        = form.text_area :description, :class => "textarea", :style => "width: 100%"
+
+- render_region :form_bottom do |form_bottom_region|
+  - form_bottom_region.edit_timestamp do
+    = updated_stamp @tag  
+
+  - form_bottom_region.edit_buttons do
+    %p.buttons
+      = save_model_button(@tag)
+      = save_model_and_continue_editing_button(@tag)
+      or
+      = link_to "Cancel", admin_tags_url

data/app/views/admin/tags/_search_results.html.haml

@@ -0,0 +1,10 @@
+%ul#search_list
+  - unless @labels.empty?
+    - @labels.each do |label| 
+      - dom_id = "label_#{label.id}"
+      %li.label{ :id => dom_id }
+         %strong
+           = link_to label.title, edit_label_url(label)
+  - else
+    %li
+      %p.note There were no labels found

data/app/views/admin/tags/cloud.html.haml

@@ -0,0 +1,17 @@
+- include_stylesheet 'admin/tags'
+- url = Radiant::Config['tags.page'] || '/tags'
+
+%h1 Tag cloud
+
+%p
+  = link_to "← view as list", admin_tags_url
+
+%div.cloud
+  - @tags.each do |tag|
+    = link_to tag.title, admin_tag_url(tag), :style => "font-size: #{tag.cloud_size.to_f * 2.5}em;"
+    
+#actions
+  %ul
+    %li= link_to image('plus') + " " + "new tag", new_admin_tag_url
+    %li= link_to "tag list", admin_tags_url, :class => 'minor'
+    %li= link_to "tag cloud", cloud_admin_tags_url, :class => 'minor'

data/app/views/admin/tags/edit.html.haml

@@ -0,0 +1,14 @@
+- include_stylesheet 'admin/tags' 
+
+- render_region :main do |main|
+  - main.edit_header do
+    %h1
+      Edit Tag
+    
+  - main.edit_form do
+    - form_for :tag, :url => admin_tag_path(@tag), :html => { :method => "put", :multipart => true } do |form|
+      = render :partial => 'form', :object => form
+
+    
+    
+