Usage

Configuration

RailsAdmin provides its out of the box administrative interface by inspecting your application's
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:
config/initializers/rails_admin.rb

General

You can customize authentication by providing a custom block for RailsAdmin.authenticate_with.
To disable authentication, pass an empty block:

RailsAdmin.authenticate_with {}

You can exclude models from RailsAdmin by appending those models to excluded_models:

RailsAdmin.config do |config|
config.excluded_models << ClassName
end

Navigation

hiding a model

setting the model's label

configuring the number of visible tabs

You can hide a model from the top navigation by marking its visible option
as false within the model's navigation configuration section:

By using an accessor:

RailsAdmin.config do |config|
config.model Team do
navigation do
visible = false
end
end
end

Or by passing the value as an argument:

RailsAdmin.config do |config|
config.model Team do
navigation do
visible false
end
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
navigation do
visible { false }
end
end
end

These three examples also work as a generic example of how most of the configuration options
function within RailsAdmin. You can access them with option_name = value, you
can pass a value as an argument option_name value, or you can pass in a block
which will be evaluated each time the option is read. Notable is that boolean options'
reader accessors will be appended with ? whereas the writers will not be. That is, if you
want to get the Team model's visibility in navigation, you use
RailsAdmin.config(Team).navigation.visible?.

Back to navigation configuration - there is also an alias method that can be used:

RailsAdmin.config do |config|
config.model Team do
hide_from_navigation
end
end

And also a reverse alias method to make it visible again:

RailsAdmin.config do |config|
config.model Team do
show_in_navigation
end
end

Both also accept a block:

RailsAdmin.config do |config|
config.model Team do
# Hide Team from navigation on Sundays
hide_from_navigation do
Time.now.wday == 0
end
end
end

If you need to customize the label of the model within the navigation tab, use:

RailsAdmin.config do |config|
config.model Team do
navigation do
label "List of teams"
end
end
end

Remember, you can also pass the value as an argument or as a block as with the
before mentioned visibility options. Besides that, the label also has a
shorthand syntax:

RailsAdmin.config do |config|
config.model Team do
label_for_navigation "List of teams"
end
end

Links to the rest of the models will be rendered in a drop down menu next to the
tabs. Even though this option is not model specific, it shares the same
semantics as the earlier ones - you can also pass in a block or pass the value
as an argument by omitting the equals sign.

RailsAdmin.config do |config|
config.model Team do
list do
items_per_page 100
end
end
end

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
list do
field :name
field :created_at
end
end
end

This would show only "name" and "created at" columns in the list view.

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
list do
field :name
field :created_at
field :revenue do
visible do
current_user.roles.include?(:accounting) # metacode
end
end
end
end
end

Note that above example's authorization conditional is not runnable code, just
an imaginary example. You need to provide RailsAdmin with your own
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
list do
field :name do
label "Title"
end
field :created_at do
label "Created on"
end
end
end
end

As in the previous example this would show only columns for fields "name" and
"created at" and their headers would have been renamed to "Title" and
"Created on".

The field's output can be modified:

RailsAdmin.config do |config|
config.model Team do
list do
field :name do
formatted_value do
value.to_s.upcase
end
end
field :created_at
end
end
end

This would render all the teams' names uppercased.

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
list do
field :name
field :created_at do
date_format :short
end
field :updated_at do
strftime_format "%Y-%m-%d"
end
end
end
end

This would render all the teams' "created at" dates in the short format of your
application's locale and "updated at" dates in format YYYY-MM-DD. If both
options are defined for a single field, strftime_format has precedence over
date_format option. For more information about localizing Rails see
Rails Internationalization API
and Rails I18n repository.

You can make a column non-sortable by setting the sortable option to false:

RailsAdmin.config do |config|
config.model Team do
list do
field :name
field :created_at do
sortable false
end
end
end
end

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
list do
field :name
field :created_at do
column_css_class "customClass"
end
end
end
end

This would render the "created at" field's header column with a CSS class named
"customClassHeader" and each "created at" value with a class named
"customClassRow".

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
list do
field :name do
column_width 200
end
field :created_at
end
end
end

Create and update views

field groupings

By default RailsAdmin groups fields in the edit views (create and update views)
by including all database columns and belongs to associations to "Basic info"
group which is displayed on top of form. Below that are displayed all the other
associations a model has, one group per association.

The configuration accessors are edit, create and update. First one is a
batch accessor which configures both create and update views. For consistency,
these examples only include the batch accessor edit, but if you need differing
create and update views just replace edit with create or update.

Field groups can be hidden:

RailsAdmin.config do |config|
config.model Team do
edit do
group :default do
hide
end
end
end
end

This would hide the "Basic info" group which is accessed by the symbol :default.
Associations' groups can be accessed by the name of the association, such as
:fans or :players. The hide method is just a shortcut for the actual visible
option which was mentioned in the beginning of the navigation section.

Field groups can be renamed:

RailsAdmin.config do |config|
config.model Team do
edit do
group :default do
label "Team information"
end
end
end
end

This would render "Team information" instead of "Basic info" as the groups label.

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
edit do
group :default do
label "Default group"
end
field :name do
label "Title"
group :default
end
end
end
end
RailsAdmin.config do |config|
config.model Team do
edit do
group :default do
label "Default group"
field :name do
label "Title"
end
end
end
end
end

In fact the first examples group :default configuration is unnecessary
as the default group has already initialized all fields and belongs to
associations for itself.

Just like in the list view, all fields are visible by default. If you specifically
declare fields, only defined fields will be visible and they will be presented
in the order defined. Thus both examples would render a form with
only one group (labeled "Default group") that would contain only one
element (labeled "Title").

In the list view label is the text displayed in the field's column header, but
in the edit views label literally means the html label element associated with
field's input element.

Naturally edit views' fields also have the visible option along with
hide and show accessors as the list view has.

Authorization

Rails Admin has no specific authorization requirements so you can use
whichever authz framework best suits your needs.

Declarative Authorization

Declarative Authorization
works well with Rails Admin. You need to hook
declarative_authorization's code into Rails Admin's controllers and
write appropriate authorization declarations.

You can hook declarative_authorization into Rails Admin using code
like this in an initializer (e.g., config/initializers/rails_admin.rb):

Submitting an Issue

We use the GitHub issue tracker to track bugs and
features. Before submitting a bug report or feature request, check to make sure it hasn't already
been submitted. You can indicate support for an existing issuse by voting it up. When submitting a
bug report, please include a Gist that includes a stack trace and any
details that may be necessary to reproduce the bug, including your gem version, Ruby version, and
operating system. Ideally, a bug report should include a pull request with failing specs.

Submitting a Pull Request

Fork the project.

Create a topic branch.

Implement your feature or bug fix.

Add documentation for your feature or bug fix.

Run bundle exec rake doc:yard. If your changes are not 100% documented, go back to step 4.

Add specs for your feature or bug fix.

Run bundle exec rake spec. If your changes are not 100% covered, go back to step 6.

Commit and push your changes.

Submit a pull request. Please do not include changes to the gemspec, version, or history file. (If you want to create your own version for some reason, please do so in a separate commit.)