kealy_cheese 0.3.0

data/README.rdoc

@@ -0,0 +1,56 @@
+== Overview
+
+One of the things I was most looking forward to in rails 3 was the plugin / engine architecture. Recently, I sat down to figure out how to create my first engine and package it up as a gem and it took me awhile of time just to get the structure of the engine setup. It's missing a lot of the "rails" you get in a normal rails app.
+
+In it's simplest form engines are quite easy, however for a full-featured engine (such as creating a forum) there are a lot of extras that you're going to want. These are the things I spent time figuring out that I've packaged up into an easy starting point:
+
+* Namespacing models & controllers so they don't collide with those in the main app
+* Creating a global layout within your engine that gets nested within your application layout
+* Generating migrations from your engine
+* Creating an "acts_as_[plugin]" declaration for use inside your main app's models
+* Easy plugin configuration file editable from main app directory
+* Rake tasks within engine
+* Writing tests for models complete with fixtures
+* Serving static assets within engine
+* Packaging and distributing as a gem
+* Code is here - I've created an engine stub that has all the things setup for you already. I want to see a lot more rails 3 engines get created, I hope this helps! I'd love to hear feedback from you if you try it out.
+
+Here’s how you get ready to create your first gem by using this starting point:
+
+* git clone http://github.com/krschacht/rails_3_engine_demo.git
+* cd rails_3_engine_demo
+* [edit test/database.yml]
+* rake test (this will initialize your test database and run the basic test suite)
+
+Now, create a plain rails app and set it up to use your engine. FYI: even though the engine's directory is 'rails_3_engine_demo', internally the engine is named 'cheese'
+
+* cd .. [ this is to take you outside the 'rails_3_engine_demo' directory that was created above' ]
+* rails new demo_app_to_use_gem -d mysql
+* cd demo_app_to_use_gem
+* [edit config/database.yml]
+* [edit Gemfile, add line: ] gem ‘cheese’, :path => "../rails_3_engine_demo"
+* rails generate cheese
+* [examine config/initializers/cheese.rb to see basic config parameters]
+* rake db:create
+* rake db:migrate (one of the migrations that you'll see run came from the engine)
+
+You have now setup a empty rails app that utilizes your engine. To test out the functionality, startup the demo app’s webserver:
+
+* rails server
+* Then visit: http://localhost:3000/cheese (this is a controller included within the engine)
+* Watch the server logs as you're viewing this page and you'll see some output which is coming from an application before_filter which is executing from inside the engine (in lib/application_controller.rb)
+* rake cheese:report (this is a a rake task that is included inside the engine)
+
+Lastly, let's package up your engine as a real gem. You’ll need Jeweler installed for this:
+
+* cd rails_3_engine_demo
+* sudo gem install jeweler
+* rake gemspec
+* rake build
+* rake install (you have now installed your engine as a gem locally)
+* [ At this point if you wanted your demo app to use your installed gem, edit the Gemfile in your demo app and remove the 'path' option from your gem line. It should look like this: ] gem ‘cheese’
+* rake gemcutter:release (this pushes your gem up to Gemcutter, a public gem repository)
+
+Now you’re ready to start customizing this engine for your own purposes. Do a global find in your engine directory and replace every instance of "cheese" and "Cheese" with your engine name (be sure to preserve capitalization). Likewise, rename every directory and file that’s named "cheese" with your engine name. I should really automate this but I haven’t figured out how to create a rake task that I can run from within the engine directory itself.
+
+P.S. Special thanks to Chrispy for helping figure out the application_controller includes!

data/app/controllers/cheese/widgets_controller.rb

@@ -0,0 +1,15 @@
+module Cheese
+  class WidgetsController < ApplicationController
+
+    unloadable
+    
+    layout 'cheese'  # this allows you to have a gem-wide layout
+    
+    def index
+    end
+    
+    def show
+    end
+    
+  end
+end

data/app/helpers/application_helper.rb

@@ -0,0 +1,2 @@
+## Look in lib/application_helper.rb
+## I can't figure out how to get it included unless I put it that directory

data/app/helpers/cheese/widgets_helper.rb

@@ -0,0 +1,9 @@
+module Cheese
+  module WidgetsHelper
+  
+    def helper_for_widgets_view
+      "this output is coming from a helper method just for the widgets controller"
+    end
+    
+  end
+end

data/app/models/cheese/widget.rb

@@ -0,0 +1,10 @@
+module Cheese
+  class Widget < ActiveRecord::Base
+    set_table_name "cheese_widgets"
+
+    def make
+      puts "widget made"
+    end
+    
+  end
+end

data/app/views/cheese/widgets/index.html.erb

@@ -0,0 +1,9 @@
+widget#index<br>
+<br>
+The red border is from a layout within the engine which is nested within your application layout<br>
+<br>
+<%= helper_for_widgets_view %><br>
+<br>
+<%= app_wide_helper_method %><br><br>
+This image is being served from the public directory contained within the engine:
+<%= image_tag "cheese.jpg" %>

data/app/views/cheese/widgets/show.html.erb

@@ -0,0 +1 @@
+widgets#show

data/app/views/layouts/cheese.html.erb

@@ -0,0 +1,12 @@
+
+<% content_for :content do %>
+
+  <%= stylesheet_link_tag("cheese") %>
+  
+  <div class="red_border">
+    <%= yield %>
+  </div>
+
+<% end -%>
+
+<%= render :file => 'layouts/application' %>

data/config/routes.rb

@@ -0,0 +1,12 @@
+Rails.application.routes.draw do |map|
+
+  mount_at = Cheese::Engine.config.mount_at
+
+  match mount_at => 'cheese/widgets#index'
+
+  map.resources :widgets, :only => [ :index, :show ],
+                          :controller => "cheese/widgets",
+                          :path_prefix => mount_at,
+                          :name_prefix => "cheese_"
+
+end

data/lib/acts_as_widget/base.rb

@@ -0,0 +1,36 @@
+module Cheese
+  module ActsAsWidget
+
+    ## Define ModelMethods
+    module Base
+      def self.included(klass)
+        klass.class_eval do
+          extend Config
+        end
+      end
+      
+      module Config
+        def acts_as_widget
+        
+          # This is where arbitrary code goes that you want to 
+          # add to the class that declared "acts_as_widget"
+          
+          has_many :widgets,  :class_name => 'Cheese::Widget'
+
+          include Cheese::ActsAsWidget::Base::InstanceMethods
+        end
+      end
+      
+      module InstanceMethods
+        
+        def factory_name
+          "this is an example instance method"
+        end
+                
+      end # InstanceMethods      
+    end
+
+  end
+end
+
+::ActiveRecord::Base.send :include, Cheese::ActsAsWidget::Base

data/lib/application_helper.rb

@@ -0,0 +1,7 @@
+module ApplicationHelper
+  
+  def app_wide_helper_method
+    "this output is from an app-wide helper method that is declared within the gem"
+  end
+  
+end

data/lib/cheese.rb

@@ -0,0 +1,5 @@
+module Cheese
+  require 'engine' if defined?(Rails) && Rails::VERSION::MAJOR == 3
+  require 'acts_as_widget/base'
+  require 'application_controller'
+end

data/lib/engine.rb

@@ -0,0 +1,30 @@
+require 'cheese'
+require 'rails'
+require 'action_controller'
+require 'application_helper'
+
+module Cheese
+  class Engine < Rails::Engine
+
+    # Config defaults
+    config.widget_factory_name = "default factory name"
+    config.mount_at = '/'
+    
+    # Load rake tasks
+    rake_tasks do
+      load File.join(File.dirname(__FILE__), 'rails/railties/tasks.rake')
+    end
+    
+    # Check the gem config
+    initializer "check config" do |app|
+
+      # make sure mount_at ends with trailing slash
+      config.mount_at += '/'  unless config.mount_at.last == '/'
+    end
+    
+    initializer "static assets" do |app|
+      app.middleware.use ::ActionDispatch::Static, "#{root}/public"
+    end
+    
+  end
+end

data/lib/rails/generators/cheese/cheese_generator.rb

@@ -0,0 +1,75 @@
+require 'rails/generators'
+require 'rails/generators/migration'
+
+class CheeseGenerator < Rails::Generators::Base
+  include Rails::Generators::Migration
+
+  def self.source_root
+    File.join(File.dirname(__FILE__), 'templates')
+  end
+   
+  def self.next_migration_number(dirname) #:nodoc:
+    if ActiveRecord::Base.timestamped_migrations
+      Time.now.utc.strftime("%Y%m%d%H%M%S")
+    else
+      "%.3d" % (current_migration_number(dirname) + 1)
+    end
+  end
+
+
+  # Every method that is declared below will be automatically executed when the generator is run
+  
+  def create_migration_file
+    f = File.open File.join(File.dirname(__FILE__), 'templates', 'schema.rb')
+    schema = f.read; f.close
+    
+    schema.gsub!(/ActiveRecord::Schema.*\n/, '')
+    schema.gsub!(/^end\n*$/, '')
+
+    f = File.open File.join(File.dirname(__FILE__), 'templates', 'migration.rb')
+    migration = f.read; f.close
+    migration.gsub!(/SCHEMA_AUTO_INSERTED_HERE/, schema)
+    
+    tmp = File.open "tmp/~migration_ready.rb", "w"
+    tmp.write migration
+    tmp.close
+
+    migration_template  '../../../tmp/~migration_ready.rb',
+                        'db/migrate/create_cheese_tables.rb'
+    remove_file 'tmp/~migration_ready.rb'
+  end
+
+  def copy_initializer_file
+    copy_file 'initializer.rb', 'config/initializers/cheese.rb'
+  end
+
+  def update_application_template
+    f = File.open "app/views/layouts/application.html.erb"
+    layout = f.read; f.close
+    
+    if layout =~ /<%=[ ]+yield[ ]+%>/
+      print "    \e[1m\e[34mquestion\e[0m  Your layouts/application.html.erb layout currently has the line <%= yield %>. This gem needs to change this line to <%= content_for?(:content) ? yield(:content) : yield %> to support its nested layouts. This change should not affect any of your existing layouts or views. Is this okay? [y/n] "
+      begin
+        answer = gets.chomp
+      end while not answer =~ /[yn]/i
+      
+      if answer =~ /y/i
+        
+        layout.gsub!(/<%=[ ]+yield[ ]+%>/, '<%= content_for?(:content) ? yield(:content) : yield %>')
+
+        tmp = File.open "tmp/~application.html.erb", "w"
+        tmp.write layout; tmp.close
+
+        remove_file 'app/views/layouts/application.html.erb'
+        copy_file '../../../tmp/~application.html.erb', 
+                  'app/views/layouts/application.html.erb'
+        remove_file 'tmp/~application.html.erb'
+      end
+    elsif layout =~ /<%=[ ]+content_for\?\(:content\) \? yield\(:content\) : yield[ ]+%>/
+      puts "    \e[1m\e[33mskipping\e[0m  layouts/application.html.erb modification is already done."
+    else
+      puts "    \e[1m\e[31mconflict\e[0m  The gem is confused by your layouts/application.html.erb. It does not contain the default line <%= yield %>, you may need to make manual changes to get this gem's nested layouts working. Visit ###### for details."
+    end
+  end
+  
+end

data/lib/rails/generators/cheese/templates/initializer.rb

@@ -0,0 +1,8 @@
+module Cheese
+  class Engine < Rails::Engine
+
+    config.mount_at = '/cheese'
+    config.widget_factory_name = 'Factory Name'
+        
+  end
+end

data/lib/rails/generators/cheese/templates/migration.rb

@@ -0,0 +1,9 @@
+class CreateCheeseTables < ActiveRecord::Migration
+  def self.up
+    SCHEMA_AUTO_INSERTED_HERE
+  end
+
+  def self.down
+    drop_table :cheese_widgets
+  end
+end

data/lib/rails/generators/cheese/templates/schema.rb

@@ -0,0 +1,11 @@
+ActiveRecord::Schema.define(:version => 0) do
+
+    create_table :cheese_widgets, :force => true do |t|
+      t.string    :title
+      t.datetime  :created_at
+      t.datetime  :updated_at
+    end
+
+    add_index :cheese_widgets, [:title]
+
+end

data/lib/rails/railties/tasks.rake

@@ -0,0 +1,8 @@
+namespace :cheese do
+  
+  desc "example gem rake task"
+  task :report => :environment do
+    puts "you just ran the example gem rake task"
+  end
+
+end

data/public/stylesheets/cheese.css

@@ -0,0 +1,9 @@
+.cheese {
+  color: red;
+}
+
+.red_border {
+  border: 2px solid red;
+  margin: 5px;
+  padding: 5px;
+}

data/test/test_helper.rb

@@ -0,0 +1,56 @@
+ENV["RAILS_ENV"] = "test"
+
+require 'test/unit'
+require 'rubygems'
+require 'yaml'
+require 'active_record'
+require 'mysql'
+
+require 'app/models/cheese/widget.rb'
+
+def cheese_widget( fixture_name )
+  id = @@fixtures['cheese_widget'][ fixture_name.to_s ][ 'id' ]
+  Cheese::Widget.find( id )
+end
+
+def load_schema
+  config = YAML::load( IO.read( File.dirname(__FILE__) + '/database.yml') )
+
+  # Manually initialize the database
+  conn = Mysql.real_connect( config['mysql']['host'], config['mysql']['username'], config['mysql']['password'] )
+  conn.query( "CREATE DATABASE IF NOT EXISTS #{config['mysql']['database']}" )
+  
+  ActiveRecord::Base.establish_connection( config['mysql'] )
+  ActiveRecord::Base.connection()
+  
+  load(File.dirname(__FILE__) + "/../" +
+    "lib/rails/generators/cheese/templates/schema.rb")
+
+  @@fixtures = {}
+  
+  load_fixture( 'cheese_widget' )
+end
+
+def load_fixture( table )
+  @@fixtures[ table ] = {}
+  fixture = YAML::load( IO.read( File.dirname(__FILE__) + "/fixtures/#{table}.yml") )
+  @@fixtures[ table ] = fixture
+
+  klass = class_eval table.titleize.gsub(/ /, '::')
+
+  fixture.each do |record_name, record|
+    record.each do |column, value|
+      if ( match = column.match(/(.*)_id/) )
+        fixture_reference = "cheese_" + match[1].pluralize
+        if value.is_a? Symbol
+          r = class_eval "#{fixture_reference}( '#{value}' )"
+          record[ column ] = r.id
+        end
+      end
+    end
+      
+    r = klass.create( record )
+    @@fixtures[ table ][ record_name ][ 'id' ] = r.id
+  end
+
+end

data/test/unit/widget_test.rb

@@ -0,0 +1,11 @@
+require 'test_helper'
+
+class WidgetTest < Test::Unit::TestCase
+  load_schema
+
+  def test_fixtures_are_working
+    assert_equal cheese_widget(:first).title, "This is the title"
+  end
+  
+    
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification 
+name: kealy_cheese
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.3.0
+platform: ruby
+authors: 
+- John Kealy
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-09-13 00:00:00 Z
+dependencies: []
+
+description: 
+email: you@email.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- app/controllers/cheese/widgets_controller.rb
+- app/helpers/application_helper.rb
+- app/helpers/cheese/widgets_helper.rb
+- app/models/cheese/widget.rb
+- app/views/cheese/widgets/index.html.erb
+- app/views/cheese/widgets/show.html.erb
+- app/views/layouts/cheese.html.erb
+- config/routes.rb
+- lib/acts_as_widget/base.rb
+- lib/application_helper.rb
+- lib/cheese.rb
+- lib/engine.rb
+- lib/rails/generators/cheese/cheese_generator.rb
+- lib/rails/generators/cheese/templates/initializer.rb
+- lib/rails/generators/cheese/templates/migration.rb
+- lib/rails/generators/cheese/templates/schema.rb
+- lib/rails/railties/tasks.rake
+- public/images/cheese.jpg
+- public/stylesheets/cheese.css
+- README.rdoc
+- test/test_helper.rb
+- test/unit/widget_test.rb
+homepage: 
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.5
+signing_key: 
+specification_version: 3
+summary: Description of your gem
+test_files: 
+- test/test_helper.rb
+- test/unit/widget_test.rb