dry_crud 1.2.7 → 1.3.0

data/README.rdoc

@@ -18,9 +18,9 @@ To integrate DRY CRUD into your code, only a few additions are required:
 
 * For uniform CRUD functionality, just subclass your controllers from +CrudController+. 
 * To use standard formatting, tables and forms throughout your application, add <tt>helper :standard</tt> to your +ApplicationController+ and benefit everywhere from these little helper methods. 
-* Add a <tt>:label</tt> method to your models for a human-friendly representation.
+* Overwrite the <tt>:to_s</tt> method of your models for a human-friendly representation.
 
-Version 1.0.0 and higher are built for Rails 3. If you need a version for Rails 2.3, please get version 0.6.0 of the gem or go to the rails-2.3 branch on Github.
+Version 1.0 and higher are built for Rails 3. If you need a version for Rails 2.3, please get version 0.6.0 of the gem or go to the rails-2.3 branch on Github. DRY CRUD 1.3 is fully compatible with Ruby 1.8.7, Ruby 1.9.2 and JRuby.
 
 == Overview
 
@@ -44,7 +44,7 @@ See the Examples section for some use cases and the Generated Files section belo
 
 === Controller with CRUD functionality
 
-Say you want to manage a +Person+ model. Create the following controller and add a <tt>:label</tt> method to your model for a human-friendly representation used in page titles.
+Say you want to manage a +Person+ model. Create the following controller and overwrite the <tt>:to_s</tt> method of your model for a human-friendly representation used in page titles.
 
 <tt>app/controllers/people_controller.rb</tt>:
   class PeopleController < CrudController
@@ -52,7 +52,7 @@ Say you want to manage a +Person+ model. Create the following controller and add
 
 <tt>app/models/person.rb</tt>:
   class Person
-    def label
+    def to_s
       "#{lastname} #{firstname}"
     end
   end
@@ -64,7 +64,7 @@ That's it. You have a sortable overview of all people, detail pages and forms to
 
 Well, maybe there are certain attributes you do not want to display in the people list, or others that are not editable. No problem, simply create a <tt> _list</tt> partial in <tt>app/views/people/_list.html.erb</tt> to customize this:
 
-  <%= crud_table [:lastname, :firstname, :city, :sex] %>
+  <%= crud_table :lastname, :firstname, :city, :sex %>
 
 This only displays these three attributes in the table. All other templates, as well as the main index view, fallback to the ones in <tt>app/views/crud</tt>.
 
@@ -87,18 +87,20 @@ And we are done again. All our controllers inheriting from +ListController+, inc
 If the current page should be remembered while viewing or editing an entry, just add :page to the remembered_params in <tt>ListController::Memory</tt>:
 
   controller.remember_params = [:q, :sort, :sort_dir, :page]
+  
+In this case, you should also pass the parameter <tt>page=1</tt> with a hidden field in your <tt>list/_search.html.erb</tt> to start displaying search results at page one.
 
 
 ==== Special formatting for selected attributes
 
-Sometimes, the default formatting provided by +:format_attr+ will not be sufficient. We have a boolean column <tt>sex</tt> in our model, but would like to display 'male' or 'female' for it (instead of 'no' or 'yes', which is a bit cryptic). Just define a method in your view helper starting with <tt>format_</tt>, followed by the attribute name:
+Sometimes, the default formatting provided by <tt>:format_attr</tt> will not be sufficient. We have a boolean column +sex+ in our model, but would like to display 'male' or 'female' for it (instead of 'no' or 'yes', which is a bit cryptic). Just define a method in your view helper starting with <tt>format_</tt>, followed by the attribute name:
 
 In <tt>app/helpers/people.rb</tt>:
   def format_sex(person)
     person.sex ? 'female' : 'male'
   end
 
-By the way: The method +:f+ in +StandardHelper+ uniformly formats arbitrary values according to their class.  
+By the way: The method <tt>:f</tt> in +StandardHelper+ uniformly formats arbitrary values according to their class.  
 
 
 ==== Filtering the index list
@@ -164,10 +166,10 @@ To render custom columns, use the :col method:
 
 Forms work very similar. In the most simple case, you just have to specify which attributes of a model to create input fields for, and you get a complete form with error messages, labeled input fields according the column types and a save button:
 
