Skip to content
Browse files

Allow configuration within model classes, discussed in #275 and #289.…

… Fixes #275

Conflicts:

	README.md
  • Loading branch information...
1 parent d84a10a commit fb334694d23bf5aaa2d64c40914c964523f9e39e @bbenezech bbenezech committed Jul 4, 2011
Showing with 176 additions and 92 deletions.
  1. +151 −92 README.md
  2. +4 −0 config/initializers/active_record_extensions.rb
  3. +4 −0 lib/rails_admin/engine.rb
  4. +17 −0 spec/lib/config_spec.rb
View
243 README.md
@@ -47,6 +47,13 @@ If you have good reasons to think you found a *rails_admin* bug, submit a ticket
API Update Note
---------------
+`ActiveRecord::Base.rails_admin` is the new recommendation for configuring
+models. The old API is not deprecated as the new one is just a proxy for
+`RailsAdmin::Config.model`.
+
+`navigation.max_visible_tabs` is not configurable anymore, as the new Activo
+theme implements the main navigation as a vertical list.
+
`object_label` is not directly configurable anymore, as it lead to performance issues when used with a list of records.
Please use object_label_method instead.
@@ -115,10 +122,31 @@ RailsAdmin provides its out of the box administrative interface by inspecting yo
models and following some Rails conventions. For a more tailored experience, it also provides a
configuration DSL which allows you to customize many aspects of the interface.
-The configuration code should be placed in an initializer file, for example:
+The configuration code should be placed within model classes, for example:
+
+ app/models/team.rb
+
+ class Team < ActiveRecord::Base
+ rails_admin do
+ label "List of teams"
+ end
+ end
+
+Configuration code that is not specific to any model, such as options listed in
+the following General section and later in Mass Assignment Operations, should
+be placed in an initializer file, for example:
config/initializers/rails_admin.rb
+ RailsAdmin.config do |config|
+ config.models do
+ list do
+ fields_of_type :datetime do
+ date_format :compact
+ end
+ end
+ end
+ end
### General
@@ -163,8 +191,8 @@ sure that new models are not automatically added to RailsAdmin, e.g. because of
If you need to customize the label of the model, use:
- RailsAdmin.config do |config|
- config.model Team do
+ class Team < ActiveRecord::Base
+ rails_admin do
label "List of teams"
end
end
@@ -190,15 +218,19 @@ related models and for part of the audit information stored in the history
records--so keep in mind that this configuration option has widespread
effects.
- RailsAdmin.config do |config|
- config.model Team do
+ class Team < ActiveRecord::Base
+ rails_admin do
object_label_method do
:custom_label_method
end
end
+<<<<<<< HEAD
end
def Team<ActiveRecord::Base
+=======
+
+>>>>>>> d035100... Allow configuration within model classes, discussed in #275 and #289. Fixes #275
def custom_label_method
"Team #{self.name}"
end
@@ -224,16 +256,16 @@ as false:
By passing the value as an argument:
- RailsAdmin.config do |config|
- config.model Team do
+ class Team < ActiveRecord::Base
+ rails_admin do
visible false
end
end
Or by passing a block that will be lazy evaluated each time the option is read:
- RailsAdmin.config do |config|
- config.model Team do
+ class Team < ActiveRecord::Base
+ rails_admin do
visible { false }
end
end
@@ -261,17 +293,16 @@ evaluated at runtime.
**Create a dropdown menu in navigation**
-This will desactivate config.navigation.max_visible_tabs.
-
- RailsAdmin.config do |config|
- ..
- config.model Team do
+ class Team < ActiveRecord::Base
+ rails_admin do
parent League
end
- config.model Division do
+ end
+ ...
+ class Division < ActiveRecord::Base
+ rails_admin do
parent League
end
- ..
end
Obtained navigation:
@@ -289,12 +320,10 @@ This can be easily achieved with the 'dropdown' attribute of the parent model.
Added to previous example:
- RailsAdmin.config do |config|
- ...
- config.model League do
+ class League < ActiveRecord::Base
+ rails_admin do
dropdown 'League related'
end
- ...
end
Obtained navigation:
@@ -317,8 +346,8 @@ menu subset. (but parent will always be first inside his submenu).
Example:
- RailsAdmin.config do |config|
- config.model League do
+ class League < ActiveRecord::Base
+ rails_admin do
dropdown 'League related'
weight -1
end
@@ -354,8 +383,8 @@ You can configure the default number of rows rendered per page:
You can also configure it per model:
- RailsAdmin.config do |config|
- config.model Team do
+ class Team < ActiveRecord::Base
+ rails_admin do
list do
items_per_page 100
end
@@ -381,8 +410,8 @@ You can change default behavior with use two options: `sort_by` and `sort_revers
**Default sorting - Configure per model**
- RailsAdmin.config do |config|
- config.model Player do
+ class Player < ActiveRecord::Base
+ rails_admin do
list do
sort_by :name
sort_reverse false
@@ -400,8 +429,8 @@ Belongs_to associations :
you can also specify a column on the targetted table (see example) (3)
- RailsAdmin.config do |config|
- config.model Player do
+ class Player < ActiveRecord::Base
+ rails_admin do
list do
field :created_at do # (1)
sortable false
@@ -421,17 +450,17 @@ Belongs_to associations :
Default sort column is :id for ActiveRecord version
To change it:
- RailsAdmin.config do |config|
- config.model Team do
+ class Team < ActiveRecord::Base
+ rails_admin do
sort_by :nam
end
end
By default, dates and serial ids are reversed when first-sorted ('desc' instead of 'asc' in SQL).
If you want to reverse (or cancel it) the default sort order (first column click or the default sort column):
- RailsAdmin.config do |config|
- config.model Team do
+ class Team < ActiveRecord::Base
+ rails_admin do
list do
field :id do
sort_reverse? false # will sort id increasing ('asc') first ones first (default is last ones first)
@@ -456,8 +485,8 @@ Belongs_to associations :
will be searched on their label if label is not virtual (:name, :title, etc.)
you can also specify columns on the targetted table (see example) (4)
- RailsAdmin.config do |config|
- config.model Player do
+ class Player < ActiveRecord::Base
+ rails_admin do
list do
field :created_at do # (1)
searchable false
@@ -495,8 +524,8 @@ By default all fields are visible, but they are not presented in any particular
order. If you specifically declare fields, only defined fields will be visible
and they will be presented in the order defined:
- RailsAdmin.config do |config|
- config.model Team do
+ class Team < ActiveRecord::Base
+ rails_admin do
list do
field :name
field :created_at
@@ -510,8 +539,8 @@ If you need to hide fields based on some logic on runtime (for instance
authorization to view field) you can pass a block for the `visible` option
(including its `hide` and `show` accessors):
- RailsAdmin.config do |config|
- config.model Team do
+ class Team < ActiveRecord::Base
+ rails_admin do
list do
field :name
field :created_at
@@ -532,8 +561,8 @@ authorization scheme for which you can find a guide at the end of this file.
The header of a list view column can be changed with the familiar label method:
- RailsAdmin.config do |config|
- config.model Team do
+ class Team < ActiveRecord::Base
+ rails_admin do
list do
field :name do
label "Title"
@@ -553,8 +582,8 @@ As in the previous example this would show only columns for fields "name" and
The field's output can be modified:
- RailsAdmin.config do |config|
- config.model Team do
+ class Team < ActiveRecord::Base
+ rails_admin do
list do
field :name do
formatted_value do
@@ -573,8 +602,8 @@ current record instance in key :object and the view instance in key :view.
Via :object we can access other columns' values and via :view we can access our
application's view helpers:
- RailsAdmin.config do |config|
- config.model Team do
+ class Team < ActiveRecord::Base
+ rails_admin do
list do
field :name do
formatted_value do
@@ -593,8 +622,8 @@ but that could be written more verbosely as `bindings[:object].name`.
Fields of different date types (date, datetime, time, timestamp) have two extra
options to set the time formatting:
- RailsAdmin.config do |config|
- config.model Team do
+ class Team < ActiveRecord::Base
+ rails_admin do
list do
field :name
field :created_at do
@@ -619,8 +648,8 @@ and [Rails I18n repository](https://github.com/svenfuchs/rails-i18n/tree/master/
By default each column has a CSS class set according to field's data type. You
can customize this by:
- RailsAdmin.config do |config|
- config.model Team do
+ class Team < ActiveRecord::Base
+ rails_admin do
list do
field :name
field :created_at do
@@ -639,8 +668,8 @@ By default columns' widths are calculated from certain pre-defined,
data-type-specific pixel values. If you want to ensure a minimum width for a
column, you can:
- RailsAdmin.config do |config|
- config.model Team do
+ class Team < ActiveRecord::Base
+ rails_admin do
list do
field :name do
column_width 200
@@ -673,8 +702,8 @@ form builder then provide an override for the edit view or independingly for the
create and update views. The argument is a symbol or string that is sent to the view
to process the form. This is handy for integrating things like the nested form builder (https://github.com/ryanb/nested_form) if you need to override a field's edit template.
- RailsAdmin.config do |config|
- config.model Team do
+ class Team < ActiveRecord::Base
+ rails_admin do
edit do
form_builder :nested_form_for
field :name
@@ -684,8 +713,8 @@ to process the form. This is handy for integrating things like the nested form b
or independently
- RailsAdmin.config do |config|
- config.model Team do
+ class Team < ActiveRecord::Base
+ rails_admin do
create do
form_builder :create_form_for
field :name
@@ -713,8 +742,8 @@ create and update views just replace `edit` with `create` or `update`.
Field groups can be hidden:
- RailsAdmin.config do |config|
- config.model Team do
+ class Team < ActiveRecord::Base
+ rails_admin do
edit do
group :default do
hide
@@ -732,8 +761,8 @@ option which was mentioned in the beginning of the navigation section.
Field groups can be renamed:
- RailsAdmin.config do |config|
- config.model Team do
+ class Team < ActiveRecord::Base
+ rails_admin do
edit do
group :default do
label "Team information"
@@ -744,15 +773,36 @@ Field groups can be renamed:
This would render "Team information" instead of "Basic info" as the groups label.
+<<<<<<< HEAD
+=======
+**Field groupings - help**
+
+Field groups can have a set of instructions which is displayed under the label:
+
+ class Team < ActiveRecord::Base
+ rails_admin do
+ edit do
+ group :default do
+ label "Team information"
+ help "Please fill all informations related to your team..."
+ end
+ end
+ end
+ end
+
+This content is mostly useful when the admin doign the data entry is not familiar with the system or as a way to display inline documentation.
+
+
+>>>>>>> d035100... Allow configuration within model classes, discussed in #275 and #289. Fixes #275
**Field groupings - syntax**
As in the list view, the edit views' configuration blocks can directly
contain field configurations, but in edit views those configurations can
also be nested within group configurations. Below examples result an
equal configuration:
- RailsAdmin.config do |config|
- config.model Team do
+ class Team < ActiveRecord::Base
+ rails_admin do
edit do
group :default do
label "Default group"
@@ -765,8 +815,8 @@ equal configuration:
end
end
- RailsAdmin.config do |config|
- config.model Team do
+ class Team < ActiveRecord::Base
+ rails_admin do
edit do
group :default do
label "Default group"
@@ -802,8 +852,8 @@ hide and show accessors as the list view has.
The edit view's fields are rendered using partials. Each field type has its own
partial per default, but that can be overridden:
- RailsAdmin.config do |config|
- config.model Team do
+ class Team < ActiveRecord::Base
+ rails_admin do
edit do
field :name do
partial "my_awesome_partial"
@@ -817,8 +867,8 @@ The partial should be placed in your applications template folder, such as
One can also completely override the rendering logic:
- RailsAdmin.config do |config|
- config.model Team do
+ class Team < ActiveRecord::Base
+ rails_admin do
edit do
field :name do
render do
@@ -842,8 +892,8 @@ field method provides second parameter which is field type as a symbol. For
instance, if we have a column that's a text column in the database, but we'd
like to have it as a string type we could accomplish that like this:
- RailsAdmin.config do |config|
- config.model Team do
+ class Team < ActiveRecord::Base
+ rails_admin do
edit do
field :description, :string do
# configuration here
@@ -855,8 +905,8 @@ like to have it as a string type we could accomplish that like this:
If no configuration needs to take place the configuration block could have been
left out:
- RailsAdmin.config do |config|
- config.model Team do
+ class Team < ActiveRecord::Base
+ rails_admin do
edit do
field :description, :string
end
@@ -901,8 +951,8 @@ If you have a reusable field you can define a custom class extending
Then you can use your custom class in a field:
- RailsAdmin.config do |config|
- config.model Team do
+ class Team < ActiveRecord::Base
+ rails_admin do
edit do
field :name, :my_awesome_type do
# configuration here
@@ -922,8 +972,8 @@ examples if you want to use that mechanism.
Every field is accompanied by a hint/text help based on model's validations.
Everything can be overridden with `help`:
- RailsAdmin.config do |config|
- config.model Team do
+ class Team < ActiveRecord::Base
+ rails_admin do
edit do
field :name
field :email do
@@ -941,10 +991,15 @@ Everything can be overridden with `help`:
# handling delete in your model, if needed. Replace all image occurences with your asset name.
attr_accessor :delete_image
before_save { self.image = nil if self.delete_image == '1' }
+<<<<<<< HEAD
end
RailsAdmin.config do |config|
config.model Team do
+=======
+
+ rails_admin do
+>>>>>>> d035100... Allow configuration within model classes, discussed in #275 and #289. Fixes #275
edit do
field :image do
thumb_method :thumb # for images. Will default to full size image, which might break the layout
@@ -961,17 +1016,21 @@ You can use `enum_method` to indicate the name of the enumeration method in your
You can use `enum` to override any `enum_method` and give back a `FormOptionsHelper#options_for_select` collection.
class Team < ActiveRecord::Base
- ...
def color_enum
[['blue', 'red'], 'red']
# should return any collection accepted by `FormOptionsHelper#options_for_select`
# See http://api.rubyonrails.org/classes/ActionView/Helpers/FormOptionsHelper.html#method-i-options_for_select
end
+<<<<<<< HEAD
...
end
RailsAdmin.config do |config|
config.model Team do
+=======
+
+ rails_admin do
+>>>>>>> d035100... Allow configuration within model classes, discussed in #275 and #289. Fixes #275
edit do
field :color
# defaults to
@@ -986,8 +1045,8 @@ You can use `enum` to override any `enum_method` and give back a `FormOptionsHel
If you don't have any enumeration method in your model, this will work:
- RailsAdmin.config do |config|
- config.model Team do
+ class Team < ActiveRecord::Base
+ rails_admin do
edit do
field :color, :enum do
enum do
@@ -1002,8 +1061,8 @@ If you don't have any enumeration method in your model, this will work:
CKEditor can be enabled on fields of type text:
- RailsAdmin.config do |config|
- config.model MyModel do
+ class MyModel < ActiveRecord::Base
+ rails_admin do
edit do
field :description, :text do
ckeditor true
@@ -1017,8 +1076,8 @@ CKEditor can be enabled on fields of type text:
Orderable can be enabled on filtering multiselect fields (has_many, has_many :through & has_and_belongs_to_many associations), allowing selected options to be moved up/down.
RailsAdmin will handle ordering in and out of the form.
- RailsAdmin.config do |config|
- config.model Player do
+ class Player < ActiveRecord::Base
+ rails_admin do
edit do
field :fans do
orderable true
@@ -1048,14 +1107,14 @@ You can exclude specific fields with exclude_fields & exclude_fields_if:
Example:
- RailsAdmin.config do |config|
- config.model League do
+ class League < ActiveRecord::Base
+ rails_admin do
list do
exclude_fields_if do
type == :datetime
end
- exclude_fields :id, :name
+ exclude_fields :id, :name
end
end
end
@@ -1066,13 +1125,13 @@ But you can then use include_all_fields to add all default fields:
Example:
- RailsAdmin.config do |config|
- config.model League do
+ class League < ActiveRecord::Base
+ rails_admin do
list do
field :name do
# snipped specific configuration for name attribute
end
-
+
include_all_fields # all other default fields will be added after, conveniently
exclude_fields :created_at # but you still can remove fields
end
@@ -1085,15 +1144,15 @@ It is also possible to add fields by group and configure them by batches:
Example:
- RailsAdmin.config do |config|
- config.model League do
+ class League < ActiveRecord::Base
+ rails_admin do
list do
# all selected fields will be added, but you can't configure them.
# If you need to select them by type, see *fields_of_type*
include_fields_if do
name =~ /displayed/
end
-
+
include_fields :name, :title # simply adding fields by their names (order will be maintained)
fields :created_at, :updated_at do # adding and configuring
label do
@@ -1149,8 +1208,8 @@ configuration is only effective for create, list and update views.
Naturally this also works for a single model configuration:
- RailsAdmin.config do |config|
- config.model Team do
+ class Team < ActiveRecord::Base
+ rails_admin do
fields do
label do
label.upcase
View
4 config/initializers/active_record_extensions.rb
@@ -1,5 +1,9 @@
if defined?(::ActiveRecord)
class ActiveRecord::Base
+ def self.rails_admin(&block)
+ RailsAdmin::Config.model(self, &block)
+ end
+
def rails_admin_default_object_label_method
"#{self.class.to_s} ##{self.try :id}"
end
View
4 lib/rails_admin/engine.rb
@@ -8,5 +8,9 @@ class Engine < Rails::Engine
app.middleware.insert_after ::ActionDispatch::Static, ::ActionDispatch::Static, "#{root}/public"
end
end
+
+ config.to_prepare do
+ RailsAdmin::Config.reset
+ end
end
end
View
17 spec/lib/config_spec.rb
@@ -0,0 +1,17 @@
+require 'spec_helper'
+
+describe RailsAdmin::Config do
+
+ describe "ActiveRecord::Base.rails_admin" do
+
+ let(:config) { lambda {} }
+
+ it "should proxy to RailsAdmin::Config.model" do
+ RailsAdmin::Config.should_receive(:model) do |*args, &block|
+ args[0].should eql(Team)
+ block.should eql(config)
+ end
+ Team.rails_admin(&config)
+ end
+ end
+end

0 comments on commit fb33469

Please sign in to comment.
Something went wrong with that request. Please try again.