slug-engine 0.0.1

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2011 YOURNAME
+
+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.rdoc

@@ -0,0 +1,35 @@
+= SlugEngine
+
+SlugEngine provides an easy, reusable method of adding permalinks to your content.
+
+== Getting Started
+
+First, add `gem 'slug_engine'` to your `Gemfile` and run `bundle install`.
+
+Second, mount the `SlugEngine` in `config/routes.rb` at the appropriate location.
+
+  My::Application.routes.draw do
+  
+    # some REST-ful routes
+    resources :posts
+  
+    # the SlugEngine
+    mount Slug::Engine => "/"
+  
+  end
+
+It's best if you place the `SlugEngine` after your other routes, but this is not required. If the `SlugEngine` cannot find a matching slug, it will abstain from handling the request, allowing lower priority routes or other engines to take a stab at the request. If no further routes match, the normal 404 page will be returned.
+
+You can use a prefix with your slugs if you like:
+
+  My::Application.routes.draw do
+  
+    # some REST-ful routes
+    resources :posts
+  
+    # the SlugEngine
+    mount Slug::Engine => "/p"
+  
+  end
+
+This will match requests like `"http://www.example.com/p/my-slug"` where `'my-slug'` is the matched slug. When authoring your content, `'/p'` will not be considered part of the slug, e.g., `p = Post.create :title => 'My Post', :slug => 'my-slug'` would still resolve when accessed at `"http://www.example.com/p/my-slug"` if the engine was prefixed.

data/Rakefile

@@ -0,0 +1,39 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Slug'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path("../test/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task :default => :test

data/app/controllers/permalinks_controller.rb

@@ -0,0 +1,45 @@
+class PermalinksController < ApplicationController
+
+  # TODO: Need to figure out how to handle slugs with extensions, e.g., 'foo/bar/baz.jpg'
+  def show
+    # find permalink, raising error if none found
+    @permalink = Permalink.find_by_slug!(params[:slug])
+  
+    # find content by permalink, raising error if none found
+    @content = content_class.find_by_permalink!(@permalink)
+    @content_type = @permalink.content_type
+    
+    # customize view path based on content_type
+    prepend_view_path "app/views/#{@content_type.pluralize.underscore}"
+    
+    # set params[:controller] to match model of content
+    params[:controller] = @content_type.pluralize.underscore
+    
+    # render the appropriate partial for this content, and do it in the layout
+    render :partial => partial, :object => decorate(@content), :layout => true
+
+  end
+
+protected
+
+  def content_class
+    @permalink.content_type.constantize
+  end
+
+  # TODO: Make this an application-extension, not built-in
+  def decorate(content)
+    decorated = begin
+      Module.const_get("#{@content_type}Decorator").decorate(content)
+    rescue NameError
+      content
+    end
+    decorated
+  end
+  
+  def partial
+    # We're going to have to make a guess about this...
+    # TODO: Is there some way to still defer to the partial renderer to determine the partial to use?
+    "#{@content_type.downcase.pluralize}/#{@content_type.downcase}"
+  end
+
+end

data/app/helpers/permalinks_helper.rb

@@ -0,0 +1,2 @@
+module PermalinksHelper
+end

data/app/models/permalink.rb

@@ -0,0 +1,28 @@
+class Permalink < ActiveRecord::Base
+  
+  belongs_to :content, :polymorphic => true
+  before_save :validate_content
+  
+  validates_presence_of   :slug
+  validates_uniqueness_of :slug
+  validate :not_system_slug
+  
+private
+
+  # Validates that the slug is not routable to a controller other than PermalinksController
+  def not_system_slug
+    begin
+      route = Rails.application.routes.recognize_path "/#{slug}"
+      errors.add :slug, "is a reserved system route" unless route[:controller] == "permalinks"
+    rescue ActionController::RoutingError
+      # No route matches, so that's probably good
+    end
+  end
+
+  def validate_content
+    errors.add :content_id, "can't be blank" unless content_id.present?
+    errors.add :content_type, "can't be blank" unless content_type.present?
+    errors.empty?
+  end
+  
+end

data/config/routes.rb

@@ -0,0 +1,5 @@
+Slug::Engine.routes.draw do
+  
+  get '*slug' => 'permalinks#show', :as => :slug
+  
+end

data/db/migrate/20111108194929_create_permalinks.rb

@@ -0,0 +1,11 @@
+class CreatePermalinks < ActiveRecord::Migration
+  def change
+    create_table :permalinks do |t|
+      t.string :slug
+      t.integer :content_id
+      t.string :content_type
+
+      t.timestamps
+    end
+  end
+end

data/lib/slug-engine.rb

@@ -0,0 +1 @@
+require 'slug'

data/lib/slug.rb

