From 86125a444857ad9c54285894961bffe296a40055 Mon Sep 17 00:00:00 2001
From: Joshua Clayton <jclayton@thoughtbot.com>
Date: Fri, 12 Aug 2011 15:25:58 -0400
Subject: [PATCH] Document attribute groups

---
 GETTING_STARTED.md | 72 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)

diff --git a/GETTING_STARTED.md b/GETTING_STARTED.md
index f83d633..11196f5 100644
--- a/GETTING_STARTED.md
+++ b/GETTING_STARTED.md
@@ -259,6 +259,78 @@ Without a block, the value will increment itself, starting at its initial value:
       sequence(:position)
     end
 
+Attribute Groups
+----------------
+
+Attribute groups allow you to group attributes together and then apply them
+to any factory.
+
+    factory :user, :aliases => [:author]
+
+    factory :story do
+      title "My awesome story"
+      author
+
+      attribute_group :published do
+        published true
+      end
+
+      attribute_group :unpublished do
+        published false
+      end
+
+      attribute_group :week_long_publishing do
+        start_at { 1.week.ago }
+        end_at   { Time.now }
+      end
+
+      attribute_group :month_long_publishing do
+        start_at { 1.month.ago }
+        end_at   { Time.now }
+      end
+
+      factory :week_long_published_story,    :attribute_groups => [:published, :week_long_publishing]
+      factory :month_long_published_story,   :attribute_groups => [:published, :month_long_publishing]
+      factory :week_long_unpublished_story,  :attribute_groups => [:unpublished, :week_long_publishing]
+      factory :month_long_unpublished_story, :attribute_groups => [:unpublished, :month_long_publishing]
+    end
+
+Attribute groups can be used as attributes:
+
+    factory :week_long_published_story_with_title, :parent => :story do
+      published
+      week_long_publishing
+      title { "Publishing that was started at {start_at}" }
+    end
+
+Attribute groups that define the same attributes won't raise AttributeDefinitionErrors;
+the attribute group that defines the attribute latest in order gets precedence.
+
+    factory :user do
+      name "Friendly User"
+      login { name }
+
+      attribute_group :male do
+        name   "John Doe"
+        gender "Male"
+        login { "#{name} (M)" }
+      end
+
+      attribute_group :female do
+        name   "Jane Doe"
+        gender "Female"
+        login { "#{name} (F)" }
+      end
+
+      attribute_group :admin do
+        admin true
+        login { "admin-#{name}" }
+      end
+
+      factory :male_admin,   :attribute_groups => [:male, :admin]   # login will be "admin-John Doe"
+      factory :female_admin, :attribute_groups => [:admin, :female] # login will be "Jane Doe (F)"
+    end
+
 Callbacks
 ---------