README.textile in grimen-dry_scaffold-0.1.2 vs README.textile in grimen-dry_scaffold-0.2.0
- old
+ new
@@ -4,29 +4,38 @@
h2. Description
DryScaffold is a replacement for the Rails scaffold generator that generates code that most people end up deleting or rewriting anyway because of the unusable code. The scaffold concept is powerful, but it has more potential than generating messy and almost useless code. The goal with DryScaffold is to generate DRY, beautiful, and standards compliant code based on common patterns without adding a lot of magic.
-h4. Key concepts:
+h3. Key concepts:
-* Controllers that are DRY, RESTful, no code-smells, following conventions, and implementing VERY common patterns
-* Views that are DRY, semantic, standards compliant, valid, and more useful in development
-* Generator that gets smart with additional arguments - but not stupid without them
-* Any Rails developer should be able to switch generator with no effort - follow current conventions, but extend them
+* Controllers that are DRY, RESTful, no code-smells, following conventions, and implementing VERY common patterns.
+* Views that are DRY, semantic, standards compliant, valid, and more useful in development.
+* Factories instead of fixtures.
+* Generator that gets smart with additional arguments - but not stupid without them.
+* Any Rails developer should be able to switch generator with no effort - follow current conventions, but extend them.
h2. Dependencies
h3. Required:
* "*haml*":http://github.com/nex3/haml - ERB sucks like PHP, end of story
h3. Optional:
+h4. Controllers/Views
+
* "*will_paginate*":http://github.com/mislav/will_paginate - Pagination
* "*formtastic*":http://github.com/justinfrench/formtastic - DRY and semantic forms
* "*inherited_resources*":http://github.com/josevalim/inherited_resources - DRY/Resourceful controllers
+h4. Models
+
+* "*factory_girl*":http://github.com/thoughtbot/factory_girl - Fixture-replacement
+* "*machinist*":http://github.com/notahat/machinist - Fixture-replacement
+* "*object_daddy*":http://github.com/flogic/object_daddy - Fixture-replacement
+
h2. Features
h3. Overview
The most characteristic features:
@@ -92,23 +101,25 @@
Find out more about *inherited_resources*: "http://github.com/josevalim/inherited_resources":http://github.com/josevalim/inherited_resources
h3. Pagination
-Pagination is such a common feature that always seems to be implemented anyway, so dry_scaffold will generate a DRY solution for this in each controller that you can tweak - even thought that will not be needed in most cases. See DRY Patterns beneath for more details how it's done.
+Pagination is such a common feature that always seems to be implemented anyway, so DryScaffold will generate a DRY solution for this in each controller that you can tweak - even thought that will not be needed in most cases. See DRY Patterns beneath for more details how it's done. Pagination - using WillPaginate - can be turned off.
Find out more about *will_paginate*: "http://github.com/mislav/will_paginate":http://github.com/mislav/will_paginate
h3. DRY Patterns
Either if you choosing default or resourceful controllers, this pattern is used to DRYing up controllers a bit more, and at the same time loading resources in the same place using before_filter while adding automatic pagination for collections.
-h4. Default (ActionController, without InheritedResources)
+h4. Default (ActionController with pagination - not using InheritedResources)
<pre>before_filter :load_resource, :only => [:show, :edit, :update, :destroy]
before_filter :load_and_paginate_resources, :only => [:index]
+...
+
protected
def collection
paginate_options ||= {}
paginate_options[:page] ||= (params[:page] || 1)
@@ -120,11 +131,11 @@
def resource
@resource = @resource = ||= Duck.find(params[:id])
end
alias :load_resource :resource</pre>
-h4. Resourceful (InheritedResources)
+h4. Resourceful (InheritedResources with pagination)
<pre>protected
def collection
paginate_options ||= {}
@@ -137,21 +148,21 @@
@resource = @resource ||= end_of_association_chain.find(params[:id])
end</pre>
h3. View Partials
-A very common pattern is to break up views in partials, wich is also what DryScaffold does:
+A very common pattern is to break up views in partials, which is also what DryScaffold does:
* new/edit => _form
* index => _item
h3. More To Come... (TODO)
These are things I have in mind:
-* Generation of factory stubs instead of fixture stubs that Rails model generator generates
-* Generation of Rails builder stubs (RSS/Atom/...)
+* Generation of Rails builder stubs automatically for formats atom/rss.
+* Read default scaffold options for current Rails porject from a config (say "config/scaffold.yml")
* Break up into multiple generators as dependencies (like Rails generators): dry_controller, dry_views, dry_scaffold, ...
h2. Setup
Installing DryScaffold is easy as 1-2-3...nah, really:
@@ -177,18 +188,28 @@
h3. 3. Install Dependencies (Partly optional)
Install dependencies to release the full power of dry_scaffold. Only HAML is really required of these, but how could anyone resist candy? =)
-h4. Installation, i.e. get the gems
+h4. Express
+For us lazy ones... =)
+
+<pre>rake dry_scaffold:setup</pre>
+
+Will install the dependencies, initialize HAML within current Rails project if not already done, and automatically referencing the dependency gems within the current Rails project environment config if they are not already in there (note: nothing will be overwritten).
+
+h4. Installation
+
+Get the gems...
+
<pre>sudo gem install haml</pre>
<pre>sudo gem install will_paginate</pre>
<pre>sudo gem install justinfrench-formtastic</pre>
<pre>sudo gem install josevalim-inherited_resources</pre>
-h4. Configuration
+h4. B2. Configuration
In: @config/environment.rb@
<pre>config.gem 'haml'</pre>
<pre>config.gem 'will_paginate'</pre>
@@ -197,26 +218,36 @@
h2. Usage
<pre>./script/generate dry_scaffold ModelName [attribute:type attribute:type] [_actions:new,create,...] [_formats:html,json,...] [--skip-pagination] [--skip-resourceful] [--skip-formtastic] [--skip-views] [--skip-helpers] [--skip-tests] [--include-layout]</pre>
+...or use the alias (instead of @dry_scaffold@):
+
+<pre>./script/generate dscaffold ...</pre>
+
h3. Model Name
-Example: <pre>Hello</pre>
+Example:
+<pre>Duck</pre>
+
Same as in the default scaffold/model generator; the name of a new/existing model.
h3. Model Attributes
-Example: <pre>title:string description:text ...</pre>
+Example:
+<pre>name:string about:text ...</pre>
+
Same as in the default scaffold/model generator; model attributes and database migration column types.
h3. Controller Actions
-Usage: <pre>_actions:new,create,recent,index,...</pre>
+Usage:
+<pre>_actions:new,create,quack,index,...</pre>
+
You can override what actions that should be generated directly - including custom actions.
NOTE: Sorry for the a bit ugly prefix (_), but I had to trick the Rails generator a bit to get this working for now. This is definitely something I want to fix sooner or later, but I skipped that for now with this small hack.
h4. Default actions (REST)
@@ -231,18 +262,25 @@
* @update@
* @destroy@
Default controller action stubs, controller action test stubs, and corresponding views (and required partials), are generated for all of these actions.
+These default actions can also be included using the alias symbol @*@, which makes it easier to add new actions without having to specify all the default actions explicit. Example:
+
+<pre>_actions:quack # => quack</pre>
+<pre>_actions:*,quack # => show,index,new,edit,create,update,destroy,quack</pre>
+
h4. Custom actions
The above REST actions are in many RESTful applications the only ones needed. Any other specified actions will generate empty action function stubs for manual implementation. No views will be generated for custom actions.
h3. Controller Formats
-Usage: <pre>_formats:html,xml,txt,...</pre>
+Usage:
+<pre>_formats:html,xml,txt,... # <=> _respond_to:html,xml,txt,...</pre>
+
You can override what respond_to-formats that should be generated directly - only for REST-actions right now because I tried to avoid bad assumptions.
NOTE: Sorry for the a bit ugly prefix (_), but I had to trick the Rails generator a bit to get this working for now. This is definitely something I want to fix sooner or later, but I skipped that for now with this small hack.
h4. Default formats
@@ -254,44 +292,66 @@
* @xml@ => Render: resource.to_xml
* @json@ => Render: resource.to_json
Default respond block stubs are generated for all of these formats - for each generated REST-action.
+Like for actions, these default respond_to-formats can also be included using the alias symbol @*@, which makes it easier to add new formats without having to specify all the default formats explicit. Example:
+
+<pre>_formats:iphone # => _formats:iphone</pre>
+<pre>_formats:*,iphone # => _formats:html,js,xml,json,iphone</pre>
+
h4. Additional formats
Also, default respond block stubs are generated for any of these formats - for each generated REST-action - if they are specified:
* @yaml@ or @yml@ => Render: resource.to_yaml
* @txt@ or @text@ => Render: resource.to_s
+NOTE: Only for Non-InheritedResources controllers for now.
+
h4. Custom formats
The above formats are the most commonly used ones, and respond blocks are already implemented using Rails default dependencies. Any other specified formats (such as PDF, CSV, etc.) will generate empty respond block stubs for manual implementation with help of additional dependencies.
h3. Options/Flags
-Example: <pre>--skip-resourceful --include-layout</pre>
+Example:
+<pre>--skip-resourceful --layout</pre>
+
+h4. General
+
* @--skip-pagination@ - Don't generate pagination of collections in controller and views, i.e. don't use *will_paginate*.
* @--skip-resourceful@ - Don't generate resourceful controller, i.e. don't use *inherited_resources*.
* @--skip-formtastic@ - Don't generate formtastic forms in views, i.e. don't use *formtastic*.
* @--skip-views@ - Don't generate views.
* @--skip-helpers@ - Don't generate helpers.
* @--skip-tests@ - Don't generate tests (functional/unit/...).
-* @--include-layout@ - Generate a neat application layout.
+* @--layout@ - Generate layout.
+h4. Model-specific
+
+* @--fixtures@ - Generate fixtures.
+* @--fgirl@ - Generate *factory_girl* factories.
+* @--machinist@ - Generate *machinist* blueprints (factories).
+* @--odaddy@ - Generate *object_daddy* generator/factory methods.
+* @--skip-timestamps@ - Don't add timestamps to the migration file.
+* @--skip-migration@ - Skip generation of migration file.
+
As DryScaffold is built upon Rails generator, the default generator options is available as well. For more details; see Rails documentation.
h2. Examples
-No need for more samples here, just create a new Rails project, install dry_scaffold and it's dependencies, and try it out!
+No need for more samples here, just create a new Rails project, install DryScaffold and it's dependencies, and try it out!
For your inspiration, you could try the following:
<pre>./script/generate dry_scaffold Zebra name:string about:text --skip-resourceful
./script/generate dry_scaffold Kangaroo name:string about:text --skip-formtastic
./script/generate dry_scaffold Duck name:string about:text _actions:new,create,index,quack
-./script/generate dry_scaffold Parrot name:string about:text _formats:html,xml,yml</pre>
+./script/generate dry_scaffold Parrot name:string about:text _formats:html,xml,yml
+./script/generate dry_scaffold Parrot name:string about:text _indexes:name --fgirl
+./script/generate dry_scaffold Parrot name:string about:text _indexes:name,name+about --fixtures</pre>
...or just go crazy!
h2. Bugs & Feedback
\ No newline at end of file