@@ -0,0 +1,80 @@
+require "slug/filter"
+require "slug/engine"
+
+module Slug
+  extend ActiveSupport::Concern
+  
+  included do
+    # setup polymorphic association
+    has_one :permalink, :as => :content, :dependent => :destroy, :autosave => true
+
+    # allows forms to accept values for permalink
+    accepts_nested_attributes_for :permalink
+
+    # allows alternative access to slug (although validation errors will still be on 'permalink.slug')
+    delegate :slug, :slug=, :to => :permalink
+
+    # add validation callbacks
+    before_validation :set_default_slug
+
+    # This little syntactic sugar causes permalink to be created lazily precisely
+    # the first time it is accessed. This is necessary because we delegate :slug
+    # to :permalink, and if permalink is nil, things get hairy.
+    redefine_method(:permalink) do |*args|
+      association(:permalink).reader(*args) || build_permalink(*args)
+    end
+
+    # Setup a 'permalink' scope so model classes can find by permalink
+    # find_by_permalink doesn't use this, but it may be useful elsewhere
+    scope :permalink, lambda { |permalink| where(:id => permalink.content_id) }
+
+  end
+
+  module ClassMethods
+
+    # Finder returning the matching content for a given permalink, or nil if
+    # none found. Notably, the content_type of the given permalink must match
+    # the target model's class
+    def find_by_permalink(permalink)
+      find_by_permalink!(permalink)
+    rescue
+      nil
+    end
+
+    # Finder returning the matching content for a given permalink. Raises an
+    # ActiveRecord::RecordNotFound error if no match is found or if the 
+    # content_type of the given permalink must match the target model's class
+    def find_by_permalink!(permalink)
+      result = scoped_by_permalink(permalink).first
+      raise ActiveRecord::RecordNotFound.new "Could not find Content for Permalink id=#{permalink.id}" if result.nil?
+      result
+    end
+
+  protected
+
+    # Default scope for returning the matching content for a given permalink.
+    # Model classes may override this method to extend the scope query, for
+    # example, to restrict content found by permalink by additional parameters.
+    def scoped_by_permalink(permalink)
+      # scoped_by_id is a 'magic' scope created by missing_method
+      scoped_by_id(permalink.content_id)
+    end
+
+  end
+
+  module InstanceMethods
+
+  protected
+
+    # provide a suitable default slug value
+    def default_slug
+      nil
+    end
+
+    # set default_slug on permalink before validation
+    def set_default_slug
+      permalink.slug = default_slug unless permalink.slug.present?
+    end
+
+  end
+end

data/lib/slug/engine.rb

@@ -0,0 +1,8 @@
+module Slug
+  class Engine < Rails::Engine
+    
+    # Use the SlugFilter to avoid processing slugs that do not exist
+    config.middleware.use Slug::Filter
+    
+  end
+end

data/lib/slug/filter.rb

@@ -0,0 +1,31 @@
+# This middleware is necessary so that the engine can abstain from processing
+# requests where no such slug exists. If this behavior were done in a
+# controller, Rails would heavily mutate the request object and no additional
+# controllers would have much luck processing the request. Specifically, the
+# named parameters for the route are cached on the request, and downstream
+# controllers would get the wrong params hash.
+
+module Slug
+  class Filter
+    
+    def initialize(app)
+      @app = app
+    end
+  
+    def call(env)
+      # if a matching slug exists in the database, allow engine to process it
+      if Permalink.where('slug = ?', slug(env)).exists?
+        @app.call(env)
+      else # force engine to abstain from processing this request
+        [404, {"X-Cascade" => "pass"}, ["no such slug exists"]]
+      end
+    end
+
+    # Extract the :slug value from the raw request
+    def slug(env)
+      slug = env['PATH_INFO']
+      slug = slug.slice(1..-1) if slug[0] == 47 # has a leading '/'
+      slug
+    end
+  end
+end

data/lib/slug/version.rb

@@ -0,0 +1,3 @@
+module Slug
+  VERSION = "0.0.1"
+end

data/lib/tasks/slug_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :slug do
+#   # Task goes here
+# end

data/test/dummy/Rakefile

@@ -0,0 +1,7 @@
+#!/usr/bin/env rake
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require File.expand_path('../config/application', __FILE__)
+
+Dummy::Application.load_tasks

data/test/dummy/app/assets/javascripts/application.js

@@ -0,0 +1,9 @@
+// This is a manifest file that'll be compiled into including all the files listed below.
+// Add new JavaScript/Coffee code in separate files in this directory and they'll automatically
+// be included in the compiled file accessible from http://example.com/assets/application.js
+// It's not advisable to add code directly here, but if you do, it'll appear at the bottom of the
+// the compiled file.
+//
+//= require jquery
+//= require jquery_ujs
+//= require_tree .

data/test/dummy/app/assets/javascripts/posts.js

