radiant-reader-extension 3.0.0.rc4 → 3.0.0

data/README.md

@@ -2,82 +2,150 @@
 
 This is a framework that takes care of all the dull bits of registering, activating, reminding, logging in and editing preferences for your site visitors. 
 
-It uses authlogic to handle sessions and provides complete interfaces both for the administrator and the visitor. The admin interface is very basic and fits in with radiant. The visitor interface is more friendly (and incidentally includes a trick email field - so-called inverse captcha - that should prevent spam signups).
+It uses authlogic to handle sessions and provides complete interfaces both for the administrator and the visitor. The admin interface is simple and fits in with radiant. The visitor interface is more friendly (and incidentally includes a trick email field - so-called inverse captcha - that should prevent spam signups).
 
 The visitors are referred to as 'readers' here. Readers never see the admin interface, but your site authors and admins are automatically given reader status.
 
-The purpose of this extension is to provide a common core that supports other visitor-facing machinery. See for example our [forum extension](http://github.com/spanner/radiant-forum-extension) for discussions and page/blog comments and [downloads extension](http://github.com/spanner/radiant-downloads-extension) for secure access-controlled file downloads. More will follow and I hope other people will make use of this framework.
+## Status
 
-## Latest
+Compatible with radiant 1, which isn't out yet. You can use radiant edge to try this out. Expect a few point releases as radiant 1 is finalised.
 
-This version requires edge radiant, or radiant 1 when it becomes available. We are using a lot of the new configuration and sheets code.
+Multi-site compatibility is currently missing but will follow as soon as I can add a better scoping engine to radiant core.
 
-New ReaderPages provide flexible directory services with configurable access control. The old controller and page parts mechanism is going to be phased out gradually both here and in the forum in favour of more orthodox radiant page-types. We will always need to use the layout-wrapper approach for login and registration forms, though.
+## Note on internationalisation and customisation
 
-Right now we are **not compatible with multi_site or the sites extension**: that's mostly because neither is radiant edge: it will all be sorted out in time for the release of v1, which isn't far away.
+The locale strings here are generally defined in a functional rather than grammatical way. That is, they have labels like `activation_required_explanation` rather than being assembled out of lexical units. This is partly because for flexibility of translation, but also because it gives you an easy way to change the text on functional pages like reader-preferences and registration forms.
 
-Also:
+## Requirements
 
-* public interface internationalized;
-* Uses the new configuration interface;
-* Messaging much simplified and now intended to be purely administrative.
-* ajaxable status panel returned by `reader_session_url` (ie. you just have to call /reader_session.js over xmlhttp to get a sensible welcome and control block)
+Versions 3.x of reader are designed to work with radiant 1 and will not work with older versions. There's a '0.9.1' tag in the repository for the last release that will.
 
-## Status
+Since you now have to install reader as a gem, all of its gem-based dependencies will be taken care of for you, but you may need some system libraries. We use Sanitize to whitelist html input. Sanitize uses Nogogiri to parse html, and Nokogiri needs `libxml2` and `libxslt` to do that. If you've installed imagemagick to work with radiant assets, it's very likely that you have those libraries already. If not, you will need to install them before you can install the reader gem.
 
-Compatible with radiant 1, which isn't out yet. You can use radiant edge to try this out. Expect small changes in support of the new forum and group releases. Multi-site compatibility will follow soon.
+## Installation
 
-## Note on internationalisation and customisation
+Install the gem:
 
-The locale strings here are generally defined in a functional rather than grammatical way. That is, they have labels like `activation_required_explanation` rather than being assembled out of lexical units. This is partly because for flexibility of translation, but also because it gives you an easy way to change the text on functional pages like reader-preferences and registration forms.
+	sudo gem install radiant-reader-extension
 
-## Requirements
+add it to your application's Gemfile:
 
-Radiant 0.9.2 (or currently, edge). The [layouts](http://github.com/squaretalent/radiant-layouts-extension) and [mailer_layouts](http://github.com/spanner/radiant-mailer_layouts-extension) extensions.
+	gem 'authlogic', "~> 2.1.6"
+	gem radiant-reader-extension, '~>2.0.0'
 
-You also need three gems (in addition to those that radiant requires): authlogic, gravtastic and sanitize. They're declared in the extension so you should be able just to run
+and then you can bring over assets and create data tables:
 
-	sudo rake gems:install
+	rake radiant:extensions:update_all
+	rake radiant:extensions:reader:migrate
+	rake radiant:extensions:reader:update
 
-Sanitize uses nokogiri, which needs libxml2 and libxslt: you may need to go off and install those first. You will also need to put
+## Configuration
 
-	gem 'authlogic'
+All the main configuration settings can now be managed through the `settings > readers` configuration pane. THey have sensible defaults but you will need to choose a layout for reader-administration views and supply the name and email address that messages should appear to come from.
 
-in your environment.rb before you can migrate anything. Authlogic has to load before _anything_ else requires `ApplicationController`.
+## Usage
 
-## Installation
+This is primarily a framework and its main purpose is to take care of the tedious minutiae of account-management. The basic reader framework provides for:
 
-As a gem:
+* registration
+* honeypot spam trap
+* activation by email confirmation
+* logging in and out
+* password reminders
+* edit account preferences
+* edit profile
+* dashboard view on login
+* configurable members directory with csv and vcard export
+* administrative email messages for welcome, invitation, etc
+* ad-hoc email messages to some or all readers
 
-	gem install 'radiant_reader_extension'
-	
-or for more control:
+The extension also includes a group-based access control mechanism. You can organise your readers into groups (either by invitation or by public subscription) and any resource (eg a page) associated with one or more groups is visible only to their members. Anyone else attempting to access the page will be prompted to log in (or register, if registration is permitted).
 
-	git submodule add git://github.com/spanner/radiant-reader-extension.git vendor/extensions/reader
+You can use the group mechanism in a simple way just to create self-selected interest groups, or you can disable public registration and use the full group-hierarchical functionality to provide a very secure system of controlled access to selected resources. 
 
-and then:
+The group-scoping mechanism is easily extended to other classes:
 
-	rake radiant:extensions:reader:migrate
-	rake radiant:extensions:reader:update
+	class Widget < ActiveRecord::Base
+	  has_groups
+	  ...
+	end
 
-## Configuration
+So the forum extension, for example, includes the ability to make a forum visible only to members of selected groups.
 
-All the main configuration settings can now be managed through the 'readers' configuration pane.
+For more reader-facing usefulness please see our [forum extension](http://github.com/spanner/radiant-forum-extension) for discussions and page/blog comments and [downloads extension](http://github.com/spanner/radiant-downloads-extension) for secure access-controlled file downloads. We also have extensions for public submission of calendar events and assets, which will emerge here soon.
 
 ## Layouts
 
-We use the share_layouts extension to wrap the layout of your public site around the pages produced by the reader extension. You can designate any layout as the 'reader layout': in a single-site installation put the name of the layout in a `reader.layout` config entry. In a multi-site installation you'll find a 'reader layout' dropdown on the 'edit site' page. Choose the one you want to use for each site.
+We use the `layouts` extension to wrap the appearance of your public site around the views produced by the reader extension. You can configure this with the dropdown list on the reader configuration page.
+
+The laying-out is achieved by defining lots of fake page parts in the reader views. All your layout has to do is include those page parts with the usual `<r:content />` calls.
+
+* `<r:content />` on its own will hold the main page content: login form, activation form, dashboard or whatever.
+* `<r:title />` is always the page title
+* `<r:content part="introduction" />` will provide a separate opening paragraph for layouts that require it
+* `<r:content part="sidebar" />` will (sometimes) provide relevant marginal content
+* `<r:content part="breadhead" />` is a more minimal breadcrumb trail that omits the present page and is suitable for use above the page title
+* `<r:content part="controls" />` will show a standard 'hello [name]' block with login and logout and so on, but only on an uncached page. If the page is cached it will render an empty div with class 'remote_controls' that you can populate with javascipt. An ajax call to `/reader_session/show` will return the same controls block.
+* `<r:content part="signals" />` will render any confirmation or error flashes. Not suitable for cached pages.
+* `<r:content part="person" />` will render a gravatar and link for the current reader
+
+You don't really need anything but the main title and content tags:
 
-The layout of the layout is up to you: from our point of view all it has to do is call `<r:content />` at some point. Ideally it will call `<r:content part="pagetitle" />` too. There is also a `breadcrumbs` part if that's required. In many cases you can just use your existing site layout and the various forms and pages will drop into its usual compartments.
+	<h1><r:title /></h1>
+	<r:content />
+
+will do just fine to start with.
+
+## CSS and Javascript
+
+Some standard formatting and interaction is included for you to build upon.
+
+`/javascripts/reader.js` includes some rather basic jquery code to handle retrieving remote content (such as the control block mentioned above), fading out flashes and errors and adding a bit of responsiveness to the reader-facing forms.
+
+`/stylesheets/sass/reader.sass` includes the default formatting of reader-facing forms and lists. It could probably stand to be reorganised a bit but you should find it a useful starting point and I recommend that you override it selectively rather than replacing it completely. There are two ways to do that:
+
+* @import 'reader.sass' at the top of your (SASS-based) stylesheet within radiant
+* link to /stylesheets/reader.css in the old-fashioned way and then bring in your own stylesheets any way you like.
+
+Or you can replace all this with your own, of course.
+
+## ReaderPages
+
+You can also provide a more customised directory service by creating a ReaderPage and populating it with the many `r:readers` and `r:reader` tags that are defined here.
+
+## Directory Visibility
+
+There are four levels of directory visibility, and the behaviour of your site is set by the `reader.directory_visibility` configuration entry:
+
+* *none* is the default. No reader details are shown to anybody.
+* *public* means that anyone can see the directory. Individual readers can still opt out, but this is intended for public directory services with the expectation that people want to be shown.
+* *private* means that only logged in readers can see the directory. Useful for closed groups and works well as an internal directory for an organisation or team.
+* *grouped* means that only logged in people can see the directory and that they can only see the people with whom they share a group. Useful for more complex authorization requirements but also for sites that have a privileged core group and unprivileged guests.
 
 ## Using readers in other extensions
 
-The reader admin pages are properly registered with the AdminUI as collections of parts, so you can override them in the same way as the other admin pages.
+All the reader pages (both public and administrative) are sharded in the AdminUI. The public-facing administration and directory pages are all in `admin.accounts`, since the admin-facing views are already in `admin.readers`.
 
 Most of your reader-facing controllers will want to inherit from `ReaderActionController`.
 
 Marking a reader as untrusted does nothing here apart from making them go red, but we assume that in other extensions it will have some limiting effect.
 
+## Latest changes
+
+This version requires edge radiant, or radiant 1 when it becomes available.
+
+New ReaderPages provide flexible directory services with configurable access control. The old controller and page parts mechanism is likely to be phased out gradually both here and in the forum in favour of more orthodox radiant page-types. We will always need to use the layout-wrapper approach for login and registration forms, though.
+
+Right now we are **not compatible with multi_site or the sites extension**: that's mostly because neither is radiant edge: it will all be sorted out in time for the release of v1, which isn't far away.
+
+Also:
+
+* groups hierarchical
+* public interface internationalized;
+* Uses the new configuration interface;
+* Messaging much simplified and now intended to be purely administrative.
+* ajaxable status panel returned by `reader_session_url` (ie. you just have to call /reader_session.js over xmlhttp to get a sensible welcome and control block)
+
 ## See also
 
 * [reader_group](http://github.com/spanner/radiant-reader_group-extension)
@@ -91,7 +159,6 @@ Marking a reader as untrusted does nothing here apart from making them go red, b
 
 ## Author and copyright
 
-* Copyright spanner ltd 2007-9.
+* Copyright spanner ltd 2007-11.
 * Released under the same terms as Rails and/or Radiant.
 * Contact will at spanner.org
-

data/Rakefile

@@ -16,11 +16,11 @@ unless defined? RADIANT_ROOT
 end
 
 require 'rake'
-require 'rake/rdoctask'
+require 'rdoc/task'
 require 'rake/testtask'
 
-rspec_base = File.expand_path(RADIANT_ROOT + '/vendor/plugins/rspec/lib')
-$LOAD_PATH.unshift(rspec_base) if File.exist?(rspec_base)
+# 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'
@@ -101,7 +101,7 @@ namespace :spec do
 end
 
 desc 'Generate documentation for the reader extension.'
-Rake::RDocTask.new(:rdoc) do |rdoc|
+RDoc::Task.new(:rdoc) do |rdoc|
   rdoc.rdoc_dir = 'rdoc'
   rdoc.title    = 'ReaderExtension'
   rdoc.options << '--line-numbers' << '--inline-source'

data/app/controllers/accounts_controller.rb

@@ -2,17 +2,20 @@ class AccountsController < ReaderActionController
   helper :reader
   
   before_filter :check_registration_allowed, :only => [:new, :create, :activate]
+  before_filter :no_removing, :only => [:remove, :destroy]
   before_filter :i_am_me, :only => [:show, :edit, :edit_profile]
-  before_filter :require_reader, :except => [:new, :create, :activate]
   before_filter :default_to_self, :only => [:show]
   before_filter :restrict_to_self, :only => [:edit, :edit_profile, :update, :resend_activation]
-  before_filter :no_removing, :only => [:remove, :destroy]
+  before_filter :get_readers_and_groups, :only => [:index, :show]
+  before_filter :require_reader, :except => [:new, :create, :activate]
+  before_filter :require_reader_visibility
   before_filter :ensure_groups_subscribable, :only => [:update, :create]
 
   def index
-    @readers = Reader.visible_to(current_reader)
     respond_to do |format|
-      format.html {}
+      format.html {
+        render :template => 'readers/index'
+      }
       format.csv {
         send_data generate_csv(@readers), :type => 'text/csv; charset=utf-8; header=present', :filename => "everyone.csv"
       }
@@ -23,9 +26,10 @@ class AccountsController < ReaderActionController
   end
 
   def show
-    @reader = Reader.find(params[:id])
     respond_to do |format|
-      format.html
+      format.html {
+        render :template => 'readers/show'
+      }
       format.vcard {
         send_data @reader.vcard.to_s, :filename => "#{@reader.filename}.vcf"	
       }
@@ -88,7 +92,7 @@ class AccountsController < ReaderActionController
     @reader.clear_password = params[:reader][:password] if params[:reader][:password]
     if @reader.save
       flash[:notice] = t('reader_extension.account_updated')
-      redirect_to dashboard_url
+      redirect_to reader_dashboard_url
     else
       render :action => 'edit'
     end
@@ -105,7 +109,7 @@ protected
   end
   
   def restrict_to_self
-    flash[:error] = t("reader_extension.cannot_edit_others") if params[:id] && params[:id] != current_reader.id
+    flash[:error] = t("reader_extension.cannot_edit_others") if params[:id] && params[:id] != current_reader.id.to_s
     @reader = current_reader
   end
   
@@ -136,15 +140,24 @@ protected
   
 private
 
+  def get_readers_and_groups
+    @readers = Reader.visible_to(current_reader)
+    @groups = Group.roots.visible_to(current_reader)
+    @reader = Reader.find(params[:id]) if params[:id]
+  end
+
+  def require_reader_visibility
+    # more useful than a 404 but perhaps too informative?
+    raise ReaderError::AccessDenied, "You do not have permission to see that person." if @reader && !@reader.visible_to?(current_reader)
+  end
+
   def ensure_groups_subscribable
     if params[:reader] && params[:reader][:group_ids]
       params[:reader][:group_ids].each do |g|
-        raise ActiveRecord::RecordNotFound unless Group.find(g).public?
+        raise ReaderError::AccessDenied, "One of those groups is not public and does not accept subscriptions." unless Group.find(g).public?
       end
     end
     true
-  rescue ActiveRecord::RecordNotFound
-    false
   end
 
 end

data/app/controllers/admin/groups_controller.rb

@@ -1,8 +1,23 @@
 class Admin::GroupsController < Admin::ResourceController
+  helper :reader
+  paginate_models
   skip_before_filter :load_model
   before_filter :load_model, :except => :index    # we want the filter to run before :show too
   
   def show
     
   end
+  
+  def load_models
+    self.models = paginated? ? model_class.roots.paginate(pagination_parameters) : model_class.roots.all
+  end
+  
+  def load_model
+    self.model = if params[:id]
+      model_class.find(params[:id])
+    else
+      model_class.new(:parent_id => params[:parent_id])
+    end
+  end
+  
 end

data/app/controllers/admin/memberships_controller.rb

@@ -1,14 +1,12 @@
 class Admin::MembershipsController < ApplicationController
     
-  before_filter :find_group
+  before_filter :find_reader_and_group
   
   def index
     redirect_to admin_group_url(@group)
   end
   
   def create
-    @reader = Reader.find(params[:reader_id])
-    raise ActiveRecord::RecordNotFound unless @reader
     @membership = Membership.find_or_create_by_reader_id_and_group_id(@reader.id, @group.id)
     respond_to do |format|
       format.html { 
@@ -20,7 +18,7 @@ class Admin::MembershipsController < ApplicationController
   end
   
   def destroy
-    @membership = @group.memberships.find(params[:id])
+    @membership ||= @group.memberships.find(params[:id])
     @reader = @membership.reader
     @membership.delete if @membership
     respond_to do |format|
@@ -32,11 +30,19 @@ class Admin::MembershipsController < ApplicationController
     end
   end
   
+  def toggle
+    if @membership = Membership.find_by_reader_id_and_group_id(@reader.id, @group.id)
+      destroy
+    else
+      create
+    end
+  end
+  
 protected
 
-  def find_group
+  def find_reader_and_group
     @group = Group.find(params[:group_id])
-    raise ActiveRecord::RecordNotFound unless @group
+    @reader = Reader.find(params[:reader_id]) if params[:reader_id]
   end
-    
+
 end

data/app/controllers/admin/messages_controller.rb

@@ -6,6 +6,7 @@ class Admin::MessagesController < Admin::ResourceController
   before_filter :get_group, :only => :new
 
   # here :show is the preview/send page
+  # continue_url is extended below to redirect to show rather than index after editing.
   def show
     
   end

data/app/controllers/admin/permissions_controller.rb

@@ -1,6 +1,6 @@
 class Admin::PermissionsController < ApplicationController
     
-  before_filter :find_group
+  before_filter :find_page_and_group
   
   def index
     redirect_to admin_group_url(@group)
@@ -8,12 +8,11 @@ class Admin::PermissionsController < ApplicationController
   
   def create
     @page = Page.find(params[:page_id])
-    raise ActiveRecord::RecordNotFound unless @page
     scope = @group.permissions.for(@page)
     @permission = scope.first || scope.create!
     respond_to do |format|
       format.html { 
-        flash[:notice] = "#{@page.name} bound to group #{@group.name}"
+        flash[:notice] = "#{@page.title} bound to group #{@group.name}"
         redirect_to admin_group_url(@group) 
       }
       format.js { render :partial => 'page' }
@@ -21,23 +20,31 @@ class Admin::PermissionsController < ApplicationController
   end
   
   def destroy
-    @permission = @group.permissions.find(params[:id])
+    @permission ||= @group.permissions.find(params[:id])
     @page = @permission.permitted
     @permission.delete if @permission
     respond_to do |format|
       format.html { 
-        flash[:notice] = "#{@page.name} released from group #{@group.name}"
+        flash[:notice] = "#{@page.title} released from group #{@group.name}"
         redirect_to admin_group_url(@group)
       }
       format.js { render :partial => 'page' }
     end
   end
   
+  def toggle
+    if @permission = @group.permission_for(@page)
+      destroy
+    else
+      create
+    end
+  end
+  
 protected
 
-  def find_group
+  def find_page_and_group
     @group = Group.find(params[:group_id])
-    raise ActiveRecord::RecordNotFound unless @group
+    @page = Page.find(params[:page_id]) if params[:page_id]
   end
-  
+
 end

data/app/controllers/groups_controller.rb

@@ -16,7 +16,7 @@ class GroupsController < ReaderActionController
         send_data generate_csv(@readers), :type => 'text/csv; charset=utf-8; header=present', :filename => "#{@group.filename}.csv"
       }
       format.vcard {
-        send_data @readers.map(&:vcard).join("\n"), :filename => "#{@group.filename}.vcf"	
+        send_data generate_vcard(@readers), :filename => "#{@group.filename}.vcf"	
       }
     end
   end
@@ -24,12 +24,14 @@ class GroupsController < ReaderActionController
 private
   
   def get_group_or_groups
-    @groups = Group.visible_to(current_reader)
-    @group = @groups.find(params[:id]).first if params[:id]
+    @groups = Group.roots.visible_to(current_reader)
+    @group = Group.find(params[:id]) if params[:id]
   end
 
   def require_group_visibility
-    raise ReaderError::AccessDenied if @group && !@group.visible_to?(current_reader)
+     if @group && !@group.visible_to?(current_reader)    # nb. @groups is a smaller set
+       raise ReaderError::AccessDenied, "That group is not public and you are not in it."
+     end
   end
   
 end