radiant-tags-extension 1.5.1

data/HELP.md

@@ -0,0 +1,50 @@
+The Tags extension provides a way for you to easily categorize your pages.
+
+== Results page
+
+	<r:search:empty>
+	  <h2>I couldn't find anything tagged with "<r:search:query/>".</h2>
+	</r:search:empty>
+
+	<r:search:results>
+	  <h2>Found the following pages that are tagged with "<em><r:search:query/></em>".</h2>
+
+	  <ul>
+	  <r:search:results:each>
+	    <li><r:link/> - <r:author/> - <r:date/></li>
+	  </r:search:results:each>
+	  </ul>
+	</r:search:results>
+
+
+== Tag cloud
+
+Use `<r:tag_cloud />` anywhere you like.
+I made a stab at building the 'perfect' tag cloud markup, as inspired by a post on 24ways.org;  http://24ways.org/2006/marking-up-a-tag-cloud
+
+== Tag list
+
+Use `<r:tag_list />` to get a list of tags for the current page. 
+Also works through children:each.
+
+== All tags
+
+Use `<r:all_tags />` to get a list of all tags. You may iterate through them with
+`<r:all_tags:each>` and access their associated pages with `<r:all_tags:each:pages:each>`
+
+== Collections
+
+You can grab a collection of pages with a certain tag like so;
+
+	<r:tagged with="sometag" [scope="/some/page"] [with_any="true"]>
+	  <r:link />
+	</r:tagged>
+
+Which would iterate over all the resulting pages, like you do with children:each.
+When you define scope, only this page and any of it's (grand)children will be used.
+Using scope="current_page" will use the page that is currently being rendered as scope. 
+You can also set limit, offset etc like with children:each.
+
+Using r:tagged in it's default setting searches for pages that have all of the given tags.
+Using r:tagged with the attribute 'with_any' set to 'true' will find pages that have any of
+the given tags.

data/HELP_admin.md

@@ -0,0 +1,30 @@
+The Tags extension allows you to configure the style of tagging between 2 options: 
+simple or complex strings.
+
+== Simple Tagging
+
+By default you may add tags to a page in a string such as "this that other". That string 
+will be parsed and turned into 3 separate tags.
+
+== Complex Tagging
+
+You may set `Radiant::Config['tags.complex_strings'] = true` to allow you to enter more 
+complex tags for your pages.
+
+When this setting is `true` the tags are delimited by a semi-colon, allowing you to enter 
+a string of tags such as "My Summer Vacation (2008); Entertainment/Nonsense; Miscellaneous 2.0". 
+The result of that string will return 3 tags: `My Summer Vacation (2008)`, 
+`Entertainment/Nonsense` and 'Miscellaneous 2.0'
+
+== Making the choice
+
+You'll need to restart the application server after changing this setting. Please keep in
+mind that any changes to this setting may affect any tags you currently have in the database.
+It is recommended that you choose either Simple or Complex, but that you do not switch 
+after creating your tags.
+
+== Tag Clouds
+
+Some styles are provided in tags.css for the <r:tag_cloud>. To use it, add this to your layout:
+  
+  <link rel="stylesheet" type="text/css" href="/stylesheets/tags.css" />

data/README

