headword 0.1.0

data/CHANGELOG.textile

@@ -0,0 +1,3 @@
+h2. 0.1.0
+
+* Initial Release (Jeff Rafter)

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Jeff Rafter, SocialRange, Inc.
+
+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.textile

@@ -0,0 +1,63 @@
+h1. Headword
+
+Rails user name routes for vain users.
+
+h2. Installation
+
+Headword is a Rails engine. It works with versions of Rails greater than 2.3.
+
+In config/environment.rb:
+
+<pre>
+config.gem "jeffrafter-headword",
+  :lib     => 'headword',
+  :source  => 'http://gems.github.com'
+</pre>
+
+We recommend you don't vendor the gem:
+
+Make sure the development database exists and run the generator:
+
+<pre>
+script/generate headword
+</pre>
+
+A number of files will be created and instructions will be printed.
+
+You may already have some of these files. Don't worry. You'll be asked if you want to overwrite them.
+
+Run the migration:
+
+<pre>
+rake db:migrate
+</pre>
+
+h2. Routes
+
+Headword installs a default catch-all route for single words (e.g., /jeffrafter). These are given the lowest priority in your application. If your application is already catching these routes then you may not be able to access your headword based user pages.
+
+h2. Tutorial
+
+Checkout the "tutorial":http://wiki.github.com/jeffrafter/headword/tutorial.
+
+h2. Authors
+
+Headword is based on Spreadhead.
+
+The engine implementation and gem was patterned after the Clearance gem by Thoughtbot.
+
+h2. Suggestions, Bugs, Refactoring?
+
+Fork away and create a "Github Issue":http://github.com/jeffrafter/headword/issues. Please send pull requests.
+
+When you do: 
+
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a future version unintentionally.
+* Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+h2. Documentation
+
+Documentation is available at "http://rdoc.info/projects/jeffrafter/headword":http://rdoc.info/jeffrafter/headword

data/Rakefile

@@ -0,0 +1,93 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "headword"
+    gem.summary = %Q{When your users are that vain.}
+    gem.description = %Q{Simplify adding usernames to your application.}
+    gem.email = "jeff@socialrange.org"
+    gem.homepage = "http://github.com/jeffrafter/headword"
+    gem.authors = ["Jeff Rafter"]
+    gem.add_dependency "rsl-stringex", ">= 1.0.2"
+    gem.files = FileList["[A-Z]*", "{app,config,generators,lib,rails}/**/*", "test/{controllers,models}/**/*", "test/test_helper.rb"] 
+    gem.test_files = FileList["test/{controllers,models}/**/*", "test/test_helper.rb"] 
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test => ["generator:cleanup", "generator:headword"]) do |task|
+  task.libs << "lib" << "test"
+  task.pattern = "test/**/*_test.rb"
+  task.verbose = true
+end  
+
+namespace :test do
+  Rake::TestTask.new(:clearance => ["generator:cleanup", "generator:clearance", "generator:headword"]) do |task|
+    task.libs << "lib" << "test"
+    task.pattern = "test/**/*_test.rb"
+    task.verbose = true
+  end  
+end
+
+generators = %w(headword)
+
+namespace :generator do
+  desc "Cleans up the test app before running the generator"
+  task :cleanup do  
+    FileUtils.rm_rf("test/rails")
+    system "cd test && rails rails"
+
+    # I don't like testing performance!
+    FileUtils.rm_rf("test/rails/test/performance")
+
+    system "echo \"\" >> test/rails/config/environments/test.rb"
+    system "echo \"config.gem 'thoughtbot-shoulda', :lib => 'shoulda'\" >> test/rails/config/environments/test.rb"
+    system "echo \"config.gem 'thoughtbot-factory_girl', :lib => 'factory_girl'\" >> test/rails/config/environments/test.rb"
+
+    # Make a thing
+    system "cd test/rails && ./script/generate scaffold thing name:string mood:string"
+
+    FileUtils.mkdir_p("test/rails/vendor/plugins")
+    headword_root = File.expand_path(File.dirname(__FILE__))
+    system("ln -s #{headword_root} test/rails/vendor/plugins/headword")
+  end
+  
+  desc "Prepares the application with clearance"
+  task :clearance do
+    system "echo \"config.gem 'thoughtbot-clearance', :lib => 'clearance'\" >> test/rails/config/environments/test.rb"
+    system "echo \"HOST = 'headword'\" >> test/rails/config/environments/test.rb"
+    system "echo \"DO_NOT_REPLY = 'donotreply'\" >> test/rails/config/environments/test.rb"
+    system "cd test/rails && ./script/generate clearance && rake db:migrate db:test:prepare"
+  end
+  
+  desc "Run the headword generator"
+  task :headword do
+    system "cd test/rails && ./script/generate headword && rake db:migrate db:test:prepare"
+  end
+  
+end
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "headword #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+  rdoc.rdoc_files.include('app/**/*.rb')
+  rdoc.rdoc_files.include('generators/**/*.rb')
+end

