dry_crud 2.0.0 → 2.1.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    NjBkMjk0MjMzMjE3ODM1MTMyZmJlODQwNjI0OTlmOTIzYmU5N2Y5MA==
+    MmM5NzIxMmM5YTE2YzE5YTU1NWRkNDc5OTAxODkxOGU2NjE0NTA4Mg==
   data.tar.gz: !binary |-
-    NDZlYjRhMmUzMmJkODljYWMwZDUzZjRmYzRmOGUwMDgwZmE5ZTcyMA==
+    YjM3NzY0Y2VkMTllMWNmZTUwYjk1ZWRmZTgyOTgyMzA5NWFjOWU0Ng==
 !binary "U0hBNTEy":
   metadata.gz: !binary |-
-    NzJkMzU5NjI1MWFmN2JmYzdiOWEzNDBiMDI3OTAyNDk4MDZlMGY1M2VjZjcw
-    YmIwM2ZmYzI2NTllOWViMDVhNmVjMGM5NGQ1YmM5OTY4YWI1YTJkOTA2NTMw
-    OTYwNDI3NDhkMThlMTlkZGNmY2ZkMTY3YjY3MzIyMGNlZTBmNmU=
+    YWM1ZmVjY2JlZjg4NjNiMjU1NmNlYTk3NTdlZDQzMTk2NzMzNjY0NWRlMzBm
+    YzJmZTQ2OWNiMmNkMWZmNzllZWVmODA4NGE0Yzc4N2M5NGNmMWRhN2Y5N2U3
+    ODg4YTFmYzNmNjk0ZTUxYWZiM2ViZDllOGZjODI1NjE3OTYyYzA=
   data.tar.gz: !binary |-
-    NDZmYzhjZDExY2U0NGM5NDYwZDE2MTIwMTM2OWU2ZjI2M2MzN2UwZjE2MmU4
-    NzBmZDZkOTQ2YTZiZjRhZjAyMmZmMWNhOWNkNGIwOWIxY2E0ZTY5OTNkNzI4
-    Yjg0NDY3YTFjNWIwNTY2M2JmMjAyNjBkM2Y1MDU5ZjBlYWYwYzA=
+    NjU1YmUwYjVmYzdjZjg5OGZiYjE2ZmU2NGYzYTA0OTkwNTg4ZmEzM2NkY2M4
+    OWZkNzAzZGJhNzU3NmRjM2I2MDIyZWRlMGNiM2MwNWRhZTQ5NTMxMjEzMTRk
+    ZDUyYTZlZDc1NTk5ZWYyODRiNWUxN2RiMmU5NjJjZTg5MmE2NGE=

data/README.rdoc

