has_many_through_generator 0.4.0

data/CHANGELOG

@@ -0,0 +1,3 @@
+1.0.0 ==========
+
+* Initial release of generator

data/HOWTO

@@ -0,0 +1,473 @@
+By Dr Nic
+
+If you want a model, a migration file, and a unit test file, you use the <tt>model</tt> generator.
+So if your object model consists of <tt>users</tt> and <tt>groups</tt>, with a <tt>memberships</tt>
+table in the middle to represent the many-to-many relationship, you have to do the following:
+
+1. <tt>ruby script/generate model User</tt>  -- generates user.rb, 001_create_user.rb, user_test.rb
+1. <tt>ruby script/generate model Group</tt>  -- generates group.rb, 002_create_group.rb, group_test.rb
+1. <tt>ruby script/generate model Membership</tt>  -- generates membership.rb, 003_create_membership.rb, membership_test.rb
+1. Add foreign keys to 003_create_membership.rb:
+  * <tt>t.add_column :group_id, :integer</tt>
+  * <tt>t.add_column :user_id, :integer</tt>
+1. Add belongs_to to Membership class, in membership.rb:
+  * <tt>belongs_to :group</tt>
+  * <tt>belongs_to :user</tt>
+1. Add has_manys to User class, in user.rb:
+  * <tt>has_many :memberships</tt>
+  * <tt>has_many :groups, :through => :memberships</tt>
+1. Repeat for Group class, in group.rb:
+  * <tt>has_many :memberships</tt>
+  * <tt>has_many :users, :through => :memberships</tt>
+1. Run migration to create the tables in your database:
+  * <tt>rake migrate</tt>
+
+In a few minutes you have created your tables in the database, and setup your model classes
+to reference each other. Lovely.
+
+And then you start to write test cases to make sure everything is hunky doory. Even if you have
+some similar code lying around it'll take an hour or more to refactor it for your new classes.
+
+If your a new Rails programmer, you probably don't have any similar code nor do you know
+what test cases to add to your unit tests.
+
+I became so sick of this process that I wrote a new generator - similar to <tt>model</tt>, 
+<tt>controller</tt>, and <tt>scaffold</tt> - to generate all the code above and
+a set of unit tests to show that its all stuck together nicely.
+
+Below is a tutorial for how to:
+* install the generator
+* generate code for two new models and the many-to-many model
+* generate code where one of the models already exists in your application
+
+Create a new Rails application for the tutorial
+<pre>
+\> rails hmt_tutorial
+      create
+      create  app/controllers
+      create  app/helpers
+      create  app/models
+      create  app/views/layouts
+      ...etc...
+> cd hmt_tutorial
+</pre>
+
+To install the generator run the following:
+<pre>
+> gem install hasmanythrough
+</pre>
+
+To create our User, Group and Membership models and tests:
+<pre>
+> ruby script/generate has_many_through User Group Membership
+      exists  app/models/
+      exists  test/unit/
+      exists  test/fixtures/
+      create  app/models/group.rb
+      create  test/unit/group_test.rb
+      create  test/fixtures/groups.yml
+      create  db/migrate
+      create  db/migrate/001_create_groups.rb
+      create  app/models/user.rb
+      create  test/unit/user_test.rb
+      create  test/fixtures/users.yml
+      exists  db/migrate
+      create  db/migrate/002_create_users.rb
+      create  app/models/membership.rb
+      create  test/unit/membership_test.rb
+      create  test/fixtures/memberships.yml
+      exists  db/migrate
+      create  db/migrate/003_create_memberships.rb
+</pre>
+
+The generator command is <tt>has_many_through</tt> and requires 2 parameters:
+the two class names for your two models, which is User and Group. 
+The 3rd parameter is optional: the explicit name of the many-to-many model, 
+which is Membership in this example. A later example will show what
+happens if you omit to name the many-to-many model.
+
+The generated code for the Group class is:
+<pre>
+class Group < ActiveRecord::Base
+  has_many :memberships
+  has_many :users, :through => :memberships
+end
+</pre>
+
+It includes the relationships to the other two classes. The User class will look similar,
+but with a <tt>has_many :groups, :through => :memberships</tt> statement.
+
+The generated code for the Membership class is:
+<pre>
+class Membership < ActiveRecord::Base
+  belongs_to :group
+  belongs_to :user
+  
+  validates_presence_of :group_id, :user_id
+  validates_uniqueness_of :group_id, :scope => :user_id
+  validates_uniqueness_of :user_id, :scope => :group_id
+end
+</pre>
+
+It includes the two belongs_to statements to the primary models, and also includes
+some validation. A user would never expect to see the error messages from
+these validations - there isn't much a user can do if your controller code
+doesn't correctly create Membership objects - but it will ensure that the
+database relationships are correct. 
+
+The two <tt>validates_uniqueness_of</tt> exist to ensure that there is only
+one Membership object for any [User, Group] pair. If your application
+allows for duplicates, then remove these two statements.
+
+Before we create the database tables using migrations, you'll want to add some useful
+fields to the User and Group tables.
+
+In 001_create_groups.rb, update the self.up method:
+<pre>
+  def self.up
+    create_table :groups do |t|
+      t.column :name, :string
+    end
+  end
+</pre>
+
+In 002_create_users.rb, also update the self.up method:
+<pre>
+  def self.up
+    create_table :users do |t|
+      t.column :firstname, :string
+      t.column :lastname, :string
+      t.column :email, :string
+    end
+  end
+</pre>
+
+No changes are required to the memberships table (unless you want to add
+additional fields in your model):
+<pre>
+  def self.up
+    create_table :memberships do |t|
+      t.column :group_id, :integer
+      t.column :user_id, :integer
+    end
+  end
+</pre>
+
+To setup your database (mysql example given):
+<pre>
+> mysql -u root
+mysql> create database hmt_tutorial_development;
+Query OK, 1 row affected (0.06 sec)
+
+mysql> create database hmt_tutorial_test;
+Query OK, 1 row affected (0.00 sec)
+
+mysql> create database hmt_tutorial_production;
+Query OK, 1 row affected (0.00 sec)
+
+mysql> exit
+</pre>
+
+You can now run migrations:
+<pre>
+> rake migrate
+== CreateGroups: migrating ====================================================
+-- create_table(:groups)
+   -> 0.0780s
+== CreateGroups: migrated (0.0780s) ===========================================
+
+== CreateUsers: migrating =====================================================
+-- create_table(:users)
+   -> 0.0780s
+== CreateUsers: migrated (0.0780s) ============================================
+
+== CreateMemberships: migrating ===============================================
+-- create_table(:memberships)
+   -> 0.1100s
+== CreateMemberships: migrated (0.1100s) ======================================
+</pre>
+
+Now you can run the unit tests:
+<pre>
+> rake test:units
+Started
+......................
+Finished in 0.484 seconds.
+
+22 tests, 33 assertions, 0 failures, 0 errors
+</pre>
+
+Huzzah! You've got 22 tests and 33 successful assertions.
+
+Before we look at the generated test code, let's break it. Make the email attribute required for
+all Users, and also unique so no two Users can have the same email address.
+
+<pre>
+class User < ActiveRecord::Base
+  has_many :memberships
+  has_many :groups, :through => :memberships
+  
+  validates_presence_of :email
+  validates_uniqueness_of :email
+end
+</pre>
+
+And the tests should hopefully break:
+<pre>
+> rake test:units
+Started
+..................FF..
+Finished in 0.641 seconds.
+
+  1) Failure:
+test_new(UserTest) [./test/unit/user_test.rb:28]:
+User should be valid.
+<false> is not true.
+
+  2) Failure:
+test_raw_validation(UserTest) [./test/unit/user_test.rb:18]:
+User should be valid without initialisation parameters.
+<false> is not true.
+
+22 tests, 33 assertions, 2 failures, 0 errors
+</pre>
+
+We need to update the unit test for User to consider the required email field.
+The user_test.rb file starts with something like this:
+
+<pre>
+class UserTest < Test::Unit::TestCase
+  fixtures :users, :groups, :memberships
+
+  NEW_USER = {}	# e.g. {:name => 'Test User', :description => 'Dummy'}
+  REQ_ATTR_NAMES 			 = %w( ) # name of fields that must be present, e.g. %(name description)
+  DUPLICATE_ATTR_NAMES = %w( ) # name of fields that cannot be a duplicate, e.g. %(name description)
+
+  def test_raw_validation
+    user = User.new
+    if REQ_ATTR_NAMES.blank?
+      assert user.valid?, "User should be valid without initialisation parameters"
+    else
+      # If User has validation, then use the following:
+      assert !user.valid?, "User should not be valid without initialisation parameters"
+      REQ_ATTR_NAMES.each {|attr_name| assert user.errors.invalid?(attr_name.to_sym), "Should be an error message for :#{attr_name}"}
+    end
+  end
+</pre>
+
+The constants NEW_USER, REQ_ATTR_NAMES, and DUPLICATE_ATTR_NAMES need to
+be set by you to match your class's validation requirements.
+Let's change these three lines to:
+
+<pre>
+	NEW_USER = {:firstname => 'Test', :lastname => 'Person', :email => 'test@person.com'}	# e.g. {:name => 'Test User', :description => 'Dummy'}
+	REQ_ATTR_NAMES 			 = %w( email ) # name of fields that must be present, e.g. %(name description)
+	DUPLICATE_ATTR_NAMES = %w( email ) # name of fields that cannot be a duplicate, e.g. %(name description)
+</pre>
+
+And run the tests again:
+
+<pre>
+> rake test:units
+Started
+......................
+Finished in 0.625 seconds.
+
+22 tests, 41 assertions, 0 failures, 0 errors
+</pre>
+
+More assertions were tested this time to check the required and unique fields (email).
+Now, a raw User.new object will be invalid, where as initially it was assumed to be valid.
+
+
+The last step of this tutorial is to create another many-to-many model pair where
+one of the classes already exists in the application. Let's consider we need
+<tt>users</tt> and <tt>forums</tt>, and we need a many-to-many table as well,
+but we don't care what its called.
+
+<pre>
+> ruby script/generate has_many_through User Forum
+      exists  app/models/
+      exists  test/unit/
+      exists  test/fixtures/
+      create  app/models/forum.rb
+      create  test/unit/forum_test.rb
+      create  test/fixtures/forums.yml
+      exists  db/migrate
+      create  db/migrate/004_create_forums.rb
+overwrite app/models/user.rb? [Ynaq] y
+       force  app/models/user.rb
+overwrite test/unit/user_test.rb? [Ynaq] y
+       force  test/unit/user_test.rb
+   identical  test/fixtures/users.yml
+      exists  db/migrate
+Skipping migration create_users, as already exists: db/migrate/002_create_users.rb
+      create  app/models/forum_user.rb
+      create  test/unit/forum_user_test.rb
+      create  test/fixtures/forum_users.yml
+      exists  db/migrate
+      create  db/migrate/005_create_forum_users.rb
+</pre>
+
+The generator does a number of things of interest:
+1. Automatically names your many-to-many table forum_users, and the class ForumUser.
+1. Skips the generation of the create_users migration as one already exists
+1. Allows you to re-create the user.rb and user_test.rb files to support
+the new relationships.
+
+During the process we regenerated both the user.rb and user_test.rb files. This probably
+wasn't clever as we lost our email validations and our unit test changes.
+
+But before we add those changes back, let's run the migration and unit tests:
+
+<pre>
+> rake migration
+== CreateForums: migrating ====================================================
+-- create_table(:forums)
+   -> 0.1090s
+== CreateForums: migrated (0.1090s) ===========================================
+
+== CreateForumUsers: migrating ================================================
+-- create_table(:forum_users)
+   -> 0.1090s
+== CreateForumUsers: migrated (0.1090s) =======================================
+
+> rake test:units
+Started
+............................E........
+Finished in 0.937 seconds.
+
+  1) Error:
+test_user_to_memberships(MembershipTest):
+NoMethodError: undefined method `memberships' for #<User:0x3b3bea8>
+    D:/InstantRails-1.0/ruby/lib/ruby/gems/1.8/gems/activerecord-1.14.3/lib/active_record/base.rb:1792:in `method_missing'
+    ./test/unit/membership_test.rb:64:in `test_user_to_memberships'
+
+37 tests, 56 assertions, 0 failures, 1 errors
+</pre>
+
+Our units test - which should work straight out-of-the-box - have failed. The Membership unit test,
+from the first example, which used to pass now fails.
+
+The failing test method is:
+<pre>
+	def test_user_to_memberships
+    assert_not_nil users(:first).memberships, "User.memberships should not be nil"
+    assert_equal Membership, users(:first).memberships[0].class, "User.memberships should be an array of Membership"
+    assert_equal 1, users(:first).memberships.length, "Incorrect number of Membership"
+	end
+</pre>
+
+Line 64 is the first line of the method. Apparently our User class no longer has
+a memberships method?! Aah... we must have lost it too when we re-generated the
+User class above.
+
+Our User class now looks like:
+
+<pre>
+class User < ActiveRecord::Base
+  has_many :forum_users
+  has_many :forums, :through => :forum_users
+end
+</pre>
+
+And needs to include the <tt>has_many</tt>s from the Group example, plus our
+missing validations.
+
+<pre>
+class User < ActiveRecord::Base
+  has_many :forum_users
+  has_many :forums, :through => :forum_users
+  has_many :memberships
+  has_many :groups, :through => :memberships
+  
+  validates_presence_of :email
+  validates_uniqueness_of :email
+end
+</pre>
+
+Running the unit tests:
+
+<pre>
+Started
+.................................FF..
+Finished in 0.938 seconds.
+
+  1) Failure:
+test_new(UserTest) [./test/unit/user_test.rb:28]:
+User should be valid.
+<false> is not true.
+
+  2) Failure:
+test_raw_validation(UserTest) [./test/unit/user_test.rb:18]:
+User should be valid without initialisation parameters.
+<false> is not true.
+
+37 tests, 59 assertions, 2 failures, 0 errors
+</pre>
+
+Damn. Our validation errors are back. Let's re-add the user_test.rb requirement
+and uniqueness details again:
+
+<pre>
+	NEW_USER = {:firstname => 'Test', :lastname => 'Person', :email => 'test@person.com'}	# e.g. {:name => 'Test User', :description => 'Dummy'}
+	REQ_ATTR_NAMES 			 = %w( email ) # name of fields that must be present, e.g. %(name description)
+	DUPLICATE_ATTR_NAMES = %w( email ) # name of fields that cannot be a duplicate, e.g. %(name description)
+</pre>
+
+And run the tests again:
+
+<pre>
+> rake test:units
+Started
+.....................................
+Finished in 0.938 seconds.
+
+37 tests, 67 assertions, 0 failures, 0 errors
+</pre>
+
+Now we have 67 happy assertions.
+
+But wait! There is something missing still. The has_many_through generator
+can generate new files but cannot insert code/text into existing files.
+When we regenerated our user_test.rb file, there were 3 test methods
+associated with the Membership and Group classes that were lost.
+
+By looking at the last 3 methods of the user_test.rb file for
+Forum and ForumUser, we can recreate the Group and Membership tests.
+
+Add the following to your user_test.rb file:
+
+<pre>
+  def test_memberships_to_user
+    assert_equal users(:first), Membership.find_first.user, "Membership.user should be a User"
+	end
+	
+	def test_user_to_memberships
+    assert_not_nil users(:first).memberships, "User.users should not be nil"
+    assert_equal Membership, users(:first).memberships[0].class, "User.memberships should be an array of Membership"
+	end
+	
+	def test_groups
+    assert_not_nil users(:first).groups, "User.groups should not be nil"
+    assert_equal Group, users(:first).groups[0].class, "User.groups should be an array of Group"
+	end
+</pre>
+
+And run the tests for the final time:
+
+<pre>
+Started
+........................................
+Finished in 1.0 seconds.
+
+40 tests, 72 assertions, 0 failures, 0 errors
+</pre>
+
+Lovely.
+
+It is now very easy to start your Rails apps or extend your old apps with common
+many-to-many relationships using the has_many_through generator, and you
+get a whole bunch of unit tests for free.
+
+Cheap at half the price.