data/TODO.textile

@@ -0,0 +1 @@
+h1. To-do

data/TUTORIAL.textile

@@ -0,0 +1,80 @@
+Before you can use Headword you are going to need a few things, most importantly the headword gem:
+
+<pre>
+<code>
+  sudo gem install jeffrafter-headword --source=http://gems.github.com
+</code>
+</pre>
+
+By default this should install the rsl-stringex gem which handles the url formatting. If you want to run the spreadhead-specific tests, you will need Thoughtbot's shoulda and factory_girl. Once you have all of the requisite gems, you need to configure your Rails application to use the gem. You can do this by adding a config.gem statement to your environment.rb (or to a specific environment). For example:
+
+<pre>
+<code>
+  Rails::Initializer.run do |config|
+    # Specify gems that this application depends on and have them installed with 
+    # rake gems:install
+    config.gem "jeffrafter-headword",
+      :lib     => 'headword',
+      :source  => 'http://gems.github.com'
+
+    # Skip frameworks you're not going to use. To use Rails without a database,
+    # you must remove the Active Record framework.
+    config.frameworks -= [ :active_resource ]
+
+    # Set Time.zone default to the specified zone and make Active Record 
+    # auto-convert to this zone. Run "rake -D time" for a list of tasks for 
+    # finding time zone names.
+    config.time_zone = 'UTC'
+  end
+</code>
+</pre>
+
+After you have done this, you can use the headword generator from the console (while in the rails root).
+
+<pre>
+<code>
+  script/generate headword
+</code>
+</pre>
+
+This will create (or update) a migration for the users table for the url attribute. Additionally, it will create a User model in your app/models folder (if it does not exist). The model must have include statement to bring in all of the base functionality. This is all you need to get started, you should be able to run the migration and restart your application. 
+
+h2. What do I get?
+
+By default you will have a "/:username" route. Additionally any time a user name is changed headword will automatically generate a new url. If there is a conflict it will add "-1" to the end (or "-2" and so on).
+
+You don't get any editing. You will want to add a username field to your user editing form:
+
+<pre>
+<code>
+<div class="text_field">
+  <%= form.label :username %>
+  <%= form.text_field :username %>
+</div>
+</code>
+</pre>
+
+h2. Wait a second, I am using a Clearance, this works with Clearance right?
+
+Yup. In fact, that's the point. But, there are a couple more things you need to do. In order to modify the views that come with clearance, you need to override the UserController. To do this you need to add add the following to @app/controllers/user_controller.rb@:
+
+<pre>
+<code>
+class UsersController < Clearance::UsersController  
+end
+</code>
+</pre>
+
+And you need to modify your routes:
+
+<pre>
+<code>
+  # Add this to the top
+  map.resources :users
+</code>
+</pre>
+
+h2. Hey my routes aren't working
+
+Maybe you have some fancy routes already, maybe something using a glob? Maybe you are using another engine? The only way to really manage these things are to carefully specify the order that the engines are included. 
+

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/app/controllers/headword/users_controller.rb

@@ -0,0 +1,10 @@
+module Headword
+  class UsersController < ApplicationController
+    unloadable
+    
+    def show
+      @user = ::User.find_by_url!(params[:username])
+      render :template => 'users/show' if @user
+    end
+  end  
+end

