radiant-taggable-extension 1.2.5 → 2.0.0.rc1

data/README.md

@@ -1,34 +1,35 @@
 # 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.
+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.
+
+Taggable now includes what was previously the `library` extension so it handles radiant assets as well as pages and provides radius tags to support a faceted search.
 
 ## 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 subvert the keywords mechanism on pages rather than adding another one.
+* It provides faceted search of any tagged class.
+* We subvert the keywords mechanism on pages rather than adding another one. I may change this soon to play more nicely with page fields.
 * The tag-choosing and tag-removal interface is (about to be) quite nice.
 * It's editorially versatile: tags can be used as page pointers and their visibility is controllable
-* 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.
+* 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 `has_tags` at the top of a model class.
 * We don't use `has_many_polymorphs` (it burns!)
 * Or any of the tagging libraries: it only takes a few 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
 
-The long-promised tag-suggester is there in a useable though slightly basic form. I would prefer it to display a list rather than populating
-the text box, but we're getting there. Migration is required for the metaphone support.
+* API change: `has_tags` instead of `is_taggable`.
 
-I'm refactoring, or at least tidying up, the great clutter of tag tags. There's a lot more reuse in there now but the documentation may be out of date here and there. Bug reports very welcome.
+* The library extension has been reincorporated into taggable, since radiant 1 has assets. Out of the box you get tags, clouds and faceting of both pages and assets. It should work with 0.9.1 too but you will need paperclipped.
 
-I've 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.
+* The long-promised tag-suggester is there in a useable though slightly basic form.
 
 ## 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.
+Apart from any crumpling caused by the recent reincorporation of Library this is all mature code that has been in use for years.
 
 ## Efficiency
 
@@ -44,23 +45,32 @@ 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.
 
+## Library pages
+
+The **LibraryPage** page type is a handy cache-friendly way of catching tag parameters and displaying lists of related items: any path following the address of the page is taken as a slash-separated list of tags, so with a tag page at /archive you can call addresses like:
+
+    /archive/lasagne/chips/pudding
+    
+and the right tags will be retrieved, if they exist.
+
 ## Radius tags
 
-This extension creates several radius tags. There are two kinds:
+This extension creates a great many radius tags. There are several kinds:
 
-### presenting tag information
+### 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>
+	<r:tags:each >...</r:tags:each>
 
 currently only available in a tag cloud (or a `top_tags` list):
 
     <r:tag:use_count />
 
-### presenting page information
+### Page tags and tag pages
 
 These display the tag-associations of a given page.
 
@@ -71,7 +81,46 @@ These display the tag-associations of a given page.
     <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.
+
+### Tag assets and asset tags
+
+All the page tags have asset equivalents:
+
+    <r:tags:assets:each tags="foo, bar">...</r:tags:assets:each>
+    <r:related_assets:each>...</r:related_assets:each>
+
+and for any `*asset*` tag you can substitute an asset type, so this also works:
+
+    <r:related_images:each>...</r:related_images:each>
+
+Within the each loops you can use all the usual page and asset tags.
+
+### Library page tags
+
+The library tags focus on two tasks: choosing a set of tags and displaying a set of matching objects.
+
+    <r:library:tags />
+    <r:library:tags:each>...</r:library:tags:each>
+    
+Displays a list of the tags available. If any tags have been requested, this will show the list of coincident tags (that can be used to limit the result set further). If not it shows all the available tags. If a `for` attribute is set:
+
+    <r:library:tags for="images" />
+    <r:library:tags for="pages" />
+
+Then we show only the set of tags attached to any object of that kind.
+
+    <r:library:requested_tags />
+    <r:library:requested_tags:each>...</r:library:requested_tags:each>
     
+Displays the currently-limiting set of tags.
+
+    <r:library:pages:each>...</r:library:pages:each>
+    <r:library:assets:each>...</r:library:assets:each>
+    <r:library:images:each>...</r:library:images:each>
+    <r:library:videos:each>...</r:library:videos:each>
+
+Display the list of (that kind of) objects associated with the current tag set.
+
 ## 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.