@@ -0,0 +1,2 @@
+// Place all the behaviors and hooks related to the matching controller here.
+// All this logic will automatically be available in application.js.

data/test/dummy/app/assets/javascripts/users.js

@@ -0,0 +1,2 @@
+// Place all the behaviors and hooks related to the matching controller here.
+// All this logic will automatically be available in application.js.

data/test/dummy/app/assets/stylesheets/application.css

@@ -0,0 +1,7 @@
+/*
+ * This is a manifest file that'll automatically include all the stylesheets available in this directory
+ * and any sub-directories. You're free to add application-wide styles to this file and they'll appear at
+ * the top of the compiled file, but it's generally better to create a new file per style scope.
+ *= require_self
+ *= require_tree . 
+*/

data/test/dummy/app/assets/stylesheets/posts.css

@@ -0,0 +1,4 @@
+/*
+  Place all the styles related to the matching controller here.
+  They will automatically be included in application.css.
+*/

data/test/dummy/app/assets/stylesheets/scaffold.css

@@ -0,0 +1,56 @@
+body { background-color: #fff; color: #333; }
+
+body, p, ol, ul, td {
+  font-family: verdana, arial, helvetica, sans-serif;
+  font-size:   13px;
+  line-height: 18px;
+}
+
+pre {
+  background-color: #eee;
+  padding: 10px;
+  font-size: 11px;
+}
+
+a { color: #000; }
+a:visited { color: #666; }
+a:hover { color: #fff; background-color:#000; }
+
+div.field, div.actions {
+  margin-bottom: 10px;
+}
+
+#notice {
+  color: green;
+}
+
+.field_with_errors {
+  padding: 2px;
+  background-color: red;
+  display: table;
+}
+
+#error_explanation {
+  width: 450px;
+  border: 2px solid red;
+  padding: 7px;
+  padding-bottom: 0;
+  margin-bottom: 20px;
+  background-color: #f0f0f0;
+}
+
+#error_explanation h2 {
+  text-align: left;
+  font-weight: bold;
+  padding: 5px 5px 5px 15px;
+  font-size: 12px;
+  margin: -7px;
+  margin-bottom: 0px;
+  background-color: #c00;
+  color: #fff;
+}
+
+#error_explanation ul li {
+  font-size: 12px;
+  list-style: square;
+}

data/test/dummy/app/assets/stylesheets/users.css

@@ -0,0 +1,4 @@
+/*
+  Place all the styles related to the matching controller here.
+  They will automatically be included in application.css.
+*/

data/test/dummy/app/controllers/application_controller.rb

@@ -0,0 +1,3 @@
+class ApplicationController < ActionController::Base
+  protect_from_forgery
+end

data/test/dummy/app/controllers/posts_controller.rb

@@ -0,0 +1,83 @@
+class PostsController < ApplicationController
+  # GET /posts
+  # GET /posts.json
+  def index
+    @posts = Post.all
+
+    respond_to do |format|
+      format.html # index.html.erb
+      format.json { render :json => @posts }
+    end
+  end
+
+  # GET /posts/1
+  # GET /posts/1.json
+  def show
+    @post = Post.find(params[:id])
+
+    respond_to do |format|
+      format.html # show.html.erb
+      format.json { render :json => @post }
+    end
+  end
+
+  # GET /posts/new
+  # GET /posts/new.json
+  def new
+    @post = Post.new
+
+    respond_to do |format|
+      format.html # new.html.erb
+      format.json { render :json => @post }
+    end
+  end
+
+  # GET /posts/1/edit
+  def edit
+    @post = Post.find(params[:id])
+  end
+
+  # POST /posts
+  # POST /posts.json
+  def create
+    @post = Post.new(params[:post])
+
+    respond_to do |format|
+      if @post.save
+        format.html { redirect_to @post, :notice => 'Post was successfully created.' }
+        format.json { render :json => @post, :status => :created, :location => @post }
+      else
+        format.html { render :action => "new" }
+        format.json { render :json => @post.errors, :status => :unprocessable_entity }
+      end
+    end
+  end
+
+  # PUT /posts/1
+  # PUT /posts/1.json
+  def update
+    @post = Post.find(params[:id])
+
+    respond_to do |format|
+      if @post.update_attributes(params[:post])
+        format.html { redirect_to @post, :notice => 'Post was successfully updated.' }
+        format.json { head :ok }
+      else
+        format.html { render :action => "edit" }
+        format.json { render :json => @post.errors, :status => :unprocessable_entity }
+      end
+    end
+  end
+
+  # DELETE /posts/1
+  # DELETE /posts/1.json
+  def destroy
+    @post = Post.find(params[:id])
+    @post.destroy
+
+    respond_to do |format|
+      format.html { redirect_to posts_url }
+      format.json { head :ok }
+    end
+  end
+end