data/config/headword_routes.rb

@@ -0,0 +1,3 @@
+ActionController::Routing::Routes.draw do |map|
+  map.username ':username', :controller => 'headword/users', :action => 'show'    
+end

data/generators/headword/USAGE

@@ -0,0 +1 @@
+script/generate headword

data/generators/headword/headword_generator.rb

@@ -0,0 +1,57 @@
+
+# Mostly pinched from http://github.com/ryanb/nifty-generators/tree/master
+Rails::Generator::Commands::Create.class_eval do
+  def insert_into(file, line)
+    logger.insert "#{line} into #{file}"
+    unless options[:pretend] || File.read(destination_path(file)).include?(line)
+      gsub_file file, /^(class|module) .+$/ do |match|
+        "#{match}\n  #{line}"
+      end
+    end
+  end
+end
+
+Rails::Generator::Commands::Destroy.class_eval do
+  def insert_into(file, line)
+    logger.remove "#{line} from #{file}"
+    unless options[:pretend]
+      gsub_file file, "\n  #{line}", ''
+    end
+  end
+end
+
+class HeadwordGenerator < Rails::Generator::Base
+  def manifest
+    record do |m|
+      model = "app/models/user.rb"
+
+      if File.exists?(model)
+        m.insert_into model, "include Headword::User"
+      else
+        m.directory File.join("app", "models")
+        m.file "user.rb", model
+      end
+
+      m.directory File.join("app", "views", "users")
+      m.file "show.html.erb", "app/views/users/show.html.erb"
+
+      m.directory File.join("test", "factories")
+      m.file "factories.rb", "test/factories/headword.rb"      
+
+      m.migration_template "migrations/#{migration_name}.rb", 'db/migrate', 
+        :migration_file_name => "headword_#{migration_name}"
+
+      m.readme "README"
+    end
+  end
+
+  private
+
+  def migration_name
+    if ActiveRecord::Base.connection.table_exists?(:users)
+      'update_users'
+    else
+      'create_users'
+    end
+  end
+end

data/generators/headword/templates/README

@@ -0,0 +1,6 @@
+
+*******************************************************************************
+
+Ok, enough fancy automatic stuff. Time for some old school monkey copy-pasting.
+
+*******************************************************************************

data/generators/headword/templates/factories.rb

@@ -0,0 +1,13 @@
+Factory.sequence :username do |n|
+  "user#{n}"
+end
+
+# We need a stub if none exists
+unless Factory.factories.include?(:user)
+  Factory.define :user do |user|
+  end
+end
+
+Factory.define :user_with_username, :parent => :user do |user|
+  user.username { Factory.next :username }
+end  

data/generators/headword/templates/migrations/create_users.rb

@@ -0,0 +1,14 @@
+class HeadwordCreateUsers < ActiveRecord::Migration
+  def self.up
+    create_table(:users) do |t|
+      t.string   :username, :null => false
+      t.string   :url, :null => false
+      t.timestamps
+    end
+    add_index :users, [:url, :id]
+  end
+
+  def self.down
+    drop_table :users
+  end
+end

data/generators/headword/templates/migrations/update_users.rb

@@ -0,0 +1,35 @@
+class HeadwordUpdateUsers < ActiveRecord::Migration
+  def self.up
+<% 
+    existing_columns = ActiveRecord::Base.connection.columns(:users).collect { |each| each.name }
+    columns = [
+      [:url,              't.string :url, :null => false'],
+      [:username,         't.string :username, :null => false']
+    ].delete_if {|c| existing_columns.include?(c.first.to_s)} 
+-%>
+    change_table(:users) do |t|
+<% columns.each do |c| -%>
+      <%= c.last %>
+<% end -%>
+    end
+    
+<%
+    existing_indexes = ActiveRecord::Base.connection.indexes(:users)
+    index_names = existing_indexes.collect { |each| each.name }
+    new_indexes = [
+      [:index_users_on_id_and_url, 'add_index :users, [:url, :id]']
+    ].delete_if { |each| index_names.include?(each.first.to_s) }
+-%>
+<% new_indexes.each do |each| -%>
+    <%= each.last %>
+<% end -%>
+  end
+  
+  def self.down
+    change_table(:pages) do |t|
+<% unless columns.empty? -%>
+      t.remove <%= columns.collect { |each| ":#{each.first}" }.join(',') %>
+<% end -%>
+    end
+  end
+end

