radiant-page_attachments-extension 1.0.0

data/.gitignore

@@ -0,0 +1,5 @@
+.svn
+.DS_Store
+coverage
+rdoc
+pkg

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Sean Cribbs
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,129 @@
+Page Attachments
+===
+
+About
+---
+
+A [Radiant][rd] Extension by [Sean Cribbs][sc] that adds page-attachment-style asset management.  Page Attachments adds support for file uploads realized as attachments to individual pages.  Attachments can have an order via acts_as_list, a title, a description and various metadata fields as provided by AttachmentFu.
+
+Installation
+---
+
+If you want `page_attachments` to generate and display thumbnails of your uploaded images you'll first need to install one of, [`image_science`][is], [`mini-magick`][mm] or [`rmagick`][rm] on your server. This is completely optional, `page_attachments` will still function in every other way without any of these packages installed.
+
+Now you're ready to install `page_attachments`.
+
+    cd /path/to/radiant
+    git clone git://github.com/radiant/radiant-page-attachments-extension.git vendor/extensions/page_attachments
+    rake radiant:extensions:page_attachments:migrate
+    rake radiant:extensions:page_attachments:update
+
+If you don't have `git` you can [download a tarball][pa].
+
+Attachment thumbnails for images default to `:icon => '50x50>'`. You can customize that by setting
+`PAGE_ATTACHMENT_SIZES` to whatever you need in your `config/environment.rb` file
+
+    PAGE_ATTACHMENT_SIZES = {:thumb => '120x120>', :normal => '640x480>'}
+
+Restart your server and refresh the admin interface.
+
+Running features and specs
+---
+The Cucumber features use Webrat and Selenium.  You'll need the webrat 0.5.1 and selenium-client 1.2.16 gems installed and you'll need to change the version of webrat specified in environments/test.rb.
+
+Managing Attachments
+---
+
+Now when you login and edit a page, you'll find the "Attachments" interface below the text editing area. To add a new attachment to the page click the **+** icon. If you need to you can upload multiple attachments at once by clicking the **+** icon once for each attachment you'll be adding. Attachments are **not** added or deleted until the page is saved. Therefore, if you accidentally deleted something you meant to keep, simply cancel the page edit.
+
+Usage
+---
+
+* See the "available tags" documentation built into the Radiant page admin for more details.
+* Reference an attachment by name `<r:attachment name="file.txt">...</r:attachment>`
+* Display an attachment's URL `<r:attachment:url name="file.jpg"/>`
+* Display an attachment's `#{key}` attribute `<r:attachment:#{key} name="file.jpg"/>`
+* Display the date an attachment was added `<r:attachment:date name="file.txt"/>`
+* Display an attached image `<r:attachment:image name="file.jpg"/>`
+* Display a link to an attachment `<r:attachment:link name="file.jpg"/>` or `<r:attachment:link name="file.jpg">Click Here</r:attachment:link>`
+* Display name of the user who added the attachment `<r:attachment:author name="file.jpg"/>`
+* Iterate through all the attachments on a page `<r:attachment:each><r:link/></r:attachment:each>`
+* Display the extension of an attachement inside iterations with <r:attachment:extension/>
+
+Troubleshooting
+---
+
+If you have a problem running the migrate task, and it fails with an error something like this:
+
+    ld: library not found for -lfreeimage
+    collect2: ld returned 1 exit status
+
+It means you have installed the ImageScience gem but you don't have FreeImage installed. So, either install FreeImage or uninstall the gem with
+
+    gem uninstall image_science
+
+---
+
+If you're using ImageScience as a user without a home directory, you may see this error:
+
+    Define INLINEDIR or HOME in your environment and try again
+
+This is caused by RubyInline not having a place to store its generated files and can be easily fixed by specifying a path in your environment file like so:
+
+    ENV['INLINEDIR'] = File.join(RAILS_ROOT,'tmp','ruby_inline')
+
+---
+
+If you have trouble attaching files to Page Types other than the normal type, try editing the following line in your `config/environment.rb` file
+
+		config.extensions = [ :all ]
+
+to look like
+
+		config.extensions = [ :page_attachments, :all ]
+
+Amazon S3 for Attachment storage
+---
+
+Since `page_attachments` uses `attachment_fu` for the handling of attachments it's just as easy to use [S3][s3] as it is to use your hard drive. Before you get started with this there are a few things to keep in mind:
+
+* If you've already started storing attachments on your hard drive **this will break** any `<r:attachment...>` tags pointing to those files. You'll need to remove all existing attachments and re-add them to Amazon S3.
+* You have to install the `AWS::S3` gem. In some shared hosting environments this might not be possible.
+* The `AWS::S3` gem does not (currently) support EU buckets, so if that's all you have you'll need to create a bucket in the US.
+
+Before you start make sure you have `page_attachments` working using your hard drive. Once you've tested an upload or two to the hard drive and feel confident the basic setup is working, dive right in.
+
+1. `gem install aws-s3`
+2. `cd /path/to/radiant`
+3. `cp vendor/plugins/attachment_fu/amazon_s3.yml.tpl config/amazon_s3.yml`
+4. edit `config/amazon_s3.yml` with your S3 credentials
+5. `cp vendor/extensions/page_attachments/app/models/page_attachment.rb vendor/extensions/page_attachments/app/models/page_attachment.rb.bak`
+6. edit line 2 of `vendor/extensions/page_attachments/app/models/page_attachment.rb` changing `:file_system` to `:s3`
+7. restart your server
+
+Add an attachment and make sure the link it gives back is on S3. You should see all your attachments start showing up at `http://s3.amazonaws.com/bucket-name/page_attachments/`. While it is possible to customize the URL to Amazon (i.e. http://attachments.your-domain.com/) but it's beyond the scope of this document and a task best left for those that really need custom URLs.
+
+Contributors
+---
+
+These people have contributed patches that have been added to the extension:
+
+* [John Muhl][jm]
+* [Daniel Collis-Puro][djcp]
+* [James Burka][jb]
+* [Istvan Hoka][ihoka]
+* [Oleg Ivanov][oleg]
+
+[rd]: http://radiantcms.org/
+[sc]: http://seancribbs.com/
+[is]: http://seattlerb.rubyforge.org/ImageScience.html
+[mm]: http://rubyforge.org/projects/mini-magick/
+[rm]: http://rmagick.rubyforge.org/
+[af]: http://github.com/technoweenie/attachment_fu/tarball/master
+[pa]: http://github.com/radiant/radiant-page-attachments-extension/tarball/master
+[s3]: http://www.amazon.com/gp/browse.html?node=16427261
+[jm]: http://github.com/johnmuhl
+[djcp]: http://www.kookdujour.com/
+[jb]: http://github.com/jjburka
+[ihoka]: http://github.com/ihoka
+[oleg]: http://github.com/morhekil

data/Rakefile

@@ -0,0 +1,57 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "radiant-page_attachments-extension"
+    gem.summary = %Q{Adds page-attachment-style asset management.}
+    gem.description = %Q{Page Attachments adds support for file uploads realized as attachments to individual pages. Attachments can have an order via acts_as_list, a title, a description and various metadata fields as provided by AttachmentFu.}
+    gem.email = "radiant@radiantcms.org"
+    gem.homepage = "http://github.com/radiant/radiant-page-attachments-extension"
+    gem.authors = ["Sean Cribbs"]
+    gem.add_development_dependency "rspec"
+    gem.add_development_dependency "cucumber"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :spec => :check_dependencies
+
+begin
+  require 'cucumber/rake/task'
+  Cucumber::Rake::Task.new(:features)
+
+  task :features => :check_dependencies
+rescue LoadError
+  task :features do
+    abort "Cucumber is not available. In order to run features, you must: sudo gem install cucumber"
+  end
+end
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "radiant-page_attachments-extension #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/app/models/observe_page_attachments.rb

@@ -0,0 +1,5 @@
+module ObservePageAttachments
+  def self.included(base)
+    base.send :observe, User, Page, Layout, Snippet, PageAttachment
+  end
+end

data/app/models/page_attachment.rb

@@ -0,0 +1,28 @@
+class PageAttachment < ActiveRecord::Base
+  acts_as_list :scope => :page_id
+  has_attachment :storage => :file_system,
+                 :thumbnails => defined?(PAGE_ATTACHMENT_SIZES) && PAGE_ATTACHMENT_SIZES || {:icon => '50x50>'},
+                 :max_size => 10.megabytes
+  validates_as_attachment
+
+  belongs_to :created_by,
+             :class_name => 'User',
+             :foreign_key => 'created_by'
+  belongs_to :updated_by,
+             :class_name => 'User',
+             :foreign_key => 'updated_by'
+  belongs_to :page
+
+  def short_filename(wanted_length = 15, suffix = ' ...')
+          (self.filename.length > wanted_length) ? (self.filename[0,(wanted_length - suffix.length)] + suffix) : self.filename
+  end
+
+  def short_title(wanted_length = 15, suffix = ' ...')
+          (self.title.length > wanted_length) ? (self.title[0,(wanted_length - suffix.length)] + suffix) : self.title
+  end
+
+  def short_description(wanted_length = 15, suffix = ' ...')
+          (self.description.length > wanted_length) ? (self.description[0,(wanted_length - suffix.length)] + suffix) : self.description
+  end
+
+end

data/app/models/page_attachment_associations.rb

@@ -0,0 +1,20 @@
+module PageAttachmentAssociations
+  def self.included(base)
+    base.class_eval {
+      has_many :attachments,
+               :class_name => "PageAttachment",
+               :dependent => :destroy,
+               :order => 'position'
+      include InstanceMethods
+      accepts_nested_attributes_for :attachments, :allow_destroy => true
+    }
+  end
+
+  module InstanceMethods
+    # Currently recursive, but could be simplified with some SQL
+    def attachment(name)
+      att = attachments.find(:first, :conditions => ["filename LIKE ?", name.to_s])
+      att.blank? ? ((parent.attachment(name) if parent) or nil) : att
+    end
+  end
+end

data/app/models/page_attachment_tags.rb

@@ -0,0 +1,261 @@
+module PageAttachmentTags
+  include Radiant::Taggable
+
+  class TagError < StandardError; end
+
+  desc %{
+    The namespace for referencing page attachments/files.  You may specify the 'name'
+    attribute (for the filename) on this tag for all contained tags to refer to that attachment.
+    Attachments can be inherited from parent pages.
+
+    *Usage*:
+
+    <pre><code><r:attachment name="file.txt">...</r:attachment></code></pre>
+  }
+  tag "attachment" do |tag|
+    page = tag.locals.page
+    tag.locals.attachment = page.attachment(tag.attr['name']) rescue nil if tag.attr['name']
+    tag.expand
+  end
+
+  desc %{
+    Renders the url or public filename of the attachment for use in links, stylesheets, etc.
+    The 'name' attribute is required on this tag or the parent tag.  The optional 'size' attribute
+    applies only to images.
+
+    *Usage*:
+
+    <pre><code><r:attachment:url name="file.jpg" [size="icon"]/></code></pre>
+  }
+  tag "attachment:url" do |tag|
+    raise TagError, "'name' attribute required" unless name = tag.attr['name'] or tag.locals.attachment
+    page = tag.locals.page
+    size = tag.attr['size'] || nil
+    attachment = tag.locals.attachment || page.attachment(name)
+    attachment.public_filename(size)
+  end
+
+  [:short_title,:short_description,:short_filename].each do |key|
+  desc %{
+  Renders the '#{key}' attribute of the attachment.
+  The 'name' attribute is required on this tag or the parent tag.
+  The optional 'length' attribute defines how many characters of the attribute to display. It defaults to 15 total characters, including the 'suffix'.
+  If the attribute exceeds 'length', 'suffix' says what to tag onto the back to show truncation. It defaults to ' ...'
+
+        *Usage*:
+
+    <pre><code><r:attachment:#{key} name="file.jpg" [length="number of characters"] [suffix="More . . ."]/></code></pre>
+  }
+    tag "attachment:#{key}" do |tag|
+      raise TagError, "'name' attribute required" unless name = tag.attr['name'] or tag.locals.attachment
+      page = tag.locals.page
+      attachment = tag.locals.attachment || page.attachment(name)
+          tlength = (tag.attr['length']) ? tag.attr['length'].to_i : 15
+          suffix = (tag.attr['suffix']) ? tag.attr['suffix'].to_s : ' ...'
+      attachment.send("#{key}",tlength,suffix)
+    end
+  end
+
+  desc %{
+  Renders the 'size' attribute of the attachment.
+  The 'name' attribute is required on this tag or the parent tag. Returns bytes by default. Use the optional 'units' parameter to change the units this tag returns.
+
+        *Usage*:
+
+    <pre><code><r:attachment:size name="file.jpg" [units="bytes|kilobytes|megabytes|gigabytes"] /></code></pre>
+ }
+  tag "attachment:size" do |tag|
+      raise TagError, "'name' attribute required" unless name = tag.attr['name'] or tag.locals.attachment
+      page = tag.locals.page
+      attachment = tag.locals.attachment || page.attachment(name)
+          units = tag.attr['units'] || 'bytes'
+          valid_units = ['bytes','byte','kilobytes','kilobyte','megabytes','megabyte','gigabytes','gigabyte']
+          units = (valid_units.include?(units)) ? units : 'bytes'
+          return attachment.size if units == 'bytes'
+      sprintf('%.2f',(attachment.size.to_f / 1.send(units)))
+  end
+
+
+  [:content_type, :width, :height, :title, :description, :position, :filename].each do |key|
+    desc %{
+      Renders the '#{key}' attribute of the attachment.
+      The 'name' attribute is required on this tag or the parent tag.  The optional 'size'
+      attributes applies only to images.
+
+    *Usage*:
+
+    <pre><code><r:attachment:#{key} name="file.jpg" [size="icon"]/></code></pre>
+    }
+    tag "attachment:#{key}" do |tag|
+      raise TagError, "'name' attribute required" unless name = tag.attr['name'] or tag.locals.attachment
+      page = tag.locals.page
+      attachment = tag.locals.attachment || page.attachment(name)
+      attachment.attributes["#{key}"]
+    end
+  end
+
+  desc %{
+    Renders the date the attachment was uploaded using the specified 'format' (Ruby's strftime syntax).
+    The 'name' attribute is required on this tag or the parent tag.
+  }
+  tag "attachment:date" do |tag|
+    raise TagError, "'name' attribute required" unless name = tag.attr['name'] or tag.locals.attachment
+    page = tag.locals.page
+    attachment = tag.locals.attachment || page.attachment(name)
+    format = tag.attr['format'] || "%F"
+    attachment.created_at.strftime(format)
+  end
+
+  desc %{
+    Renders an image tag for the attachment (assuming it's an image).
+    The 'name' attribute is required on this tag or the parent tag.
+    Any other attributes will be added as HTML attributes to the rendered tag.
+    The optional 'size' attribute allows you to show the icon size of the image.
+
+    *Usage*:
+
+    <pre><code><r:attachment:image name="file.jpg" [size="icon"]/></code></pre>
+
+    }
+  tag "attachment:image" do |tag|
+    raise TagError, "'name' attribute required" unless name = tag.attr.delete('name') or tag.locals.attachment
+    page = tag.locals.page
+    attachment = tag.locals.attachment || page.attachment(name)
+    size = tag.attr['size'] || nil
+    raise TagError, "attachment is not an image." unless attachment.content_type.strip =~ /^image\//
+    filename = attachment.public_filename(size) rescue ""
+    attributes = tag.attr.inject([]){ |a,(k,v)| a << %{#{k}="#{v}"} }.join(" ").strip
+    %{<img src="#{filename}" #{attributes + " " unless attributes.empty?}/>}
+  end
+
+  desc %{
+    Renders a hyperlink to the attachment. The 'name' attribute is required on this tag or the parent tag.
+    You can use the 'label' attribute to specify the textual contents of the tag.  Any other attributes
+    will be added as HTML attributes to the rendered tag.  This tag works as both a singleton and a container.
+    Any contained content will be rendered inside the resulting link.  The optional 'size' attribute applies only to images.
+
+    *Usage*:
+
+    <pre><code><r:attachment:link name="file.jpg" [size="thumbnail"]/></code></pre>
+    <pre><code><r:attachment:link name="file.jpg" [size="thumbnail"]> Some text in the link </r:attachment:link></code></pre>
+  }
+  tag "attachment:link" do |tag|
+    raise TagError, "'name' attribute required" unless name = tag.attr.delete('name') or tag.locals.attachment
+    page = tag.locals.page
+    attachment = tag.locals.attachment || page.attachment(name)
+    label = tag.attr.delete('label') || attachment.filename
+    size = tag.attr.delete('size') || nil
+    filename = attachment.public_filename(size) rescue ""
+    attributes = tag.attr.inject([]){ |a,(k,v)| a << %{#{k}="#{v}"} }.join(" ").strip
+    output = %{<a href="#{filename}"#{" " + attributes unless attributes.empty?}>}
+    output << (tag.double? ? tag.expand : label)
+    output << "</a>"
+  end
+
+  desc %{
+    Renders the name of who uploaded the attachment. The 'name' attribute is required on this tag or the parent tag.
+
+    *Usage*:
+
+    <pre><code><r:attachment:author name="file.jpg" /></code></pre>
+  }
+  tag "attachment:author" do |tag|
+    raise TagError, "'name' attribute required" unless name = tag.attr.delete('name') or tag.locals.attachment
+    page = tag.locals.page
+    attachment = tag.locals.attachment || page.attachment(name)
+    if attachment and author = attachment.created_by
+      author.name
+    end
+  end
+
+  desc %{
+    Iterates through all the attachments in the current page.  The 'name' attribute is not required
+    on any nested attachment tags.
+
+    *Usage*:
+
+    <pre><code><r:attachment:each [order="asc|desc"] [by="filename|size|created_at|..."] [limit=0] [offset=0] [extensions="png|pdf|doc"]>
+        <r:link /> - <r:date>
+    </r:attachment:each></code></pre>
+  }
+  tag "attachment:each" do |tag|
+    page = tag.locals.page
+
+    returning String.new do |output|
+      page.attachments.find(:all, attachments_find_options(tag)).each do |att|
+        tag.locals.attachment = att
+        output << tag.expand
+      end
+    end
+  end
+
+  desc %{
+    Renders the contained elements only if the current contextual page has one or
+    more attachments. The @min_count@ attribute specifies the minimum number of required
+    attachments. You can also filter by extensions with the @extensions@ attribute.
+
+    *Usage:*
+    <pre><code><r:if_attachments [min_count="n"] [extensions="doc|pdf"]>...</r:if_attachments></code></pre>
+  }
+  tag "if_attachments" do |tag|
+    count = tag.attr['min_count'] && tag.attr['min_count'].to_i || 0
+    attachments = tag.locals.page.attachments.count(:conditions => attachments_find_options(tag)[:conditions])
+    tag.expand if attachments >= count
+  end
+
+  desc %{
+    Renders the contained elements only if the current contextual page has no attachments.
+
+    *Usage:*
+    <pre><code><r:unless_attachments>...</r:unless_attachments></code></pre>
+  }
+  tag "unless_attachments" do |tag|
+    count = tag.attr[''].to_i
+    attachments = tag.locals.page.attachments.count(:conditions => attachments_find_options(tag)[:conditions])
+    tag.expand if attachments == 0
+  end
+
+  desc %{
+    Renders the 'extension' virtual attribute of the attachment, extracted from filename.
+
+  *Usage*:
+
+<pre><code>
+<ul>
+  <r:attachment:each extensions="doc|pdf">
+    <li class="<r:extension/>">
+      <r:link/>
+    </li>
+  </r:attachment:each>
+</ul>
+</code></pre>
+  }
+  tag "attachment:extension" do |tag|
+    raise TagError, "must be nested inside an attachment or attachment:each tag" unless tag.locals.attachment
+    attachment = tag.locals.attachment
+    attachment.filename[/\.(\w+)$/, 1]
+  end
+
+  private
+    def attachments_find_options(tag)
+      attr = tag.attr.symbolize_keys
+
+      extensions = attr[:extensions] && attr[:extensions].split('|') || []
+      conditions = unless extensions.blank?
+        [ extensions.map { |ext| "page_attachments.filename LIKE ?"}.join(' OR '),
+          *extensions.map { |ext| "%.#{ext}" } ]
+      else
+        nil
+      end
+
+      by = attr[:by] || "position"
+      order = attr[:order] || "asc"
+
+      options = {
+        :order => "#{by} #{order}",
+        :offset => attr[:offset] || nil,
+        :limit => attr[:limit] || (attr[:offset] ? 9999 : nil),
+        :conditions => conditions
+      }
+    end
+end