@@ -0,0 +1,38 @@
+= Tags extension
+
+Created by: Keith Bingman - keithbingman.com
+Revived by: Benny Degezelle - gorilla-webdesign.be
+New features by: Jim Gay - saturnflyer.com
+Version: 1.5
+
+This extension enhances the page model with tagging capabilities, tagging as in "2.0" and tagclouds.
+
+== Requirements
+
+This extension depends on the has_many_polymorphs plugin (included in vendor/plugins)
+If you're still on Radiant pre-0.6.7, then the shards_extension should be installed and loaded first.
+You can change the load order of extensions in config/environment.rb (see http://wiki.radiantcms.org/Using_the_Shards_Extension).
+
+== Installation
+
+1. Copy the extension to your vendor/extensions directory as you would any other extension.
+2. Run 'rake radiant:extensions:tags:install'
+3. Make a page to sit in /search/by-tag, and give it the "Tag Search" pagetype.
+	If you want to change this location, it's in Radiant::Config['tags.results_page_url'].
+
+Done!
+Here's a sample results page to get you started;
+	
+	<r:search:empty>
+	  <h2>I couldn't find anything tagged with "<r:search:query/>".</h2>
+	</r:search:empty>
+
+	<r:search:results>
+	  <h2>Found the following pages that are tagged with "<em><r:search:query/></em>".</h2>
+
+	  <ul>
+	  <r:search:results:each>
+	    <li><r:link/> - <r:author/> - <r:date/></li>
+	  </r:search:results:each>
+	  </ul>
+	</r:search:results>

data/Rakefile

@@ -0,0 +1,25 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the tags extension.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the tags extension.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'TagsExtension'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+# Load any custom rakefiles for extension
+Dir[File.dirname(__FILE__) + '/tasks/*.rake'].sort.each { |f| require f }

data/app/models/meta_tag.rb

@@ -0,0 +1,53 @@
+class MetaTag < ActiveRecord::Base
+
+  if Radiant::Config['tags.complex_strings'] == 'true'
+    delim = ";"
+    re_format = /^[a-zA-Z0-9,\_\-\s\/()'.&]+$/
+  else
+    delim = " "
+    re_format = /^[a-zA-Z0-9\_\-]+$/
+  end
+  DELIMITER = delim
+    # how to separate tags in strings (you may
+    # also need to change the validates_format_of parameters 
+    # if you update this)
+
+  # if speed becomes an issue, you could remove these validations 
+  # and rescue the AR index errors instead
+  validates_presence_of :name
+  validates_uniqueness_of :name, :case_sensitive => false
+  validates_format_of :name, :with => re_format, 
+    :message => "can not contain special characters"
+    
+  has_many_polymorphs :taggables, 
+    :from => [:pages], 
+    :through => :taggings, 
+    :dependent => :destroy,
+    :skip_duplicates => false
+  
+  def after_save
+    # if you allow editable tag names, you might want before_save instead 
+    self.name = name.downcase.strip.squeeze(" ")
+  end
+ 
+  class << self
+    def find_or_create_by_name!(name)
+      find_by_name(name) || create!(:name => name)
+    end
+
+    def cloud(args = {})
+      find(:all, :select => 'meta_tags.*, count(*) as popularity',
+      :limit => args[:limit] || 5,
+      :joins => "JOIN taggings ON taggings.meta_tag_id = meta_tags.id",
+      :conditions => args[:conditions],
+      :group => "meta_tags.id, meta_tags.name",
+      :order => "popularity DESC" )
+    end
+  end
+  
+  def <=>(other)
+    # To be able to sort an array of tags
+    name <=> other.name
+  end
+  
+end

data/app/models/radius_tags.rb

@@ -0,0 +1,328 @@
+module RadiusTags
+  include Radiant::Taggable
+  include ActionView::Helpers::TextHelper
+  
+  class TagError < StandardError; end
+  
+  desc %{
+    Expands if a <pre><r:tagged with="" /></pre> call would return items. Takes the same options as the 'tagged' tag.
+    The <pre><r:unless_tagged with="" /></pre> is also available.
+  }
+  tag "if_tagged" do |tag|
+    if tag.attr["with"]
+      tag.locals.tagged_results = find_with_tag_options(tag)
+      tag.expand unless tag.locals.tagged_results.empty?
+    else
+      tag.expand unless tag.locals.page.tag_list.empty?
+    end
+  end
+  tag "unless_tagged" do |tag|
+    if tag.attr["with"]
+      tag.expand if find_with_tag_options(tag).empty?
+    else
+      tag.expand if tag.locals.page.tag_list.empty?
+    end
+  end
+  
+  desc %{
+    Find all pages with certain tags, within in an optional scope. Additionally, you may set with_any to true to select pages that have any of the listed tags (opposed to all listed tags which is the provided default).
+    
+    *Usage:*
+    <pre><code><r:tagged with="shoes diesel" [scope="/fashion/cult-update"] [with_any="true"] [offset="number"] [limit="number"] [by="attribute"] [order="asc|desc"]>...</r:tagged></code></pre>
+  }
+  tag "tagged" do |tag|
+    unless tag.locals.tagged_results.nil? # We're inside an r:if_tagged, so results are already available;
+      results = tag.locals.tagged_results
+    else
+      results = find_with_tag_options(tag)
+    end
+    output = []
+    results.each do |page|
+      tag.locals.page = page
+      output << tag.expand
+    end
+    output
+  end
+  
+  desc %{
+    Find all pages related to the current page, based on all or any of the current page's tags. A scope attribute may be given to limit results to a certain site area.
+    
+    *Usage:*
+    <pre><code><r:related_by_tags [scope="/fashion/cult-update"] [offset="number"] [limit="number"] [by="attribute"] [order="asc|desc"]>...</r:related_by_tags></code></pre>
+  }
+  tag "related_by_tags" do |tag|
+    tag.attr["with"] = tag.locals.page.tag_list.split(MetaTag::DELIMITER)
+    tag.attr["with_any"] = true
+    tag.attr["exclude_id"] = tag.locals.page.id
+    results = find_with_tag_options(tag)
+    return false if results.size < 1
+    output = []
+    first = true
+    results.each do |page|
+      tag.locals.page = page
+      tag.locals.first = first
+      output << tag.expand
+      first = false
+    end
+    output
+  end
+  
+  tag "if_has_related_by_tags" do |tag|
+    tag.attr["with"] = tag.locals.page.tag_list.split(MetaTag::DELIMITER)
+    tag.attr["with_any"] = true
+    tag.attr["exclude_id"] = tag.locals.page.id
+    results = find_with_tag_options(tag)
+    results -= [tag.locals.page]
+    tag.expand if results.size > 0
+  end
+  
+  tag "related_by_tags:if_first" do |tag|
+    tag.expand if tag.locals.first
+  end
+  
+  desc %{
+    Render a Tag cloud
+    The results_page attribute will default to #{Radiant::Config['tags.results_page_url']}
+    
+    *Usage:*
+    <pre><code><r:tag_cloud_list [limit="number"] [results_page="/some/url"] [scope="/some/url"]/></code></pre>
+  }
+  tag "tag_cloud" do |tag|
+    tag_cloud = MetaTag.cloud(:limit => tag.attr['limit'] || 5).sort
+    tag_cloud = filter_tags_to_url_scope(tag_cloud, tag.attr['scope']) unless tag.attr['scope'].nil?
+    
+    results_page = tag.attr['results_page'] || Radiant::Config['tags.results_page_url']
+    output = "<ol class=\"tag_cloud\">"
+    if tag_cloud.length > 0
+    	build_tag_cloud(tag_cloud, %w(size1 size2 size3 size4 size5 size6 size7 size8 size9)) do |tag, cloud_class, amount|
+    		output += "<li class=\"#{cloud_class}\"><span>#{pluralize(amount, 'page is', 'pages are')} tagged with </span><a href=\"#{results_page}/#{tag}\" class=\"tag\">#{tag}</a></li>"
+    	end
+    else
+    	return "<p>No tags found.</p>"
+    end
+    output += "</ol>"
+  end
+ 
+  desc %{
+    Render a Tag list, more for 'categories'-ish usage, i.e.: Cats (2) Logs (1) ...
+    The results_page attribute will default to #{Radiant::Config['tags.results_page_url']}
+    
+    *Usage:*
+    <pre><code><r:tag_cloud_list [results_page="/some/url"] [scope="/some/url"]/></code></pre>
+  }
+  tag "tag_cloud_list" do |tag|
+    tag_cloud = MetaTag.cloud({:limit => 100}).sort
+    tag_cloud = filter_tags_to_url_scope(tag_cloud, tag.attr['scope']) unless tag.attr['scope'].nil?
+    
+    results_page = tag.attr['results_page'] || Radiant::Config['tags.results_page_url']
+    output = "<ul class=\"tag_list\">"
+    if tag_cloud.length > 0
+        build_tag_cloud(tag_cloud, %w(size1 size2 size3 size4 size5 size6 size7 size8 size9)) do |tag, cloud_class, amount|
+          output += "<li class=\"#{cloud_class}\"><a href=\"#{results_page}/#{tag}\" class=\"tag\">#{tag} (#{amount})</a></li>"
+        end
+    else
+        return "<p>No tags found.</p>"
+    end
+    output += "</ul>"
+  end
+ 
+  desc "List the current page's tags"
+  tag "tag_list" do |tag|
+    results_page = tag.attr['results_page'] || Radiant::Config['tags.results_page_url']
+    output = []
+    tag.locals.page.tag_list.split(MetaTag::DELIMITER).each {|t| output << "<a href=\"#{results_page}/#{t}\" class=\"tag\">#{t}</a>"}
+    output.join ", "
+  end
+  
+  desc "List the current page's tagsi as technorati tags. this should be included in the body of a post or in your rss feed"
+  tag "tag_list_technorati" do |tag|
+    output = []
+    tag.locals.page.tag_list.split(MetaTag::DELIMITER).each {|t| output << "<a href=\"http://technorati.com/tag/#{ t.split(" ").join("+")}\" rel=\"tag\">#{t}</a>"}
+    output.join ", "
+  end
+  
+  tag "tags" do |tag|
+    tag.expand
+  end
+  
+  desc "Iterates over the tags of the current page"
+  tag "tags:each" do |tag|
+    result = []
+    tag.locals.page.meta_tags.each do |meta_tag|
+      tag.locals.meta_tag = meta_tag
+      result << tag.expand
+    end
+    result
+  end
+  
+  tag "tags:each:name" do |tag|
+    tag.locals.meta_tag.name
+  end
+  
+  tag "tags:each:link" do |tag|
+    results_page = tag.attr['results_page'] || Radiant::Config['tags.results_page_url']
+    name = tag.locals.meta_tag.name
+    return "<a href=\"#{results_page}/#{name}\" class=\"tag\">#{name}</a>"
+  end
+
+  desc "Set the scope for all tags in the database"
+  tag "all_tags" do |tag|
+    tag.expand
+  end
+  
+  desc %{
+    Iterates through each tag and allows you to specify the order: by popularity or by name.
+    The default is by name. You may also limit the search; the default is 5 results.
+    
+    Usage: <pre><code><r:all_tags:each order="popularity" limit="5">...</r:all_tags:each></code></pre>
+  }
+  tag "all_tags:each" do |tag|
+    order = tag.attr['order'] || 'name'
+    limit = tag.attr['limit'] || '5'
+    result = []
+    case order
+    when 'name'
+      all_tags = MetaTag.find(:all, :limit => limit)
+    else
+      all_tags = MetaTag.cloud(:limit => limit)
+    end
+    all_tags.each do |t|
+      next if t.pages.empty? # skip unused tags
+      tag.locals.meta_tag = t
+      result << tag.expand
+    end
+    result
+  end
+  
+  desc "Renders the tag's name"
+  tag "all_tags:each:name" do |tag|
+    tag.locals.meta_tag.name
+  end
+  
+  tag "all_tags:each:link" do |tag|
+    results_page = tag.attr['results_page'] || Radiant::Config['tags.results_page_url']
+    name = tag.locals.meta_tag.name
+    return "<a href=\"#{results_page}/#{name}\" class=\"tag\">#{name}</a>"
+  end
+  
+  
+  desc "Set the scope for the tag's pages"
+  tag "all_tags:each:pages" do |tag|
+    tag.expand
+  end
+  
+  desc "Iterates through each page"
+  tag "all_tags:each:pages:each" do |tag|
+    result = []
+    tag.locals.meta_tag.taggables.each do |taggable|
+      if taggable.is_a?(Page)
+        tag.locals.page = taggable
+        result << tag.expand
+      end
+    end
+    result
+  end
+  
+  private
+  
+  def build_tag_cloud(tag_cloud, style_list)
+    max, min = 0, 0
+    tag_cloud.each do |tag|
+      max = tag.popularity.to_i if tag.popularity.to_i > max
+      min = tag.popularity.to_i if tag.popularity.to_i < min
+    end
+    
+    divisor = ((max - min) / style_list.size) + 1
+
+    tag_cloud.each do |tag|
+      yield tag.name, style_list[(tag.popularity.to_i - min) / divisor], tag.popularity.to_i
+    end
+  end
+
+  def tag_item_url(name)
+    "#{Radiant::Config['tags.results_page_url']}/#{name}"
+  end
+  
+  def find_with_tag_options(tag)
+    options = tagged_with_options(tag)
+    with_any = tag.attr['with_any'] || false
+    scope_attr = tag.attr['scope'] || '/'
+    results = []
+    raise TagError, "`tagged' tag must contain a `with' attribute." unless (tag.attr['with'] || tag.locals.page.class_name = TagSearchPage)
+    ttag = tag.attr['with'] || @request.parameters[:tag]
+    
+    scope = scope_attr == 'current_page' ? Page.find_by_url(@request.request_uri) : Page.find_by_url(scope_attr)
+    return "The scope attribute must be a valid url to an existing page." if scope.nil? || scope.class_name.eql?('FileNotFoundPage')
+    
+    if with_any
+      Page.tagged_with_any(ttag, options).each do |page|
+          next unless (page.ancestors.include?(scope) or page == scope)
+          results << page
+      end
+    else
+      Page.tagged_with(ttag, options).each do |page|
+          next unless (page.ancestors.include?(scope) or page == scope)
+          results << page
+      end
+    end
+    results
+  end
+  
+  def tagged_with_options(tag)
+    attr = tag.attr.symbolize_keys
+    
+    options = {}
+    
+    [:limit, :offset].each do |symbol|
+      if number = attr[symbol]
+        if number =~ /^\d{1,4}$/
+          options[symbol] = number.to_i
+        else
+          raise TagError.new("`#{symbol}' attribute of `each' tag must be a positive number between 1 and 4 digits")
+        end
+      end
+    end
+    
+    by = (attr[:by] || 'published_at').strip
+    order = (attr[:order] || 'asc').strip
+    order_string = ''
+    if self.attributes.keys.include?(by)
+      order_string << by
+    else
+      raise TagError.new("`by' attribute of `each' tag must be set to a valid field name")
+    end
+    if order =~ /^(asc|desc)$/i
+      order_string << " #{$1.upcase}"
+    else
+      raise TagError.new(%{`order' attribute of `each' tag must be set to either "asc" or "desc"})
+    end
+    options[:order] = order_string
+    
+    status = (attr[:status] || 'published').downcase
+    exclude = attr[:exclude_id] ? "AND pages.id != #{attr[:exclude_id]}" : ""
+    
+    unless status == 'all'
+      stat = Status[status]
+      unless stat.nil?
+        options[:conditions] = ["(virtual = ?) and (status_id = ?) #{exclude} and (published_at <= ?)", false, stat.id, Time.current]
+      else
+        raise TagError.new(%{`status' attribute of `each' tag must be set to a valid status})
+      end
+    else
+      options[:conditions] = ["virtual = ? #{exclude}", false]
+    end
+    options
+  end
+
+  def filter_tags_to_url_scope(tags, scope)
+    new_tags = []
+    tags.each do |t|
+      catch :record_found do # using fancy ballsports stuff to avoid unnecessary db calls (by calling each page, ànd by calling page.url)
+        t.pages.each do |p|
+          (new_tags << t; throw :record_found) if p.url.include?(scope)
+        end
+      end
+    end
+    new_tags
+  end
+end

data/app/models/tag_search_page.rb

@@ -0,0 +1,87 @@
+class TagSearchPage < Page
+
+  attr_accessor :requested_tag
+  #### Tags ####
+  desc %{    The namespace for all search tags.}
+  tag 'search' do |tag|
+    tag.expand
+  end
+
+  desc %{    Renders the passed query.}
+  tag 'search:query' do |tag|
+    CGI.escapeHTML(requested_tag)
+  end
+  
+  desc %{    Renders the contained block if no results were returned.}
+  tag 'search:empty' do |tag|
+    if found_tags.blank?
+      tag.expand
+    end
+  end
+  
+  desc %{    Renders the contained block if results were returned.}
+  tag 'search:results' do |tag|
+    unless found_tags.blank?
+      tag.expand
+    end
+  end
+
+  desc %{    <r:search:results:each [sort_by="id"] [order="asc"]/>
+    Renders the contained block for each result page.  The context
+    inside the tag refers to the found page. The optional sort_by and order attributes
+    specify how the results are sorted}
+  tag 'search:results:each' do |tag|
+    # Ordering in Ruby because we already fetched our resultset before
+    tags = found_tags
+    tags = tags.sort_by(&tag.attr['sort_by'].to_sym)  if tag.attr['sort_by']
+    tags = tags.reverse                               if tag.attr['order'].to_s =~ /desc/i
+    
+    returning String.new do |content|
+      tags.each do |page|
+        tag.locals.page = page
+        content << tag.expand
+      end
+    end
+  end
+  
+  desc %{    <r:truncate_and_strip [length="100"] />
+    Truncates and strips all HTML tags from the content of the contained block.  
+    Useful for displaying a snippet of a found page.  The optional `length' attribute
+    specifies how many characters to truncate to.}
+  tag 'truncate_and_strip' do |tag|
+    tag.attr['length'] ||= 100
+    length = tag.attr['length'].to_i
+    helper = ActionView::Base.new
+    helper.truncate(helper.strip_tags(tag.expand).gsub(/\s+/," "), length)
+  end
+  
+  #### "Behavior" methods ####
+  def cache?
+    true
+  end
+  
+  def found_tags
+    return @found_tags if @found_tags
+    return []          if requested_tag.blank?
+    
+    @found_tags = Page.tagged_with(requested_tag).delete_if { |p| !p.published? }
+  end
+  
+  def render
+    self.requested_tag = @request.parameters[:tag] unless requested_tag
+    self.title = "Tagged with #{requested_tag}" if requested_tag
+    
+    super
+  end
+
+  def find_by_url(url, live = true, clean = false)
+    url = clean_url(url).chop # chop off trailing slash added by clean_url
+    if url =~ /^#{self.url}([a-zA-Z0-9,\_\-\s\/()'.&]*)\/?$/
+      self.requested_tag = $1
+      self
+    else
+      super
+    end
+  end
+  
+end

data/app/models/tagging.rb

@@ -0,0 +1,10 @@
+class Tagging < ActiveRecord::Base
+  belongs_to :meta_tag 
+  belongs_to :taggable, :polymorphic => true
+  
+  def before_destroy
+    # if all the taggings for a particular <%= parent_association_name -%> are deleted, we want to 
+    # delete the <%= parent_association_name -%> too
+    meta_tag.destroy_without_callbacks if meta_tag.taggings.count < 2
+  end    
+end

data/app/views/admin/help/_using_tags.html.haml

@@ -0,0 +1,4 @@
+%h4 Tags
+%p Tags that you list on your pages are ad-hoc categories and tags that you apply to your pages are as flexible as you want them to be. Rather than selecting a category for your page from a pre-defined list of categories, you can create whatever you need.
+%p Tags are delimited (separated) by a space, so if you want to tag a page with Totally Awesome as one tag, be sure to put it in quotes such as 'Totally Awesome', otherwise you'll create two tags: one called Totally and one called Awesome.
+%p These tags may be used by the site developers to provide a list of links (for example) to a group of pages with the same tag.

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

@@ -0,0 +1,8 @@
+%tr
+  %th.label
+    %label{:for => "page_meta_tags"}
+      Tags
+  %td.field
+    = f.text_field :meta_tags, :value => @page.tag_list, :class => 'textbox'
+    - unless model.errors.on_base.nil?
+      %span.error= model.errors.on_base

data/db/migrate/001_add_tag_support.rb

@@ -0,0 +1,20 @@
+class AddTagSupport < ActiveRecord::Migration
+  def self.up    
+    create_table :meta_tags do |t|
+      t.column :name, :string, :null => false
+    end
+    add_index :meta_tags, :name, :unique => true
+
+    create_table :taggings do |t|
+      t.column :meta_tag_id, :integer, :null => false
+      t.column :taggable_id, :integer, :null => false
+      t.column :taggable_type, :string, :null => false
+    end
+    add_index :taggings, [:meta_tag_id, :taggable_id, :taggable_type], :unique => true
+  end
+
+  def self.down
+    drop_table :meta_tags
+    drop_table :taggings
+  end
+end