data/generators/headword/templates/show.html.erb

@@ -0,0 +1 @@
+<h2><%= @user.username -%></h2>

data/generators/headword/templates/user.rb

@@ -0,0 +1,3 @@
+class User < ActiveRecord::Base
+  include Headword::User
+end

data/lib/headword.rb

@@ -0,0 +1,3 @@
+require 'stringex'
+require 'headword/extensions/routes'
+require 'headword/user'

data/lib/headword/extensions/routes.rb

@@ -0,0 +1,14 @@
+if defined?(ActionController::Routing::RouteSet)
+  class ActionController::Routing::RouteSet
+    def load_routes_with_headword!
+      lib_path = File.dirname(__FILE__)
+      routes = File.join(lib_path, *%w[.. .. .. config headword_routes.rb])
+      unless configuration_files.include?(routes)
+        add_configuration_file(routes)
+      end
+      load_routes_without_headword!
+    end
+
+    alias_method_chain :load_routes!, :headword
+  end
+end

data/lib/headword/user.rb

@@ -0,0 +1,63 @@
+module Headword
+  module User
+
+    # Hook for all Headword::User modules.
+    #
+    # If you need to override parts of Headword::User
+    # extend and include à la carte.
+    #
+    # @example
+    #   extend ClassMethods
+    #   include InstanceMethods
+    #   include AttrAccessor
+    #   include Callbacks
+    #
+    # @see ClassMethods
+    # @see InstanceMethods
+    # @see Validations
+    # @see Scopes
+    # @see Callbacks
+    def self.included(model)
+      model.extend(ClassMethods)
+      model.send(:include, InstanceMethods)
+      model.send(:include, Validations)
+      model.send(:include, Callbacks)
+    end
+
+    module Validations
+      # Hook for validations.
+      #
+      # :username must be present and unique
+      # :url must be unique
+      def self.included(model)
+        model.class_eval do
+          validates_presence_of :username
+          validates_uniqueness_of :username
+          validates_uniqueness_of :url
+        end
+      end
+    end
+
+    module Callbacks
+      # Hook for callbacks.
+      #
+      # :title should act like a url.
+      def self.included(model)
+        model.class_eval do
+          acts_as_url :username, :sync_url => true
+          attr_accessible :username
+        end
+      end
+    end
+
+    module InstanceMethods
+      # We want to use username urls instead of ids in our routes
+      def to_param
+        url
+      end
+    end  
+
+    module ClassMethods
+    end
+  end
+end

data/rails/init.rb

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

data/test/controllers/users_controller_test.rb

