README.textile in grimen-dry_scaffold-0.2.0 vs README.textile in grimen-dry_scaffold-0.2.1
- old
+ new
@@ -4,11 +4,11 @@
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.
-h3. 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.
* Factories instead of fixtures.
* Generator that gets smart with additional arguments - but not stupid without them.
@@ -158,11 +158,11 @@
h3. More To Come... (TODO)
These are things I have in mind:
* 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")
+* Make routing smarter; if route is already declared in _config/routes.rb_, then don't generate it (no duplication).
* 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:
@@ -216,16 +216,20 @@
<pre>config.gem 'justinfrench-formtastic', :lib => 'formtastic, :source => 'http://gems.github.com'</pre>
<pre>config.gem 'josevalim-inherited_resources', :lib => 'inherited_resources', :source => 'http://gems.github.com'</pre>
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>
+<pre>./script/generate dry_scaffold ModelName [attribute:type attribute:type] [_actions:new,create,...] [_formats:html,json,...] [_indexes:attribute,...] [--skip-pagination] [--skip-resourceful] [--skip-formtastic] [--skip-views] [--skip-helpers] [--skip-tests] [--include-layout] [--fixtures] [--fgirl] [--machinist] [--odaddy] [--skip-migration] [--skip-timestamps]</pre>
-...or use the alias (instead of @dry_scaffold@):
+...or use the alias @dscaffold@ instead of @dry_scaffold@.
-<pre>./script/generate dscaffold ...</pre>
+For generating just a *model*, then use:
+<pre>./script/generate dry_model ModelName [attribute:type attribute:type] [_indexes:attribute,...] [--fixtures] [--fgirl] [--machinist] [--odaddy] [--skip-migration] [--skip-timestamps] [--skip-tests]</pre>
+
+...or use the alias @dmodel@ instead of @dry_model@.
+
h3. Model Name
Example:
<pre>Duck</pre>
@@ -240,19 +244,19 @@
Same as in the default scaffold/model generator; model attributes and database migration column types.
h3. Controller Actions
-Usage:
+Example:
<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)
+h4. Default Actions (REST)
If no actions are specified, the following REST-actions will be generated by default:
* @show@
* @index@
@@ -267,25 +271,25 @@
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
+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:
+Example:
<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
+h4. Default Formats
If no formats are specified, the following formats will be generated by default:
* @html@ => Render: resource using view template (HTML/HAML)
* @js@ => Render: resource using view template (JS/RJS)
@@ -297,23 +301,41 @@
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
+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
+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. Model Indexes
+
+Example:
+
+If model attributes are specified as:
+
+<pre>name:string owner:reference</pre>
+
+...then we could do this (for polymorphic association):
+
+<pre>_indexes:owner_id # => (In migration:) add_index :duck, :owner_id</pre>
+
+...or in account for a polymorphic association:
+
+<pre>_indexes:owner_id+owner_type # => (In migration:) add_index :duck, [:owner_id, :owner_type]</pre>
+
+NOTE: Of course...you need to specify indexes based on attributes that exists for this model, otherwise your migration will not be valid - DryScaffold is leaving this responsible to you.
+
h3. Options/Flags
Example:
<pre>--skip-resourceful --layout</pre>
@@ -337,21 +359,27 @@
* @--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.
+h3. Setting Defaults
+
+You can set defaults for the generator args/options in @config/scaffold.yml@. To generate this file, simply do:
+
+<pre>rake dry_scaffold:config:generate</pre>
+
h2. Examples
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
-./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>
+./script/generate dry_scaffold GoldFish name:string about:text _indexes:name --fgirl
+./script/generate dry_scaffold Frog name:string about:text _indexes:name,name+about --fixtures</pre>
...or just go crazy!
h2. Bugs & Feedback
\ No newline at end of file