radiant-page_factory-extension 1.0.0

data/EXAMPLES.md

@@ -0,0 +1,136 @@
+# Using PageFactory
+
+PageFactory is meant to provide a way of defining content types without altering the page editing experience, or the way pages fundamentally behave. A content type is just a set of parts that you can re-use to create many pages with the same structure.
+
+Let's say I'm creating a Radiant site for my company, and I need to create an employee directory. I'll have a lot of pages that represent individual employees, and each page will need the same basic parts: first name, last name, and biography.
+
+Rather than add these parts to every employee page, it would be nice if I could simply get a new page with these parts already added. Page Factory lets me define "factories" which will set up my new pages exactly the way I want. I can have multiple factories, and I can make changes to existing factories and ask them to update my existing content.
+
+## Creating new factories
+
+The first thing I'll do (after installing PageFactory and running `rake db:migrate:extensions`) is to create a factory for "Employee" pages. I'll create a file called "employee_page_factory.rb" (the `_page_factory` suffix is mandatory.) I can put this in the app/models/ or lib/ directory of any extension, or a lib/ directory at the root of my Radiant project.
+
+I need to tell my factory what parts I want:
+
+    class EmployeePageFactory < PageFactory::Base
+      part 'first name'
+      part 'last name'
+      part 'biography'
+    end
+
+I visit /admin/pages, and click "Add Child." Hey, there's a popup here asking me what kind of page to add! I select "Employee Page" and I'm taken to a new page. The first name, last name, and biography parts are waiting for me! Neat!
+
+But I don't need the default "extended" part on my employees page. Let's get rid of it:
+
+    class EmployeePageFactory < PageFactory::Base
+      part 'first name'
+      part 'last name'
+      part 'biography'
+      remove 'extended'
+    end
+
+Repeat the steps to add a new page, and the "extended" part is no longer taking up space.
+
+## Additional part options
+
+I'll be adding a page for each of my coworkers, but I want them to log in and fill out their own biographies. In the meantime, I want some placeholder text in the biography part, even if it's just dummy text. That should motivate everyone to actually fill it out.
+
+I'll edit my page factory to add the dummy text:
+
+    class EmployeePageFactory < PageFactory::Base
+      part 'first name'
+      part 'last name'
+      part 'biography', :content => "Lorem ipsum dolor sit amet."
+    end
+
+Now when I add a new Employee page, the biography field will be pre-populated with this dummy text. But I want to make it clear that people should replace this with actual content. (Not all of my coworkers speak Latin.) I can add a little helper text that will be shown on the "biography" part tab, in order to explain what this part is used for:
+
+    class EmployeePageFactory < PageFactory::Base
+      part 'first name'
+      part 'last name'
+      part 'biography', :content => "Lorem ipsum dolor sit amet.",
+                        :description => "Please replace this with one or two paragraphs about yourself."
+    end
+
+The helper text gets displayed right above the text field on the biography tab for all new Employee pages.
+
+## Updating existing content
+
+### Adding parts
+
+I spent all day adding employee pages for each of my coworkers... and then my boss tells me that the employee pages should list people's department. I add a 'department' part to my EmployeePageFactory, but this won't affect any employee pages I've already created.
+
+Luckily, I won't have to go back through each existing employee page to manually add a department part. I can run the following rake task:
+
+    $ rake radiant:extensions:page_factory:refresh:soft
+
+This iterates over every page created with a factory and adds any parts that are listed in the page's factory but missing from the page. Now all of my existing Employee pages have been updated with an empty "department" part.
+
+It's called a "soft" refresh because it adds parts, but it won't change or remove any content. If I had more than one factory and I only wanted to act on Employee pages, I could specify a particular factory:
+
+    $ rake radiant:extensions:page_factory:refresh:soft[employee]
+
+That argument is the name of my factory class minus "page_factory," because this rake task is already long enough.
+
+### Removing parts
+
+The boss just changed her mind about displaying everyone's department. This always happens! No problem though, I can just as easily remove the extra part. I just remove it from my factory definition and run this task:
+
+    $ rake radiant:extensions:page_factory:refresh:hard[employee]
+
+Unlike a soft refresh, a hard refresh _will_ alter or remove content. In this case, it goes through all of my Employee pages and removes any parts that aren't listed in the factory definition.
+
+## Other factory options
+
+### Descriptions
+
+If you have a lot of factories, it might be helpful to add a description to each so that you remember what they're all used for.
+
+    class EmployeePageFactory < PageFactory::Base
+      description "An employee profile page."
+
+      part 'first name'
+      part 'last name'
+      ...
+    end
+
+This description appears in the factory selection popup.
+
+### Default layouts
+
+Our very talented designer has just sent me the markup for the employee page. I'd like to put this in a layout and assign it to all the employee pages -- that way I only have to edit it in one place if there are changes later. I create a new layout called "Employee" and paste in the markup. I can make this the default layout by passing its name to the factory:
+
+    class EmployeePageFactory < PageFactory::Base
+      layout "Employee"
+      
+      part 'first name'
+      part 'last name'
+      part 'biography', :content => "Lorem ipsum dolor sit amet.",
+                        :description => "..."
+    end
+
+Now the Employee layout will be automatically selected whenever I create a new Employee page. If I want to update all of my previously created Employee pages to use this new layout, I can do this by running the hard refresh task.
+
+### Default page classes
+
+Sometimes it might be useful to set a default page class, if for instance I have a page factory that deals with Archive pages. That's just as easy:
+
+    class ArchivePageFactory < PageFactory::Base
+      page_class "ArchivePage"
+    end
+
+Again, I'd have to run the hard refresh task to update any existing pages.
+
+## Working with pages
+
+Good news! Because PageFactory made it so easy to create and maintain our site, I was awarded the Lifetime Employee Achievement Award! As part of this, I get to have a photo on my employee page. I'll use this nice one of me in a dapper hat.
+
+This will require an extra page part, to hold the URL for my photo. It will also require a slightly different layout, to hold the image tag.
+
+Does this mean I need to create a new factory and recreate my own employee page? Nope! PageFactory was built with flexibility in mind, and doesn't prevent you from working with pages in the ways that you're used to.
+
+I can just open up my page and add a new 'photo url' part, then change the layout to one that accommodates a photo. The EmployeePageFactory doesn't care what happens to employee pages after they've been created. And if they ever find out I've been filching copy paper and revoke my award, I can just as easily remove that extra part and change the layout back to a normal employee layout.
+
+(I do have to be careful about running the hard refresh task, however. That will remove my photo part, because it isn't defined in the factory, and reset my layout to the default employee layout. I can safely run it as long as I specify another factory name.)
+
+I can also add a plain old page with no factory and add/delete parts as usual -- I don't have to rely on a factory for everything. This makes it easy to add individual pages whenever I want.

data/README.md

@@ -0,0 +1,59 @@
+# Page Factory
+
+An experimental Radiant extension for defining content types/page templates. The intent is to stay light and reuse instead of rebuild.
+
+There are three basic questions when dealing with content types in any CMS:
+
++ Content Definition: what parts make up a particular kind of page?
++ Templating: what's the markup for each set of parts?
++ Versioning: how do we track and share changes to definitions & templates?
+
+Page Factory is meant to address the first point, defining pages. Templating and versioning can be achieved with existing extensions and don't need to be reinvented. I like the combination of Nested Layouts and File System Resources, but the goal is to create an extension that's agnostic on those matters.
+
+## Goals
+
+I'm using the word "Factory" very deliberately. A traditional "content type" is a model that's attached to a page for the page's entire lifespan. To some extent, the content type dictates what you can and cannot do with that page.
+
+This is a different approach. I want a _factory_ that only cares about setting up new pages, and doesn't make any page modifications until I tell it to. I want to retain all of the flexibility that comes with Radiant.
+
+I want the following behaviors in my solution:
+
+### Flexibility
+
+I want my factories to set up pages for me and then stay out of my way. Using factories shouldn't prevent me from creating a Plain Old Page with my own choice of parts; nor should they prevent me from modifying pages after they're created.
+
+### Simplicity
+
+Page factories shouldn't fundamentally alter the way Pages work. I don't want to overload the `:body` part for use as a layout container. Nor do I want to use a web interface to manipulate content types. A Page factory should be a regular Ruby class; I should be able to inherit or extend it.
+
+### Modularity
+
+I want my factories to respect the division between presentation and behavior. Factories can _suggest_ a Page class, but shouldn't prevent you from changing that class on new or existing records. I'd like to take a similar approach to layouts -- flexibility is a requirement, not an enhancement.
+
+## Some use cases
+
+In addition to the core task of defining content types, there are some specific cases I want Page Factory to address:
+
+### Generic pages
+
+I want to add a one-off page somewhere. In the past, generic pages have been catch-all content types with enough parts to fit any use case. They're ugly and hard to use.
+
+I should be able to add a Plain Old Page without setting up a content type first. I should be able to add only those parts I need. I should be able to use the `:body` part to hold that page's unique markup, just like normal Radiant usage.
+
+### Edge cases
+
+There's a page that needs to look or behave just a little differently from others of its kind. Instead of making its content type pull double duty, or creating a content type to handle a single page, I should be able to switch this page to a different layout. Or use a different page class. Or add a single page part to it.
+
+Page factories shouldn't have an opinion about any of those attributes until you tell it to take action on a page or set of pages.
+
+## Usage
+
+See EXAMPLES.md for a detailed walkthrough.
+
+## Notes on implementation
+
++   **Syncing.** Because I'm not exposing these factories in the admin UI, there's no need to do this in real-time. Unless explicitly asked, the methods responsible for altering existing content ignore Plain Old Pages so that you have at least one type of Page that's always open to modification and not in any danger of being overwritten.
+
++   **Changing factories.** I decided not to implement a way to change a page's factory after creation. This is mostly because I felt adding a new element to the page edit interface wasn't in line with PageFactory's stated goal of changing as little as possible about page behavior. It was confusing to have both a 'Page Type' select and a factory/template/whatever select side-by-side.
+
+    Additionally, I haven't worked out how changing a page's factory should work. Do the parts get reassigned on the fly? What happens if the pages share some parts?

data/Rakefile

@@ -0,0 +1,136 @@
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "radiant-page_factory-extension"
+    gem.summary = %Q{Page Factory Extension for Radiant CMS}
+    gem.description = %Q{Page Factory is a small DSL for intelligently defining content types in Radiant CMS.}
+    gem.email = "josh@vitamin-j.com"
+    gem.homepage = "http://github.com/joshfrench/radiant-page_factory-extension"
+    gem.authors = ["Josh French"]
+    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 page-factory 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 page_factory extension.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'PageFactoryExtension'
+  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 page_factory 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 @@
+1.0.0

data/app/controllers/admin/page_factories_controller.rb

@@ -0,0 +1,42 @@
+class Admin::PageFactoriesController < ApplicationController
+  helper_method :factory_link
+
+  def index
+    @page = Page.find_by_id(params[:page])
+    @factories = factories
+
+    respond_to do |format|
+      format.html { render :partial => '/admin/page_factories/page_factory', :collection => @factories }
+      format.js { render :partial => '/admin/page_factories/page_factory', :collection => @factories }
+      format.json { render :json => @factories.to_json() }
+      format.xml { render :json => @factories.to_xml() }
+    end
+  end
+
+  private
+    ##
+    # If you need to limit what factories can be selected, alias chain this
+    # method. The current user and @page (the page you're adding a child to)
+    # are available here, so you can filter according to @page.class_name,
+    # @page.page_factory, current_user roles, etc.
+    #
+    # @return [Array] an array of factory classes which you may then modify
+    #
+    # @example Don't let designers add Archive pages
+    #   def factories_with_permissions
+    #     if current_user.admin?
+    #       factories_without_permissions
+    #     else
+    #       factories_without_permissions.reject { |f| f.page_class == 'ArchivePage' }
+    #     end
+    #   end
+    #   alias_method_chain :factories, :permissions
+    def factories
+      [PageFactory::Base, *PageFactory::Base.descendants.sort { |a,b| a.name <=> b.name }]
+    end
+
+    def factory_link(factory=PageFactory::Base)
+      args = { :factory => factory < PageFactory::Base ? factory : nil }
+      @page.nil? ? new_admin_page_path(args) : new_admin_page_child_path(@page, args)
+    end
+end

data/app/helpers/admin/part_description_helper.rb

@@ -0,0 +1,9 @@
+module Admin::PartDescriptionHelper
+  def description_for(part)
+    return nil if @page.nil? or @page.page_factory.blank?
+    @page.page_factory.parts.detect do |f|
+      f.name.downcase == part.name.downcase and
+      f.class == part.class
+    end.try :description
+  end
+end

data/app/views/admin/page_factories/_page_factory.html.haml

@@ -0,0 +1,4 @@
+- if page_factory_counter == 1
+  %li{:class => 'separator'}
+%li
+  = link_to page_factory.template_name, factory_link(page_factory), :title => page_factory.description

data/app/views/admin/page_parts/_part_description.html.haml

@@ -0,0 +1,2 @@
+%span.part_description
+  = description_for(page_part)

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

@@ -0,0 +1,3 @@
+- unless simple
+  %td.add_child
+    = link_to t('add_child'), admin_factory_link_path(:page => page), :class => 'dropdown'

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

@@ -0,0 +1 @@
+%h1== #{controller.template_name.capitalize} #{(@page.page_factory || PageFactory::Base).template_name}

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

@@ -0,0 +1,4 @@
+- unless @pages.blank?
+  %ul.menu{:id => "add_child_dropdown"}
+    %li
+      %a= link_to PageFactory::Base.template_name, new_admin_page_path, :title => PageFactory::Base.description

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

@@ -0,0 +1 @@
+= hidden_field_tag 'page[page_factory]', @page.try(:page_factory) || params[:factory]

data/config/locales/en.yml

@@ -0,0 +1,3 @@
+---
+en:
+  page factory: Page Factory

data/config/routes.rb

@@ -0,0 +1,5 @@
+ActionController::Routing::Routes.draw do |map|
+  map.namespace :admin do |admin|
+    admin.factory_link '/pages/factories', :controller => 'page_factories', :action => 'index'
+  end
+end

data/db/migrate/20100321222140_add_page_factory.rb

@@ -0,0 +1,9 @@
+class AddPageFactory < ActiveRecord::Migration
+  def self.up
+    add_column :pages, :page_factory, :string
+  end
+
+  def self.down
+    remove_column :pages, :page_factory
+  end
+end

data/lib/page_factory.rb

@@ -0,0 +1,12 @@
+module PageFactory
+  def self.current_factory
+    @current_factory ||= PageFactory::Base
+  end
+
+  def self.current_factory=(factory)
+    factory = factory.constantize if factory.is_a?(String)
+    if factory.nil? or factory <= PageFactory::Base
+      @current_factory = factory
+    end
+  end
+end