@@ -100,16 +149,31 @@ Include the sample tagcloud.css in your styles and put this somewhere in the pag
     <r:tag_cloud />
 
 Seek venture capital immediately.
+
+### To display a faceted image browser on a library page:
+
+    <r:library:if_requested_tags>
+      <p>Displaying pictures tagged with <r:library:requested_tags /></p>
+    </r:library:if_requested_tags>
+    
+    <r:library:images:each paginated="true" per_page="20">
+      <r:assets:link size="full"><r:assets:image size="small" /></r:assets:link>
+    </r:library:images:each>
+
+    <r:library:tags for="images" />
     
-## Next steps
+### To automate the illustration of a page based on tag-overlap:
 
-* auto-completer to improve tagging consistency.
+    <r:related_images:each limit="3">
+      <r:assets:image size="standard" />
+      <p class="caption"><r:assets:caption /></p>
+    </r:related_images:each>
     
 ## Requirements
 
-* Radiant 0.8.1
+* Radiant 1 or radiant 0.9.x with the paperclipped extension. 
 
-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.
+Radiant 1 is strongly recommended.
 
 ## Installation
 
@@ -123,10 +187,10 @@ The update task will bring over a couple of CSS files for styling tags but you'l
 
 ## 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.
+Quite 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 2008-2010 spanner ltd
+* Copyright 2008-2011 spanner ltd
 * released under the same terms as Rails and/or Radiant

data/Rakefile

@@ -1,18 +1,3 @@
-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.

data/app/helpers/taggable_helper.rb

@@ -1,5 +1,23 @@
 module TaggableHelper
 
+  def clean_html(text)
+    Sanitize.clean(text, Sanitize::Config::RELAXED)
+  end
+
+  def strip_html(text)
+    Sanitize.clean(text)
+  end
+
+  def truncate_words(text='', options={})
+    return '' if text.blank?
+    ellipsis = options[:ellipsis] || '…'
+    limit = (options[:limit] || 64).to_i
+    text = strip_html(text) if options[:strip]
+    words = text.split
+    ellipsis = '' unless words.size > limit
+    words[0..(limit-1)].join(" ") + ellipsis
+  end 
+
   def available_pointer_pages()
     root = Page.respond_to?(:homepage) ? Page.homepage : Page.find_by_parent_id(nil)
     options = pointer_option_branch(root)

data/app/models/library_page.rb

@@ -0,0 +1,60 @@
+class LibraryPage < Page
+  include WillPaginate::ViewHelpers
+
+  class RedirectRequired < StandardError
+    def initialize(message = nil); super end
+  end
+
+  description %{ Takes tag names in child position or as paramaters so that tagged items can be listed. }
+  
+  attr_accessor :requested_tags, :strict_match
+  
+  def cache?
+    true
+  end
+  
+  def find_by_url(url, live = true, clean = false)
+    url = clean_url(url) if clean
+    my_url = self.url
+    return false unless url =~ /^#{Regexp.quote(my_url)}(.*)/
+    tags = $1.split('/')
+    if slug_child = children.find_by_slug(tags[0])
+      found = slug_child.find_by_url(url, live, clean)
+      return found if found
+    end
+    remove_tags, add_tags = tags.partition{|t| t.first == '-'}
+    add_request_tags(add_tags)
+    remove_request_tags(remove_tags)
+    self
+  end
+  
+  def add_request_tags(tags=[])
+    if tags.any?
+      tags.collect! { |tag| Tag.find_by_title(Rack::Utils::unescape(tag)) }
+      self.requested_tags = (self.requested_tags + tags.select{|t| !t.nil?}).uniq
+    end
+  end
+  
+  def remove_request_tags(tags=[])
+    if tags.any?
+      tags.collect! { |tag|
+        tag.slice!(0) if tag.first == '-' 
+        Tag.find_by_title(Rack::Utils::unescape(tag)) 
+      }
+      self.requested_tags = (self.requested_tags - tags.select{|t| !t.nil?}).uniq
+    end
+  end
+  
+  def requested_tags
+    @requested_tags ||= []
+  end
+  
+  # this isn't very pleasing but it's the best way to let the controller know 
+  # of our real address once tags have been added and removed.
+  
+  def url_with_tags(tags = requested_tags)
+    clean_url( url_without_tags + '/' + tags.uniq.map(&:clean_title).to_param )
+  end
+  alias_method_chain :url, :tags
+  
+end