-  <%= standard_form(@person, [:firstname, :lastname, :age, :city] -%>
+  <%= standard_form(@person, :firstname, :lastname, :age, :city) -%>
 
 Of course, custom input fields may be defined as well:
-  <%= standard_form(@person, [], :url => {:action => 'custom_update', :id => @person.id}) do |f| %>
+  <%= standard_form(@person, :url => custom_update_person_path(@person.id)) do |f| %>
     <%= f.labeled_input_fields :firstname, :lastname %>
     <%= f.labeled(:sex) do %>
       <%= f.radio_button :sex, true %> female
@@ -182,13 +184,35 @@ Even +belongs_to+ associations are automatically rendered with a select field. B
 
 Yes, it's bad practice to use finder logic in your views! Define the variable <tt>@hometowns</tt> in your controller instead (as shown in the example above), and you do not even have to specify the <tt>:list</tt> option.
 
+=== Internationalization (I18N)
+
+All text strings used are externalized to an english locale yaml. The keys are organized by controller and template name plus a generic global scope. 
+
+To represent the controller hierarchy used by <tt>render_inheritable</tt>, a special translation helper <tt>:ti</tt> looks up keys along this hierarchy in the following order:
+  {controller_name}.{template_name}.{key}
+  {controller_name}.{action_name}.{key}
+  {controller_name}.global.{key}
+  {parent_controller_name}.{template_name}.{key}
+  {parent_controller_name}.{action_name}.{key}
+  {parent_controller_name}.global.{key}
+  ...
+  global.{key}
+
+In order to change the title for your +PeopleController+'s +index+ action, you do not need to override the entire template, but simply define the following key:
+  people.index.title = "The People"
+
+Otherwise, the lookup for the title would fallback on the +ListController+'s key <tt>list.index.title</tt>.
+
+This lookup mechanism also allows you to easily define per-controller overridable text snippets in your views.
+
+
 == Generated Files
 
 All generated files are supposed to provide a reasonable foundation for the CRUD functionality. You are encouraged to adapt them to fit the needs of your application. They're yours!
 
 === Controller:
 
-{controller/crud_controller.rb}[http://codez.ch/dry_crud/?q=CrudController]:: Abstract controller providing basic CRUD actions. This implementation mainly follows the one of the Rails scaffolding controller and responses to HTML and XML requests. Some enhancements were made to ease extendability. Several protected helper methods are there to be (optionally) overriden by subclasses. With the help of additional callbacks, it is possible to hook into the action procedures without overriding the entire method. This class is based on ListController.
+{controller/crud_controller.rb}[http://codez.ch/dry_crud/?q=CrudController]:: Abstract controller providing basic CRUD actions. This implementation mainly follows the one of the Rails scaffolding controller and responses to HTML and XML requests. Some enhancements were made to ease extendability. Several protected helper methods are there to be (optionally) overriden by subclasses. With the help of additional callbacks, it is possible to hook into the action procedures without overriding the entire method. This class is based on +ListController+.
 
 {controller/list_controller.rb}[http://codez.ch/dry_crud/?q=ListController]:: Abstract controller providing a basic list action. There are two sub-modules that provide search and sort functionality for the table displayed in the list action. A third sub-module remembers the list parameters in order to return to an identical list.
 
@@ -197,33 +221,44 @@ All generated files are supposed to provide a reasonable foundation for the CRUD
 
 === Helpers:
 
-{helpers/standard_helper.rb}[http://codez.ch/dry_crud/?q=StandardHelper]:: A view helper to standardize often used functions like formatting, tables, forms or action links. This helper is ideally defined in the ApplicationController. It is required to use the StandardTableBuilder and the StandardFormBuilder.
+{helpers/standard_helper.rb}[http://codez.ch/dry_crud/?q=StandardHelper]:: A view helper to standardize often used functions like formatting, tables, forms or action links. This helper is ideally defined in the +ApplicationController+. It is required to use the +StandardTableBuilder+ and the +StandardFormBuilder+.
 
-{helpers/crud_helper.rb}[http://codez.ch/dry_crud/?q=CrudHelper]:: A small helper for CrudController to render tables and forms with a default set of attributes.
+{helpers/crud_helper.rb}[http://codez.ch/dry_crud/?q=CrudHelper]:: A small helper for +CrudController+ to render tables and forms with a default set of attributes.
 
-{helpers/list_helper.rb}[http://codez.ch/dry_crud/?q=ListHelper]:: A small helper for ListController to render the list table with a default set of attributes.
+{helpers/list_helper.rb}[http://codez.ch/dry_crud/?q=ListHelper]:: A small helper for +ListController+ to render the list table with a default set of attributes.
 
 {helpers/standard_table_builder.rb}[http://codez.ch/dry_crud/?q=StandardTableBuilder]:: A simple helper object to easily define tables listing several rows of the same data type.
 
-{helpers/standard_form_builder.rb}[http://codez.ch/dry_crud/?q=StandardFormBuilder]:: A form builder that automatically selects the corresponding input element for ActiveRecord columns. Input elements are rendered with a corresponding label by default.
+{helpers/standard_form_builder.rb}[http://codez.ch/dry_crud/?q=StandardFormBuilder]:: A form builder that automatically selects the corresponding input type for ActiveRecord columns. Input elements are rendered together with a label by default.
 
 
 === Views:
 
-All templates in the +crud+ folder may be 'overriden' individually in a respective view folder. Define the basic structure of your CRUD views here and adapt it as required for each single model.
+All templates in the +list+ and +crud+ folders may be 'overriden' individually in a respective view folder. Define the basic structure of your CRUD views here and adapt it as required for each single model. Actually, the <tt>_list.html.erb</tt> partial from the +list+ folder gets overriden in the +crud+ folder already.
+
+==== List
+
+views/list/index.html.erb:: The index view displaying a sortable table with all entries. If you have +search_columns+ defined for your controller, then a search box is rendered as well.
+
+views/list/_list.html.erb:: A partial defining the table in the index view. To change the displayed attributes for your list model, just create an own <tt>_list.html.erb</tt> in your controller's view directory.
 
+views/list/_search.html.erb:: A partial defining a simple search form that is displayed when +search_columns+ are defined in a subclassing controller.
+
+views/list/_actions_index.html.erb:: The action links available in the index view. None by default.
+
+==== Crud
 
 views/crud/show.html.erb:: The show view displaying all the attributes of one entry and the various actions to perform on it.
 
 views/crud/_attrs.html.erb:: A partial defining the attributes to be displayed in the show view. 
 
-views/crud/_list.html.erb:: A partial defining the table in the index view. To change the displayed attributes for your list model, just create an own _list.html.erb in your controller's view directory.
+views/crud/_list.html.erb:: A partial defining the table in the index view with various links to manipulate the entries.
 
 views/crud/new.html.erb:: The view to create a new entry.
 
 views/crud/edit.html.erb:: The view to edit an existing entry.
 
-views/crud/_form.html.erb:: The form used to create and edit entries. If you would like to customize this form for various models, just create an own _form.html.erb in your controller's view directory.
+views/crud/_form.html.erb:: The form used to create and edit entries. If you would like to customize this form for various models, just create an own <tt>_form.html.erb</tt> in your controller's view directory.
 
 views/crud/_actions_index.html.erb:: The action links available in the index view.
 
@@ -231,22 +266,20 @@ views/crud/_actions_show.html.erb:: The action links available in the show view.
 
 views/crud/_actions_edit.html.erb:: The action links available in the edit view.
 
-views/list/index.html.erb:: The index view displaying a sortable table with all entries. If you have +search_columns+ defined for your controller, then a search box is rendered as well.
-
-views/list/_list.html.erb:: A partial defining the table in the index view. To change the displayed attributes for your list model, just create an own _list.html.erb in your controller's view directory.
-
-views/list/_search.html.erb:: A partial defining a simple search form that is displayed when +search_columns+ are defined in a subclassing controller.
-
-views/list/_actions_index.html.erb:: The action links available in the index view. None by default.
+==== Various
 
 views/shared/_labeled.html.erb:: Partial to define the layout for an arbitrary content with a label.
 
-views/layouts/crud.html.erb:: An example layout showing how to use the @title and +flash+. Most probably you want to merge this with your application.html.erb or adapt the main CRUD templates, so you wont need this file.
+views/shared/_error_messages.html.erb:: Partial to display the validation errors in Rails 2 style.
+
+views/layouts/crud.html.erb:: An example layout showing how to use the <tt>@title</tt> and +flash+. Most probably you want to merge this with your <tt>application.html.erb</tt> or adapt the main CRUD templates, so you wont need this file.
 
-views/layouts/_menu.html.erb:: An empty file to put your menu items into. Included from +list.html.erb+.
+views/layouts/_menu.html.erb:: An empty file to put your menu items into. Included from <tt>crud.html.erb</tt>.
 
 public/stylesheets/crud.css:: A simple CSS with all the classes and ids used in the CRUD code. 
 
+public/images/action/*.png:: Some sample action icons from the {Open Icon Library}[http://openiconlibrary.sourceforge.net].
+
 
 === Tests:
 
@@ -254,7 +287,7 @@ public/stylesheets/crud.css:: A simple CSS with all the classes and ids used in
 
 {test/custom_assertions.rb}[http://codez.ch/dry_crud/?q=CustomAssertions]:: A handful of convenient assertions. Include this module into your <tt>test_helper.rb</tt> file.
 
-{test/functionals/crud_controller_test_helper.rb}[http://codez.ch/dry_crud/?q=CrudControllerTestHelper]:: A module to include into the functional tests for your CrudController subclasses. Contains a handful of CRUD functionality tests for the provided implementation. So for each new CRUD controller, you get 20 tests for free.
+{test/functionals/crud_controller_test_helper.rb}[http://codez.ch/dry_crud/?q=CrudControllerTestHelper]:: A module to include into the functional tests for your +CrudController+ subclasses. Contains a handful of CRUD functionality tests for the provided implementation. So for each new CRUD controller, you get 20 tests for free.
 
 test/several other tests:: Testing the provided implementation and a great base to test your adaptions of the CRUD code.
 

data/Rakefile

@@ -48,6 +48,7 @@ namespace :test do
     task :create do
       unless File.exist?(TEST_APP_ROOT)
         sh "rails new #{TEST_APP_ROOT}"
+        FileUtils.cp(File.join(File.dirname(__FILE__), 'test', 'templates', 'Gemfile'), TEST_APP_ROOT)
       end
     end
       
@@ -66,7 +67,8 @@ namespace :test do
                    File.join(TEST_APP_ROOT, 'app', 'views', 'layouts', 'application.html.erb'), 
                    :force => true)
       FileUtils.cd(TEST_APP_ROOT) do
-        sh "rake db:migrate db:seed db:test:prepare RAILS_ENV=development"
+        sh "rake db:migrate db:seed RAILS_ENV=development"
+        sh "rake db:migrate RAILS_ENV=test"  # db:test:prepare does not work for jdbcsqlite3
       end
     end
   end

data/VERSION

@@ -1 +1 @@
-1.2.7
+1.3.0

data/lib/generators/dry_crud/dry_crud_generator.rb

@@ -1,11 +1,11 @@
 require 'rails/generators'
 
 class DryCrudGenerator < Rails::Generators::Base
-  
+
   def self.source_root
      File.join(File.dirname(__FILE__), 'templates')
   end
-  
+
   def install_dry_crud
     # copy everything in template subfolders
     Dir.chdir(self.class.source_root) do
@@ -13,7 +13,7 @@ class DryCrudGenerator < Rails::Generators::Base
         directory(f) if File.directory?(f)
       end
     end
-    
+
     readme "INSTALL"
   end
 

data/lib/generators/dry_crud/templates/INSTALL

@@ -8,6 +8,8 @@ required:
  * To use standard formatting, tables and forms throughout your
    application, add 'helper :standard' to your ApplicationController and 
    benefit everywhere from these little helper methods. 
- * Add a #label method to your models for a human-friendly representation.
+ * Overwrite the :to_s method of your models for a human-friendly
+   representation.
+
 
 Enjoy dry_crud and stay DRY!

data/lib/generators/dry_crud/templates/app/controllers/crud_controller.rb

@@ -5,47 +5,37 @@
 # With the help of additional callbacks, it is possible to hook into the action procedures without
 # overriding the entire method.
 class CrudController < ListController
-    
+
+  include ERB::Util
+  
   # Set up entry object to use in the various actions.
   before_filter :build_entry, :only => [:new, :create]
   before_filter :set_entry,   :only => [:show, :edit, :update, :destroy]
-  
+
   helper_method :full_entry_label
-  
-  delegate :model_identifier, :to => 'self.class'  
-  
+
+  delegate :model_identifier, :to => 'self.class'
+
   hide_action :model_identifier, :run_callbacks
-   
-   
-  # Defines before and after callback hooks for create, update, save and destroy.
+
+
+  # Defines before and after callback hooks for create, update, save and destroy actions.
   define_model_callbacks :create, :update, :save, :destroy
-  
+
   # Defines before callbacks for the render actions. A virtual callback
   # unifiying render_new and render_edit, called render_form, is defined further down.
-  define_model_callbacks :render_show, 
-                         :render_new, 
-                         :render_edit, 
-                         :only => :before,
-                         :terminator => "result == false || performed?"
-                         
-  # Verify that required :id param is present and only allow good http methods.
-  # Uncomment if you have the Rails verification plugin installed.
-  #verify :params => :id, :only => :show, :redirect_to => { :action => 'index' }
-  #verify :method => :post, :only => :create,  :redirect_to => { :action => 'index' }  
-  #verify :method => [:put, :post], :params => :id, :only => :update,  :redirect_to => { :action => 'index' }  
-  #verify :method => [:delete, :post], :params => :id, :only => :destroy, :redirect_to => { :action => 'index' }  
-  
-   
+  define_render_callbacks :show, :new, :edit
+
+
   ##############  ACTIONS  ############################################
 
-  
   # Show one entry of this model.
   #   GET /entries/1
   #   GET /entries/1.xml
   def show
     respond_with @entry
   end
-  
+
   # Display a form to create a new entry of this model.
   #   GET /entries/new
   #   GET /entries/new.xml
@@ -55,112 +45,138 @@ class CrudController < ListController
   end
 
   # Create a new entry of this model from the passed params.
+  # There are before and after create callbacks to hook into the action.
+  # To customize the response, you may overwrite this action and call
+  # super with a block that gets success and format parameters.
   #   POST /entries
   #   POST /entries.xml
-  def create
+  def create(&block)
     @entry.attributes = params[model_identifier]
-    created = with_callbacks(:create) { save_entry } 
-    
-    respond_processed(created, 'created', 'new') do |format|
-      format.xml  { render :xml => @entry, :status => :created, :location => @entry } if created
+    created = with_callbacks(:create, :save) { @entry.save }
+
+    customizable_respond_to(created, block) do |format|
+      if created
+        format.html { redirect_to_show success_notice }
+        format.xml  { render :xml => @entry, :status => :created, :location => @entry }
+      else
+        format.html { render_with_callback 'new'  }
+        format.xml  { render :xml => @entry.errors, :status => :unprocessable_entity }
+      end
     end
   end
-    
+
   # Display a form to edit an exisiting entry of this model.
   #   GET /entries/1/edit
   def edit
     render_with_callback 'edit'
   end
-  
+
   # Update an existing entry of this model from the passed params.
+  # There are before and after update callbacks to hook into the action.
+  # To customize the response, you may overwrite this action and call
+  # super with a block that gets success and format parameters.
   #   PUT /entries/1
   #   PUT /entries/1.xml
-  def update
+  def update(&block)
     @entry.attributes = params[model_identifier]
-    updated = with_callbacks(:update) { save_entry }
-    
-    respond_processed(updated, 'updated', 'edit')
+    updated = with_callbacks(:update, :save) { @entry.save }
+
+    customizable_respond_to(updated, block) do |format|
+      if updated
+        format.html { redirect_to_show success_notice }
+        format.xml  { head :ok }
+      else
+        format.html { render_with_callback 'edit'  }
+        format.xml  { render :xml => @entry.errors, :status => :unprocessable_entity }
+      end
+    end
   end
-  
+
   # Destroy an existing entry of this model.
+  # There are before and after destroy callbacks to hook into the action.
+  # To customize the response, you may overwrite this action and call
+  # super with a block that gets success and format parameters.
   #   DELETE /entries/1
   #   DELETE /entries/1.xml
-  def destroy
-    destroyed = with_callbacks(:destroy) { @entry.destroy }
-
-    respond_processed(destroyed, 'destroyed') do |format|
-      format.html do 
-        if destroyed
-          redirect_to_index
-        else
-          flash.alert = @entry.errors.full_messages.join('<br/>').html_safe
-          request.env["HTTP_REFERER"].present? ? redirect_to(:back) : redirect_to_show
-        end
-      end
-    end
-  end
-  
-  protected 
-  
-  #############  CUSTOMIZABLE HELPER METHODS  ##############################
-  
-  # Convenience method to respond to various formats if the performed
-  # action may succeed or fail. It is possible to pass a block and respond
-  # in custom ways for certain cases. If no response is performed in the 
-  # given block, the default responses in this method are executed.
-  def respond_processed(success, operation, failed_action = 'show')
-    respond_to do |format|
-      flash.notice = "#{full_entry_label} was successfully #{operation}." if success
-      yield format if block_given?
-      return if performed?
-      
-      # fallback responders if nothing was performed in the block
-      if success
-        format.html { redirect_to_show }
+  def destroy(&block)
+    destroyed = run_callbacks(:destroy) { @entry.destroy }
+
+    customizable_respond_to(destroyed, block) do |format|
+      if destroyed
+        format.html { redirect_to_index success_notice }
         format.xml  { head :ok }
-      else 
-        format.html { render_with_callback failed_action }
+      else
+        format.html { 
+          flash.alert = @entry.errors.full_messages.join('<br/>')
+          request.env["HTTP_REFERER"].present? ? redirect_to(:back) : redirect_to_show
+        }
         format.xml  { render :xml => @entry.errors, :status => :unprocessable_entity }
       end
     end
   end
-  
+
+  protected
+
+  #############  CUSTOMIZABLE HELPER METHODS  ##############################
+
   # Creates a new model entry.
   def build_entry
     @entry = model_class.new
   end
-  
+
   # Sets an existing model entry from the given id.
   def set_entry
     @entry = model_class.find(params[:id])
   end
-  
+
   # A label for the current entry, including the model name.
   def full_entry_label
-    "#{models_label.singularize} '#{@entry.label}'"
+    "#{models_label(false)} <i>#{h(@entry)}</i>".html_safe
   end
-   
+
   # Redirects to the show action of a single entry.
-  def redirect_to_show
-    redirect_to @entry
+  def redirect_to_show(options = {})
+    redirect_to @entry, options
   end
-  
+
   # Redirects to the main action of this controller.
-  def redirect_to_index
-    redirect_to polymorphic_path(model_class, :returning => true)
+  def redirect_to_index(options = {})
+    redirect_to polymorphic_path(model_class, :returning => true), options
   end
-  
-  # Saves the current entry with callbacks.
-  def save_entry
-    with_callbacks(:save) { @entry.save }
+
+  # Helper method the run the given block in between the before and after
+  # callbacks of the given kinds.
+  def with_callbacks(*kinds, &block)
+    kinds.reverse.inject(block) do |b, kind| 
+      lambda { run_callbacks(kind, &b) }
+    end.call
   end
   
-  # Helper method the run the given block in between the before and after
-  # callbacks of the given kind.
-  def with_callbacks(kind, &block)
-    send(:"_run_#{kind}_callbacks", &block)
+  private
+  
+  # Convenience method to respond to various formats if the performed
+  # action may succeed or fail. It is possible to pass a custom_block and respond
+  # in custom ways for certain cases. If no response is performed in the
+  # given block, the default responses in the main block are executed.
+  def customizable_respond_to(success, custom_block = nil)
+    respond_to do |format|
+      custom_block.call(success, format) if custom_block
+      return if performed?
+      
+      yield format
+    end
   end
   
+  # Create an I18n flash notice if the action was successfull.
+  # Uses the key {controller_name}.{action_name}.flash.success
+  # or crud.{action_name}.flash.success as fallback.
+  def success_notice
+    key = "#{action_name}.flash.success"
+    {:notice => t(:"#{controller_name}.#{key}", 
+                  :model => full_entry_label, 
+                  :default => :"crud.#{key}")}
+  end
+
   class << self
     # The identifier of the model used for form parameters.
     # I.e., the symbol of the underscored model name.
@@ -174,5 +190,5 @@ class CrudController < ListController
       before_render_edit *methods
     end
   end
-  
+
 end