@@ -2,7 +2,10 @@
 
 {<img src="https://secure.travis-ci.org/codez/dry_crud.png" />}[http://travis-ci.org/codez/dry_crud]
 
-dry_crud generates simple and extendable controllers, views and helpers that support you to DRY up the CRUD code in your Rails projects. Start with these artifacts and build a clean base to efficiently develop your application upon.
+dry_crud generates simple and extendable controllers, views and helpers that support you to DRY up the CRUD code in your Rails projects. List, search, sort, show, create, edit and destroy any model entries in just 5 minutes. Start with these artifacts and build a clean base to efficiently develop your application upon.
+
+
+== Installation
 
 Create your Rails application directly with the dry_crud application template:
 
@@ -14,16 +17,28 @@ If your application already exists or you prefer the DIY way, then install the G
 
 By default, dry_crud generates ERB templates and Test::Unit tests. Pass the options above to generate HAML templates and/or RSpec examples instead.
 
+We recommend to use dry_crud as a generator as described above for the best understanding and the most flexibility. When you are familiar with dry_crud, it is now also possible to use it directly as a Rails Engine. Simply add the gem to your Gemfile. You may still generate single files to adapt them:
+
+  rails generate dry_crud:file list/index.html.erb
+
+If a dry_crud file exists in your application, it will be used, if not, the one from the engine is used. This holds for controllers, helpers and view templates.
+
+
+== Integration
+
 To integrate dry_crud into your code, only a few additions are required:
 
-* For uniform CRUD functionality, just subclass your controllers from CrudController.
+* For uniform CRUD functionality, just subclass your controllers from CrudController and define the +permitted_attrs+ (for StrongParameters).
 * Overwrite the +to_s+ method of your models for a human-friendly representation in captions.
+* Optionally define a +list+ scope in your models to be used in the +index+ action.
+* Optionally define a +options_list+ scope in your models to be used in select dropdowns.
 
 Version 2.0 and higher are compatible with Rails 4 and Rails 3.2. dry_crud is tested with Ruby 1.9.3, 2.0.0 and JRuby. If you are using Ruby 1.8.7, please refer to version 1.7.0.
 
-== Overview
 
-In most Rails applications, you have some models that require basic CRUD (create, read, update, delete) functionality. There are various possibilities like Rails scaffolding, {Inherited Resources}[https://github.com/josevalim/inherited_resources] or {Dry Scaffold}[http://github.com/grimen/dry_scaffold]. Still, various parts in your application remain duplicated. While you might pull up common methods into a common superclass controller, most views still contain very similar code. And then you also have to remember the entire API of these frameworks.
+== Background
+
+In most Rails applications, you have some models that require basic CRUD (create, read, update, delete) functionality. There are various possibilities like Rails scaffolding, {Inherited Resources}[https://github.com/josevalim/inherited_resources] or {Rails Admin}[https://github.com/sferik/rails_admin]. Still, various parts in your application remain duplicated. While you might pull up common methods into a common superclass controller, most views still contain very similar code. And then you also have to remember the entire API of these frameworks.
 
 Enter dry_crud.
 
@@ -35,24 +50,18 @@ dry_crud is a Rails generator. All code resides in your application and is open
 
 dry_crud does not depend on any other plugins, but easily allows you to integrate them in order to unify the behavior of your CRUD controllers. You might even use the plugins mentioned above to adapt your generated CrudController base class. All classes come with thorough tests that provide you with a solid foundation for implementing your own adaptions.
 
-A basic CSS gets you started with your application's layout. For advanced needs, dry_crud supports the styles and classes used in {Bootstrap}[http://twitter.github.com/bootstrap/]. A great design never was so close.
+A basic CSS gets you started with your application's layout. For advanced needs, dry_crud supports the styles and classes used in {Bootstrap 3}[http://getbootstrap.com]. A great design never was so close.
 
 If you find yourself adapting the same parts of dry_crud for your applications over and over, please feel free to {fork me on Github}[http://github.com/codez/dry_crud].
 
 See the Examples section for some use cases and the Generated Files section below for details on the single classes and templates.
 
+
 == Examples
 
 === Controller with CRUD functionality
 
-Say you want to manage a +Person+ model. Create the following controller and overwrite the +to_s+ method of your model for a human-friendly representation used in page titles.
-
-<tt>app/controllers/people_controller.rb</tt>:
-  class PeopleController < CrudController
-    self.permitted_attrs = [:firstname, :lastname, :birthday, :sex, :city_id]
-  end
-
-The +permitted_attrs+ define the parameter attributes allowed when creating or updating a model entry (see {Strong Paramters}[http://api.rubyonrails.org/classes/ActionController/StrongParameters.html]).
+Say you want to manage a +Person+ model. Overwrite the +to_s+ method of your model for a human-friendly representation used in page titles.
 
 <tt>app/models/person.rb</tt>:
   class Person
@@ -61,6 +70,13 @@ The +permitted_attrs+ define the parameter attributes allowed when creating or u
     end
   end
 
+Then create the following controller. The +permitted_attrs+ define the attribute parameters allowed when creating or updating a model entry (see {Strong Paramters}[http://api.rubyonrails.org/classes/ActionController/StrongParameters.html]).
+
+<tt>app/controllers/people_controller.rb</tt>:
+  class PeopleController < CrudController
+    self.permitted_attrs = [:firstname, :lastname, :birthday, :sex, :city_id]
+  end
+
 That's it. You have a sortable overview of all people, detail pages and forms to edit and create people. Of course, you may delete people as well. By default, all attributes are displayed and formatted according to their column type wherever they appear. This applies for the input fields as well.
 
 
@@ -78,7 +94,6 @@ This only displays these three attributes in the table. All other templates, as
 Next, let's adapt a part of the general behavior used in all CRUD controllers. As an example, we include pagination with kaminari[https://github.com/amatsuda/kaminari] in all our overview tables:
 
 In <tt>app/controllers/list_controller.rb</tt>, change the list_entries method to
-
   def list_entries
     model_scope.page(params[:page])
   end
@@ -105,7 +120,12 @@ By the way: The method +f+ in FormatHelper uniformly formats arbitrary values ac
 
 ==== Sorting and filtering the index list
 
-The entries listed on the index page are automatically sortable by each displayed database column. To apply a default sorting order, define the following class attribute in the controller:
+The entries listed on the index page are automatically sortable by each displayed database column. To apply a default sorting order, define a +list+ scope in your model:
+
+In <tt>app/models/person.rb</tt>:
+  scope :list, -> { order('lastname, firstname').includes(:city) }
+
+Alternatively, set the following class attribute in the controller:
 
 In <tt>app/controllers/people_controller.rb</tt>:
   self.default_sort = 'lastname, firstname'
@@ -163,7 +183,7 @@ Of course, custom input fields may be defined as well:
     <%= f.labeled_file_field :picture %>
   <% end %>
 
-Even +belongs_to+ associations are automatically rendered with a select field. By default, all entries from the associated model are used as options. To customize this, either define an instance variable with the same name as the association in your controller, or pass a <tt>list</tt> option:
+Even +belongs_to+ associations are automatically rendered with a select field. By default, entries returned from the +options_list+ scope of the associated model are used as options (if defined, all otherwise). To customize this, either define an instance variable with the same name as the association in your controller, or pass a <tt>list</tt> option:
   <%= f.belongs_to_field :hometown, list: City.where(country: @person.country) %>
 
 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.
@@ -238,40 +258,53 @@ Otherwise, the lookup for the title would fallback on the ListController's key <
 This lookup mechanism also allows you to easily define per-controller overridable text snippets in your views.
 
 
+=== Example Code
+
+To see an example application built on dry_crud, have a look at {these directories}[https://github.com/codez/dry_crud/tree/master/test/templates/app]. Only certain methods and templates are overriden, all the 'missing' files are provided by dry_crud.
+
+
 == 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
 
-{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 JSON 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. Use this controller if you require read-only functionality. It includes the following modules.
 
-{controller/crud/generic_model.rb}[http://codez.ch/dry_crud?q=Crud::GenericModel]:: Work with the model whose name corrsponds to the controller's name.
+{controller/dry_crud/generic_model.rb}[http://codez.ch/dry_crud?q=DryCrud::GenericModel]:: Work with the model whose name corrsponds to the controller's name.
 
-{controller/crud/nestable.rb}[http://codez.ch/dry_crud?q=Crud::Nestable]:: Provides functionality to easily nest controllers/resources.
+{controller/dry_crud/nestable.rb}[http://codez.ch/dry_crud?q=DryCrud::Nestable]:: Provides functionality to easily nest controllers/resources.
 
-{controller/crud/rememberable.rb}[http://codez.ch/dry_crud?q=Crud::Rememberable]:: Remembers certain params of the index action in order to return to the same list after an entry was viewed or edited.
+{controller/dry_crud/rememberable.rb}[http://codez.ch/dry_crud?q=DryCrud::Rememberable]:: Remembers certain params of the index action in order to return to the same list after an entry was viewed or edited.
 
-{controller/crud/searchable.rb}[http://codez.ch/dry_crud?q=Crud::Searchable]:: Search functionality for the index table.
+{controller/dry_crud/searchable.rb}[http://codez.ch/dry_crud?q=DryCrud::Searchable]:: Search functionality for the index table.
 
-{controller/crud/sortable.rb}[http://codez.ch/dry_crud?q=Crud::Sortable]:: Sort functionality for the index table.
+{controller/dry_crud/sortable.rb}[http://codez.ch/dry_crud?q=DryCrud::Sortable]:: Sort functionality for the index table.
 
-{controller/crud/render_callbacks.rb}[http://codez.ch/dry_crud?q=Crud::RenderCallbacks]:: Provide +before_render+ callbacks to controllers.
+{controller/dry_crud/render_callbacks.rb}[http://codez.ch/dry_crud?q=DryCrud::RenderCallbacks]:: Provide +before_render+ callbacks to controllers.
 
-{controller/crud/responder.rb}[http://codez.ch/dry_crud?q=Crud::Responder]:: Responder used by the CrudController to handle the +path_args+.
+{controller/dry_crud/responder.rb}[http://codez.ch/dry_crud?q=DryCrud::Responder]:: Responder used by the CrudController to handle the +path_args+.
 
-=== Helpers:
+=== Helpers
 
-{helpers/crud/table_builder.rb}[http://codez.ch/dry_crud?q=Crud::TableBuilder]:: A simple helper object to easily define tables listing several rows of the same data type.
+{helpers/dry_crud/form/builder.rb}[http://codez.ch/dry_crud?q=DryCrud::Form::Builder]:: A form builder that automatically selects the corresponding input type for ActiveRecord columns. Input elements are rendered together with a label by default.
 
-{helpers/crud/form_builder.rb}[http://codez.ch/dry_crud?q=Crud::FormBuilder]:: A form builder that automatically selects the corresponding input type for ActiveRecord columns. Input elements are rendered together with a label by default.
+{helpers/dry_crud/form/control.rb}[http://codez.ch/dry_crud?q=DryCrud::Form::Control]:: Representation of a single form control consisting of a label, input field, addon or help text.
 
-{helpers/table_helper.rb}[http://codez.ch/dry_crud?q=TableHelper]:: Create tables to list multiple models with Crud::TableBuilder. Contains a standardized and a custom definable table.
+{helpers/dry_crud/table/builder.rb}[http://codez.ch/dry_crud?q=DryCrud::Table::Builder]:: A helper object to easily define tables listing several rows of the same data type.
+
+{helpers/dry_crud/table/col.rb}[http://codez.ch/dry_crud?q=DryCrud::Table::Col]:: Helper class representing a single table column.
+
+{helpers/dry_crud/table/actions.rb}[http://codez.ch/dry_crud?q=DryCrud::Table::Actions]:: Module to add support for uniform CRUD actions in tables.
+
+{helpers/dry_crud/table/sorting.rb}[http://codez.ch/dry_crud?q=DryCrud::Table::Sorting]:: Module to add support for sort links in table headers.
 
 {helpers/form_helper.rb}[http://codez.ch/dry_crud?q=FormHelper]:: Create forms to edit models with Crud::FormBuilder. Contains a standardized and a custom definable form.
 
+{helpers/table_helper.rb}[http://codez.ch/dry_crud?q=TableHelper]:: Create tables to list multiple models with Crud::TableBuilder. Contains a standardized and a custom definable table.
+
 {helpers/format_helper.rb}[http://codez.ch/dry_crud?q=FormatHelper]:: Format attribute and basic values according to their database or Ruby type.
 
 {helpers/actions_helper.rb}[http://codez.ch/dry_crud?q=ActionsHelper]:: Uniform action links for the most common crud actions.
@@ -282,9 +315,10 @@ All generated files are supposed to provide a reasonable foundation for the CRUD
 
 
 
-=== Views:
+=== Views
 
 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.
+
 All templates are available as HAML as well.
 
 ==== List
@@ -323,7 +357,7 @@ views/shared/_labeled.html.erb:: Partial to define the layout for an arbitrary c
 
 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/application.html.erb:: An example layout showing how to use the <tt>@title</tt> and +flash+.
 
 views/layouts/_flash.html.erb:: An simple partial to display the various flash messages. Included from <tt>crud.html.erb</tt>.
 
@@ -334,7 +368,7 @@ app/assets/stylesheets/crud.scss:: A simple SCSS with all the classes and ids us
 app/assets/images/action/*.png:: Some sample action icons from the {Open Icon Library}[http://openiconlibrary.sourceforge.net].
 
 
-=== Tests:
+=== Tests
 
 test/support/crud_test_model.rb:: A dummy model to run CRUD tests against.
 
@@ -347,7 +381,7 @@ test/controllers/crud_test_models_controller_test.rb:: Functional tests for the
 test/helpers/*_test.rb:: Tests for the provided helper implementations and a great base to test your adaptions of the CRUD code.
 
 
-=== Specs:
+=== Specs
 
 spec/support/crud_controller_examples.rb:: A whole set of shared exampled to include into your controller specs. See <tt>spec/controllers/crud_test_models_controller_spec.rb</tt> for usage. So for each new CRUD controller, you get all the basic specs for free.
 

data/VERSION

@@ -1 +1 @@
-2.0.0
+2.1.0

data/{lib/generators/dry_crud/templates/app → app}/assets/stylesheets/crud.scss

@@ -1,4 +1,8 @@
 
+h1 {
+  margin-bottom: 20px;
+}
+
 .right {
   text-align: right;
 }
@@ -8,9 +12,12 @@
 }
 
 #content {
+  padding-top: 10px;
+}
+
+#flash {
   clear: both;
   padding-top: 5px;
-  width: 100%;
 }
 
 table.table td.action {
@@ -18,32 +25,11 @@ table.table td.action {
   text-align: center;
 }
 
-.control-group {
-  clear: both;
-  padding: 2px 0 2px;
-}
-
-.control-group label {
-  float: left;
-  width: 120px;
-  padding-right: 5px;
-}
-
-.controls {
-  margin-left: 130px;
-}
-
 .cancel {
   font-size: 80%;
   margin-left: 7px;
 }
 
-.required {
-  font-size: 80%;
-  vertical-align: top;
-  margin-left: 2px;
-}
-
 #error_explanation h2 {
   font-size: 100%;
   margin-top: 0px;
@@ -53,3 +39,7 @@ table.table td.action {
   margin-bottom: 5px;
 }
 
+footer {
+  clear: both;
+}
+