@@ -0,0 +1,70 @@
+require 'test_helper'
+require File.expand_path(File.dirname(__FILE__) + "/../rails/test/factories/headword")
+
+class UsersControllerTest < ActionController::TestCase
+
+  tests Headword::UsersController
+
+  context "default setup" do
+    context "on show existing user" do
+      setup do
+        user = Factory(:user_with_username)
+        get :show, :username => user.url
+      end  
+
+      should_respond_with :success
+      should_render_template :show
+      should_not_set_the_flash
+    end
+
+    context "on show unknown user" do
+      setup do
+        user = Factory(:user_with_username)
+      end  
+
+      should "not find an unknown user" do
+        begin
+          get :show, :username => 'turnbuckle-turnbuckle'
+          flunk "Should raise ActiveRecord::RecordNotFound"
+        rescue ActiveRecord::RecordNotFound
+        end
+      end  
+    end
+  end
+
+  context "routes" do
+  
+    should "recognize usernames" do
+      assert_recognizes({:controller => 'headword/users', :action => 'show', :username => 'marymary'}, {:path => '/marymary', :method => :get})
+    end  
+
+    should "not recognize things that are not usernames" do
+      assert_does_not_recognize('/mary/jane', :method => :get)
+    end
+    
+    should "recognize the root path" do
+      assert_recognizes({:controller => 'things', :action => 'index'}, {:path => '/', :method => :get})
+    end
+    
+    should "not override the things" do
+      assert_recognizes({:controller => 'things', :action => 'index'}, {:path => '/things', :method => :get})
+      assert_recognizes({:controller => 'things', :action => 'new'}, {:path => '/things/new', :method => :get})
+      assert_recognizes({:controller => 'things', :action => 'create'}, {:path => '/things', :method => :post})
+      assert_recognizes({:controller => 'things', :id => '1', :action => 'destroy'}, {:path => '/things/1', :method => :delete})
+      assert_recognizes({:controller => 'things', :id => '1', :action => 'update'}, {:path => '/things/1', :method => :put})
+      assert_recognizes({:controller => 'things', :id => '1', :action => 'edit'}, {:path => '/things/1/edit', :method => :get})
+    end
+
+    if defined?(Clearance)
+      should "not override clearance paths" do
+        assert_recognizes({:controller => 'sessions', :action => 'new'}, {:path => '/session/new', :method => :get})
+      end
+    end  
+  end
+  
+  def assert_does_not_recognize(path, options)
+    assert_raises(ActionController::RoutingError) do
+      ActionController::Routing::Routes.recognize_path(path, options)
+    end
+  end  
+end

data/test/models/user_test.rb

@@ -0,0 +1,15 @@
+require File.dirname(__FILE__) + '/../test_helper'
+require File.expand_path(File.dirname(__FILE__) + "/../rails/test/factories/headword")
+ 
+class UserTest < ActiveSupport::TestCase
+  should_allow_mass_assignment_of :username
+  
+  context "When signing up" do
+    should_validate_presence_of :username
+  end
+  
+  context "When multiple users have signed up" do
+    setup { @user = Factory(:user_with_username) }    
+    should_validate_uniqueness_of :username
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,18 @@
+ENV["RAILS_ENV"] = "test"
+require File.expand_path(File.dirname(__FILE__) + "/rails/config/environment")
+require 'test_help'
+require 'factory_girl'
+require 'shoulda'
+
+if defined?(Clearance)
+  require 'clearance/../../shoulda_macros/clearance'
+end
+
+# Name the root_url for testing
+ActionController::Routing::Routes.add_named_route('root', '/', :controller => 'things', :action => 'index')
+
+class ActiveSupport::TestCase
+  self.use_transactional_fixtures = true
+  self.use_instantiated_fixtures  = false
+  fixtures :all
+end

metadata

@@ -0,0 +1,90 @@
+--- !ruby/object:Gem::Specification 
+name: headword
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Jeff Rafter
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-09-08 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rsl-stringex
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.0.2
+    version: 
+description: Simplify adding usernames to your application.
+email: jeff@socialrange.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.textile
+files: 
+- CHANGELOG.textile
+- LICENSE
+- README.textile
+- Rakefile
+- TODO.textile
+- TUTORIAL.textile
+- VERSION
+- app/controllers/headword/users_controller.rb
+- config/headword_routes.rb
+- generators/headword/USAGE
+- generators/headword/headword_generator.rb
+- generators/headword/templates/README
+- generators/headword/templates/factories.rb
+- generators/headword/templates/migrations/create_users.rb
+- generators/headword/templates/migrations/update_users.rb
+- generators/headword/templates/show.html.erb
+- generators/headword/templates/user.rb
+- lib/headword.rb
+- lib/headword/extensions/routes.rb
+- lib/headword/user.rb
+- rails/init.rb
+- test/controllers/users_controller_test.rb
+- test/models/user_test.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: http://github.com/jeffrafter/headword
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.4
+signing_key: 
+specification_version: 3
+summary: When your users are that vain.
+test_files: 
+- test/controllers/users_controller_test.rb
+- test/models/user_test.rb
+- test/test_helper.rb