radiant-forum-extension 0.6.0

data/README.md

@@ -0,0 +1,155 @@
+# Forum
+
+This is a simple but comprehensive forum implementation that plugs into radiant. It's fairly well-featured, including:
+
+* forums, topics, posts etc
+* page comments
+* simple but effective forum search
+* rss feeds of pretty much anything (including search queries and individual authors)
+* textile-formatted messages with html sanitized
+* smilies :(
+* multiple message attachments and helpful image-handling
+* configurable message-editing interval during which authors can make corrections
+
+I've tried to keep it simple and tidy both inside and out. This is helped by the fact that all the user-management is in the reader extension, so you should find this one easy to adapt and extend. 
+
+The forum was derived long ago from [Beast](http://beast.caboo.se) and the fossilised bones will still be visible here and there. It has been in use on various sites in various versions for three years, but in making it ready for publication I've pretty much refactored the whole thing and probably optimised new bugs into it. Please let me know as soon as you spot one.
+
+## Status
+
+Mature and stable, but I'm a bit habitual with it so may have overlooked some rough edges in parts of the interface I don't visit much. It would benefit from wider use. 
+
+There's a lot going on here and plenty of places for me to hide bugs, but the tests are fairly thorough.
+
+## Latest
+
+* Quite a lot of tidying up and trimming of the interface
+* sample javascripts and layout updated
+* Updated for 0.8.1 with gem and extension dependencies, and many small fixes to keep up with the `reader` and `group_forum` extensions.
+
+## Still to do
+
+* Moderators among readership
+* Reinstate message preview
+* Reinstate email-monitoring
+* Message-problem button
+* Admin pages that are less crappy
+* Anonymous page-comment option
+
+## Requirements
+
+Radiant 0.8.1 (we're using the new config machinery) with the [reader](http://github.com/spanner/radiant-reader-extension) extension. Reader has a few requirements of its own so it's best to install that one first, make sure it's testing clean and then install the forum.
+
+We also require [will_paginate](http://github.com/mislav/will_paginate/) and [paperclip](http://github.com/thoughtbot/paperclip/) as gems. The latter is for post attachments, and if you're using [paperclipped](http://github.com/kbingman/paperclipped) (which vendors paperclip) then you can probably skip it. Otherwise:
+
+	sudo rake gems:install
+	
+should get everything you need. 
+
+The forum is compatible with multi_site but you have to use [sites](https://github.com/spanner/radiant-sites-extension) instead if you want forums and readers site-scoped.
+
+## Installation
+
+The usual:
+
+	git submodule add git://github.com/spanner/radiant-forum-extension.git vendor/extensions/forum
+
+Check the extension loading order in environment.rb (you will need `share_layouts`, `reader` and perhaps `multi_site` to load before this one) and then:
+
+	rake radiant:extensions:forum:migrate
+	rake radiant:extensions:forum:update
+
+As well as the basic machinery this should give you:
+
+* a basic forum.css that you will want to improve upon,
+* an admin/forum.css that you can probably leave alone, 
+* a sample layout that should be enough to let you experiment
+	
+## Administration
+
+The forum is easy to use and almost entirely separate from your page hierarchy. Forums - which are described as 'discussion categories' most of the time and not emphasised much in the reader-facing pages - are created and edited in the admin interface, and there readers can also (soon) be promoted to moderate selected forums. Everything else is done through the reader interface including the editing and deletion of posts and topics.
+
+## Configuration
+
+A few config options can be set:
+
+* `forum.layout` should be the name of the layout you want to use for reader-facing forum pages. See below for more detail.
+* `forum.default_forum` is the name of the forum that will be selected by default in the new-message form
+* `forum.editable_period` is the number of minutes for which posts remain editable by their authors once they have been submitted
+
+## Layouts
+
+We use `share_layouts` to present your forum pages inside the radiant layout of your choice. Set the config option 'forum.layout' to the name of the layout you want to use (or see below for multi_site instructions). Your layout can work in the usual way: all we do is define page parts for you to include with `<r:content part="something" />`. These are the parts available:
+
+* the main page content (that you get with a bare `<r:content />`) gives you the main list, object or form.
+* 'pagetitle' will be the main page heading (eg the name of the topic): `<r:content part="pagetitle" />`
+* 'breadcrumbs' is what you'd expect: usually something simple like Forum > Category name
+* 'breadhead' is an up-one-level link that you may want to include in the page header
+* 'feed' is an icon link to the RSS feed for whatever you are currently looking at (and works for most things including searches, of which more below)
+* 'mugshot' is a gravatar for the author of this topic or post
+* 'credits' is the authorship summary for this topic or post
+
+These parts are only defined where they're relevent, so you can do something like this:
+
+	<h1 class="pagetitle">
+	  <r:content part="mugshot" />
+	  <r:content part="breadhead" />
+	  <r:content part="pagetitle" />
+	  <r:content part="feed" />
+	</h1>
+
+and it will look right for all the forum pages. 
+
+You probably also want to include this somewhere, as on all reader-service pages:
+
+	<r:if_reader><r:reader:controls /></r:if_reader>
+
+Have a look at the included sample layout for a starting point.
+
+## Multi_site
+
+The forum is fine under multi_site. If you use [our version](http://github.com/spanner/radiant-multi-site-extension) then everything will be site-scoped for you. In that case, the forum layout is chosen for each site using a dropdown on the (currently extremely scruffy) site-editing page. Everything else works in just the same way and you should be able to run several forums next to each other without problems.
+
+## Private discussion
+
+If you install the [reader_group](http://github.com/spanner/radiant-reader_group-extension) and [group_forum](http://github.com/spanner/radiant-group_forum-extension) extensions then your forums can be made visible only to designated groups, as with pages and other groupable items.
+
+## Searching the forum
+
+The forum has its own simple search mechanism. It's not very bright but it has two great advantages: you can combine text search with filtering by author and category, and you can bookmark any search query as an RSS feed to be alerted when new posts match that search. There are arguments for integrating this with eg `sphinx_search` but at the moment I quite like keeping them separate: I find that searching for messages is not the same as searching for pages, but usually a different group seeking different results. Let me know if you disagree.
+
+To enable the search, you can either link to `/forum/posts/search` or put `<r:forum_search>` somewhere in your forum layout. See the tag documentation for control of the search form presentation.
+
+## Page Comments
+
+To enable page comments, all you have to do is put `<r:comments:all />` somewhere in the layout (or in a snippet or on an individual page). Behind the scenes this will create a dedicated forum for page comments and a topic for each page as it is commented upon. The rest of the mechanism is the same, and the comments themselves are just posts. 
+
+The page cache means we don't want anything personal on the page itself - no edit controls or logout buttons - but there are a couple of ways you can get around this with a remote call. 
+
+* Put `<r:comments:remote />` on the page instead and a stub will be included suitable for your scripts to grab. A simple example is included in platform/forum.js.
+* `<r:comments:all /><r:comments:link />` is more efficient but less friendly: it will give you a static list of all comments followed by a reply link. Posting a comment clears the page cache, btw.
+
+You can also use `<r:comments:each>...</r:comments:each>` and the various r:comment tags to compose page comments however you like. See the tags-available documentation for details.
+
+## Security & Spam
+
+The reader extension includes email confirmation and a simple honeytrap that should prevent most bots from registering. The forum includes proper XSS protection via the sanitize gem and the usual CSRF protection is enabled. You ought to be relatively spam-free.
+
+## Scripting the forum interface
+
+I've presented this in the simplest way possible, on the assumption that everyone will want to do their own thing with it. An unobtrusive javascript front end (based on mootools but without much fanciness) is included to make things a little bit more friendly: it includes edit-in-place for posts, a bit of code to handle bringing page comments into the page, and some generally-useful routines like notice faders. That's about it, but I hope it will provide a starting point. The 'forum_example' layout that is created on installation should bring in that javascript and enough css for you to see it all working. For local reasons it's all stored under `javascripts/platform/...`
+
+## Smilies
+
+I've included a basic set here and a redcloth extension that catches :smile: notation alongside the textile markup. There's a javascript front end in the works for that - click on the smiley, you know - which will also soon appear here.
+
+## Bugs
+
+Very likely. [Github issues](http://github.com/spanner/radiant-forum-extension/issues), please, or for little things an email or github message is fine.
+
+## Author & Copyright
+
+* William Ross, for spanner. will at spanner.org
+* Originally based on dear old Beast, currently not visible at [http://beast.caboo.se](http://beast.caboo.se)
+* Copyright 2007-9 spanner ltd
+* released under the same terms as Rails and/or Radiant

data/Rakefile

@@ -0,0 +1,139 @@
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "radiant-forum-extension"
+    gem.summary = %Q{Forum and Comment Extension for Radiant CMS}
+    gem.description = %Q{Nice clean forums and page comments for inclusion in your radiant site. Derived long ago from beast. Requires the reader extension and share_layouts.}
+    gem.email = "will@spanner.org"
+    gem.homepage = "http://github.com/spanner/radiant-forum-extension"
+    gem.authors = ["spanner"]
+    gem.add_dependency "radiant", ">= 0.9.0"
+    gem.add_dependency 'radiant-reader-extension'
+    gem.add_dependency 'paperclip'
+    gem.add_dependency 'will_paginate'
+  end
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. This is only required if you plan to package forum 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 forum extension.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'ForumExtension'
+  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 forum 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 @@
+0.6.0

data/app/controllers/admin/forums_controller.rb

@@ -0,0 +1,11 @@
+class Admin::ForumsController < Admin::ResourceController
+
+  # # I have no idea where this default is being overridden
+  # skip_before_filter :verify_authenticity_token if ENV["RAILS_ENV"] == "test"
+
+  only_allow_access_to :new, :create, :edit, :update, :remove, :destroy,
+    :when => :admin,
+    :denied_url => { :controller => 'pages', :action => 'index' },
+    :denied_message => 'You must be an administrator to add or change discussion categories.'
+  
+end

data/app/controllers/forums_controller.rb

@@ -0,0 +1,34 @@
+class ForumsController < ReaderActionController
+  skip_before_filter :require_reader
+  before_filter :find_forum, :only => :show
+  before_filter :no_changes_here, :except => [:index, :show]
+
+  radiant_layout { |controller| controller.layout_for(:forum) }
+
+  def index
+    @forums = Forum.visible.paginate(:all, :order => "position", :page => params[:page] || 1, :per_page => params[:per_page])
+  end
+
+  def show
+    respond_to do |format|
+      format.html { 
+        @topics = Topic.paginate_by_forum_id(params[:id], :page => params[:page] || 1, :per_page => params[:per_page] || 20, :include => :replied_by, :order => 'sticky desc, replied_at desc')
+      }
+      format.rss  {
+        @topics = Topic.paginate_by_forum_id(params[:id], :page => params[:page] || 1, :per_page => params[:per_page] || 20, :include => :replied_by, :order => 'replied_at desc')
+        render :layout => 'feed'
+      }
+    end
+  end
+
+  def no_changes_here
+    redirect_to admin_forums_url
+  end
+
+protected
+
+  def find_forum
+    @forum = Forum.find(params[:id])
+  end
+
+end

data/app/controllers/posts_controller.rb

@@ -0,0 +1,238 @@
+class PostsController < ReaderActionController
+
+  before_filter :set_site_title
+  before_filter :require_activated_reader, :except => [:index, :show, :search]
+  before_filter :find_topic_or_page, :except => [:index, :search]
+  before_filter :require_unlocked_topic_and_page, :only => [:new, :create]
+  before_filter :find_post, :only => [:show, :edit, :update]
+  before_filter :build_post, :only => [:new]
+  before_filter :require_authority, :only => [:edit, :update, :destroy]
+
+  radiant_layout { |controller| controller.layout_for(:forum) }
+
+  @@default_query_options = { 
+    :page => 1,
+    :per_page => 20,
+    :order => 'posts.created_at desc',
+    :include => [:topic, :forum, :reader]
+  }
+  
+  def index
+    @posts = Post.visible.paginate(:all, @@default_query_options.merge(:page => params[:page], :per_page => params[:per_page]))
+    render_page_or_feed
+  end
+
+  def search
+    conditions = []
+    @reader = Reader.find(params[:reader_id]) unless params[:reader_id].blank?
+    @topic = Topic.find(params[:topic_id]) unless params[:topic_id].blank?
+    @forum = Forum.find(params[:forum_id]) unless params[:forum_id].blank?
+
+    conditions << Post.send(:sanitize_sql, ["posts.reader_id = ?", @reader.id]) if @reader
+    conditions << Post.send(:sanitize_sql, ["posts.topic_id = ?", @topic.id]) if @topic
+    conditions << Post.send(:sanitize_sql, ["posts.forum_id = ?", @forum.id]) if @forum
+    conditions << Post.send(:sanitize_sql, ['LOWER(posts.body) LIKE ?', "%#{params[:q]}%"]) unless params[:q].blank?
+    @searching = true if conditions.any?
+    
+    @posts = Post.paginate(:all, @@default_query_options.merge(:conditions => @searching ? conditions.collect { |c| "(#{c})" }.join(' AND ') : nil, :page => params[:page], :per_page => params[:per_page]))
+
+    # for summary of the set, and onward links
+    @forums = @posts.collect(&:forum).uniq
+    @topics = @posts.collect(&:topic).uniq
+    @readers = @posts.collect(&:reader).uniq
+    
+    if @searching
+      @title = "Search Results"
+      @description = "Posts"
+      @description << " matching '#{params[:q]}'" unless params[:q].blank?
+      @description << " from #{@reader.name}" if @reader
+      if @topic
+        @description << " under #{@topic.name}"
+      elsif @forum
+        @description << " in #{@forum.name}"
+      end
+    end
+    
+    render_page_or_feed
+  end
+
+  def monitored
+    @searching = true
+    options = @@query_options.merge(:conditions => ['monitorships.reader_id = ? and monitorships.active = ?', params[:reader_id], true])
+    options[:joins] += ' inner join monitorships on monitorships.topic_id = topics.id'
+    options[:page] = params[:page] || 1
+    @posts = Post.paginate(:all, options)
+    @title = "Topics you're watching"
+    render_page_or_feed
+  end
+
+  def show
+    respond_to do |format|
+      format.html { redirect_to_page_or_topic }
+      format.js { render :layout => false }
+    end
+  end
+
+  # this is typically called by xht to bring a comment form into a page or a reply form into a topic
+  # if the reader is not logged in, reader_required should have intervened and caused the return of a login form instead
+
+  def new
+    respond_to do |format|
+      format.html { render :template => 'posts/new' } # we specify the template because in theory we could be reverting from a post to create 
+      format.js { render :partial => 'posts/reply' }
+    end
+  end
+    
+  def create
+    if @topic.new_record?
+      # only happens if it's a page comment and the topic has just been built
+      # in that case we can let the topic-creation routines do the post work
+      @topic.body = params[:post][:body]
+      @topic.reader = current_reader
+      @topic.save!
+      @post = @topic.first_post
+    else
+      @post = @topic.posts.create!(params[:post])
+    end
+
+    @post.save_attachments(params[:files]) unless @page && !Radiant::Config['forum.comments_have_attachments']
+    Radiant::Cache.clear if @page
+
+    respond_to do |format|
+      format.html { redirect_to_page_or_topic }
+      format.js { render :action => 'show', :layout => false }
+    end
+    
+  rescue ActiveRecord::RecordInvalid
+    flash[:error] = 'Problem!'
+    respond_to do |format|
+      format.html { render :action => 'new' }
+      format.js { render :action => 'new', :layout => false }
+    end
+  end
+
+  def topic_locked
+    respond_to do |format|
+      format.html do
+        flash[:notice] = 'Topic is locked.'
+        redirect_to_page_or_topic
+      end
+      format.js { render :partial => 'topics/locked' }
+    end
+    return
+  end
+    
+  def edit
+    respond_to do |format| 
+      format.html { render }
+      format.js { render :layout => false }
+    end
+  end
+  
+  def update
+    @post.attributes = params[:post]
+    @post.save!
+    @post.save_attachments(params[:files])
+    Radiant::Cache.clear if @post.topic.page
+  rescue ActiveRecord::RecordInvalid
+    flash[:error] = "Sorry: message can't be empty"
+  ensure
+    respond_to do |format|
+      format.html { redirect_to_page_or_topic }
+      format.js { render :partial => 'post', :layout => false }
+      format.json { render :json => @post.as_json }
+    end
+  end
+
+  def destroy
+    if @post.first?
+      @post.topic.destroy
+      flash[:notice] = "Topic removed"
+      respond_to do |format|
+        format.html { redirect_to_forum }
+        format.js { render :partial => 'post', :layout => false }
+      end
+    else
+      @post.destroy
+      flash[:notice] = "Post removed"
+      respond_to do |format|
+        format.html { redirect_to_page_or_topic }
+        format.js { render :partial => 'post', :layout => false }
+      end
+    end
+  end
+
+protected
+
+  def require_authority
+    (current_user && current_user.admin?) || @post.editable_by?(current_reader)      # includes an editable-interval check
+  end
+          
+  def find_topic_or_page
+    if params[:page_id]
+      @page = Page.find(params[:page_id])
+      @topic = @page.find_or_build_topic
+      @forum = @topic.forum if @topic
+    elsif params[:topic_id]
+      @topic = Topic.find(params[:topic_id], :include => :forum)
+      @forum = @topic.forum if @topic
+    end
+  end
+  
+  def require_unlocked_topic_and_page
+    return page_locked if @page && @page.locked?
+    return topic_locked if @topic.locked?
+    true
+  end
+
+  def find_post
+    @post = @topic.posts.find(params[:id])
+  end
+  
+  def build_post
+    @post = Post.new(params[:post])
+    @post.topic = @topic if @topic
+    @post.reader = current_reader
+  end
+  
+  def redirect_to_page_or_topic   
+    if (@topic.page)
+      post_location = @post ? "##{@post.dom_id}" : ""
+      redirect_to @topic.page.url + post_location
+    else
+      post_location = @post ? {:page => @post.topic_page, :anchor => @post.dom_id} : {}
+      redirect_to forum_topic_url(@topic.forum, @topic, post_location)
+    end
+  end
+
+  def redirect_to_forum
+    redirect_to forum_url(@topic.forum)
+  end
+  
+  def page_locked
+    respond_to do |format|
+      format.html {
+        flash[:error] = 'This page is not commentable.'
+        redirect_to @page.url
+      }
+      format.js {
+        render :template => 'locked', :layout => false
+      }
+    end
+    false
+  end
+  
+  def topic_locked
+    respond_to do |format|
+      format.html {
+        flash[:error] = 'This topic is locked.'
+        redirect_to_page_or_topic
+      }
+      format.js {
+        render :partial => 'topics/locked'
+      }
+    end
+    false
+  end
+
+end