data/app/models/tag.rb

@@ -129,12 +129,26 @@ class Tag < ActiveRecord::Base
     taggings.map {|t| t.tagged}
   end
   
-  # Returns a list of all the page tagged with this tag.
+  # Returns a list of all the pages tagged with this tag.
   
   def pages
     Page.from_tags([self])
   end
   
+  # Returns a list of all the assets tagged with this tag.
+  
+  def assets
+    Asset.from_tags([self])
+  end
+  
+  # Returns a list of all the assets of a particular type tagged with this tag.
+  
+  Asset.known_types.each do |type|
+    define_method type.to_s.pluralize.intern do
+      Asset.send("#{type.to_s.pluralize}".intern).from_tags([self])
+    end
+  end
+  
   # Returns a list of all the tags that have been applied alongside this one.
   
   def coincident_tags
@@ -244,10 +258,13 @@ class Tag < ActiveRecord::Base
   # adds retrieval methods for a taggable class to this class and to Tagging.
   
   def self.define_retrieval_methods(classname)
+    define_method "#{classname.downcase}_taggings".to_sym do
+      self.taggings.of_a(classname)
+    end
     define_method classname.downcase.pluralize.to_sym do
       classname.constantize.send :from_tag, self
     end
-  end
+  end  
 
 protected
   

data/app/views/admin/assets/_edit_metadata.html.haml

@@ -0,0 +1,20 @@
+- fields_for :asset, @asset do |fields|
+  #extended-metadata{ :class => "row", :style => "display: none" }
+    %table.fieldset{ :cellpadding => "0", :cellspacing => "0", :border => "0" }
+      %tr
+        %td.label
+          = fields.label :caption
+        %td.field
+          = fields.text_field :caption, :class => 'textbox', :maxlength => 255 
+      -if @asset.new_record? || @asset.image?
+        %tr
+          %td.label
+            Display
+          %td.field{:style => 'text-align: left;'}
+            = fields.check_box :furniture
+            = fields.label :furniture, "Site furniture? (not shown in lists and galleries)"
+      = render_region :extended_metadata
+  %p
+    %small
+      %a{ :id => "more-extended-metadata", :href => "#", :onclick => "#{toggle_javascript_for('extended-metadata')}; return false;" } More
+      %a{ :id => "less-extended-metadata", :href => "#", :onclick => "#{toggle_javascript_for('extended-metadata')}; return false;", :style => "display: none" } Less

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

@@ -0,0 +1,14 @@
+- include_stylesheet 'admin/taggable'
+- include_javascript 'autocomplete'
+- include_javascript 'admin/taggable'
+
+- fields_for :asset, @asset do |fields|
+  %p.keywords
+    %label{:for=>"asset_keywords"}
+      Tags
+    = fields.text_field :keywords, :class => 'textbox tagger'
+
+  %p.title
+    %label{:for=>"asset_title"}
+      Title
+    = fields.text_field :title, :class => 'textbox', :maxlength => 100

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

@@ -0,0 +1,22 @@
+- include_stylesheet 'admin/assets' 
+
+- asset_taggings = @tag.taggings.of_a :asset
+- if asset_taggings.any?
+  %h2
+    Tagged assets
+  %table.index
+    - asset_taggings.each do |tagging|
+      - asset = tagging.tagged
+      - if asset
+        - dom_id = "tagging_#{tagging.id}"
+        %tr{:id => dom_id}
+          %td.asset{:style => 'width: 48px'}
+            = link_to image_tag(asset.thumbnail(:icon)), edit_admin_asset_path(asset), :class => 'icon'
+          %td.asset-title
+            = link_to asset.title, edit_admin_asset_path(asset) 
+          %td.actions
+            = link_to_remote image('minus') + ' detach', |
+              :html => { :class => "action", :title => "Detach tag from asset" }, |
+              :url => admin_tagging_url(tagging), :method => :delete, |
+              :after => "Effect.Fade('#{dom_id}', { duration: 0.5 })", |
+              :complete => "Element.remove('#{dom_id}');"

data/lib/link_renderer.rb

@@ -0,0 +1,22 @@
+# This handy simplification is adapted from SphinxSearch (thanks)
+# and originally came from Ultrasphinx
+# it saves us a lot of including and bodging to make will_paginate's template calls work in the Page model
+
+module Library
+  class LinkRenderer < WillPaginate::LinkRenderer
+    def initialize(tag)
+      @tag = tag
+    end
+  
+    def page_link(page, text, attributes = {})
+      linkclass = %{ class="#{attributes[:class]}"} if attributes[:class]
+      linkrel = %{ rel="#{attributes[:rel]}"} if attributes[:rel]
+      %Q{<a href="#{@tag.locals.page.url}?page=#{page}"#{linkrel}#{linkclass}>#{text}</a>}
+    end
+
+    def page_span(page, text, attributes = {})
+      spanclass = attributes[:class]
+      %{<span class="#{attributes[:class]}">#{text}</span>}
+    end
+  end
+end

data/lib/radiant-taggable-extension.rb

@@ -0,0 +1,8 @@
+module RadiantTaggableExtension
+  VERSION = '2.0.0.rc1'
+  SUMMARY = %q{Tagging, clouding and faceting extension for Radiant CMS}
+  DESCRIPTION = %q{General purpose tagging and retrieval extension: more versatile but less focused than the tags extension. A good way to support faceted search.}
+  URL = "http://spanner.org/radiant/taggable"
+  AUTHORS = ["William Ross"]
+  EMAIL = ["radiant@spanner.org"]
+end

data/lib/radius/asset_tags.rb

@@ -0,0 +1,151 @@
+module Radius
+  module AssetTags
+    include Radiant::Taggable
+  
+    class TagError < StandardError; end
+
+    %w{tags tags:each copyright if_copyright unless_copyright minigallery illustration}.each do |name|
+      deprecated_tag "assets:#{name}", :substitute => "asset:#{name}", :deadline => '2.0'
+    end
+
+
+    ############### assets: tags for displaying tags and relatives when we have an asset
+                  # similar tags already exist for pages
+  
+    desc %{
+      Cycles through all tags attached to present asset.
+    
+      *Usage:* 
+      <pre><code><r:assets:tags><r:tag:title /></r:assets:tags></code></pre>
+    }    
+    tag 'asset:tags' do |tag|
+      raise TagError, "asset must be defined for asset:tags tag" unless tag.locals.asset
+      tag.locals.tags = tag.locals.asset.tags
+      tag.expand
+    end
+    tag 'asset:tags:each' do |tag|
+      tag.render('tags:each', tag.attr.dup, &tag.block)
+    end
+
+    desc %{
+      Lists all the assets similar to this asset (based on its tagging), in descending order of relatedness.
+    
+      *Usage:* 
+      <pre><code><r:related_assets:each>...</r:related_assets:each></code></pre>
+    }
+    tag 'related_assets' do |tag|
+      raise TagError, "asset must be defined for related_assets tag" unless tag.locals.asset
+      tag.locals.assets = tag.locals.asset.related_assets
+      tag.expand
+    end
+    tag 'related_assets:each' do |tag|
+      tag.render('assets:each', tag.attr.dup, &tag.block)
+    end
+
+    ############### extra asset fields
+
+    desc %{
+      Expands if the asset has a copyright notice.
+    }
+    tag "asset:if_copyright" do |tag|
+      options = tag.attr.dup
+      asset = find_asset(tag, options)
+      tag.expand if asset.respond_to?(method) && asset.send(method)
+    end
+    
+    desc %{
+      Expands unless the asset has a copyright notice.
+    }
+    tag "asset:unless_copyright" do |tag|
+      options = tag.attr.dup
+      asset = find_asset(tag, options)
+      tag.expand unless asset.respond_to?(method) && asset.send(method)
+    end
+
+    desc %{
+      Renders the 'copyright' attribute of the asset.
+    }
+    tag "asset:copyright" do |tag|
+      options = tag.attr.dup
+      asset = find_asset(tag, options)
+      asset.send(method) rescue nil
+    end
+
+    ############### useful shorthands
+
+    desc %{
+      Renders an illustration block for the asset, with image and caption.
+
+      *Usage:* 
+      <pre><code><r:assets:image [title="asset_title"] [size="icon|thumbnail"]></code></pre>
+    }    
+    tag "asset:illustration" do |tag|
+      options = tag.attr.dup
+      options['size'] ||= 'illustration'
+      tag.locals.asset = find_asset(tag, options)
+      if tag.locals.asset.image?
+        result = %{<div class="illustration">}
+        result << tag.render('assets:image', options)
+        result << %{<p class="caption">#{tag.render('assets:caption', options)}</p>}
+        result << "</div>"
+        result
+      end
+    end
+    
+    desc %{ 
+      Presents a standard marginal gallery block suitable for turning unobtrusively into a rollover or lightbox gallery. 
+      We need to be able to work out a collection of assets: that can be defined already (eg by assets:all) or come from the current page.
+      Default preview size is 'large' and thumbnail size 'thumbnail' but you can specify any of your asset sizes.
+
+      *Usage:*
+      <pre><code>
+        <r:assets:images>
+          <r:assets:minigallery [size="..."] [thumbnail_size="..."] [tags="one,or,more,tags"] />
+        </r:assets:images>
+      </code></pre>
+
+    }
+    tag 'asset:minigallery' do |tag|
+      options = tag.attr.dup.symbolize_keys
+      raise TagError, "asset collection must be available for assets:minigallery tag" unless tag.locals.assets or tag.locals.page or tag.attr[:tags]
+      if options[:tags] && tags = Tag.from_list(options[:tags])
+        tag.locals.assets = Asset.images.from_all_tags(tags)
+      else
+        tag.locals.assets = tag.locals.page.assets
+      end
+      tag.locals.assets.images.to_a     # because we can't let empty? trigger a call to count
+
+      unless tag.locals.assets.empty?
+        size = tag.attr['size'] || 'illustration'
+        thumbsize = tag.attr['thumbnail_size'] || 'icon'
+        result = ""
+        result << %{
+  <div class="minigallery">}
+        tag.locals.asset = tag.locals.assets.first
+        result << tag.render('assets:image', {'size' => size})
+        result << %{
+    <p class="caption">#{tag.render('assets:caption')}</p>
+    <ul class="thumbnails">}
+        if tag.locals.assets.size > 1
+          tag.locals.assets.each do |asset|
+            tag.locals.asset = asset
+            result << %{
+      <li class="thumbnail">
+        <a href="#{tag.render('assets:url', 'size' => 'illustration')}" title="#{asset.caption}" id="thumbnail_#{asset.id}">
+          }
+            result << tag.render('assets:image', {'size' => thumbsize, 'alt' => asset.title})
+            result << %{
+        </a>
+      </li>}
+          end
+        end
+        result << %{
+    </ul>
+  </div>}
+        result
+      end
+    end
+
+  end
+end
+