Skip to content

Latest commit

 

History

History
860 lines (682 loc) · 25.7 KB

README.mkd

File metadata and controls

860 lines (682 loc) · 25.7 KB
Raw

RailsAdmin

RailsAdmin is a Rails engine that provides an easy-to-use interface for managing your data.

RailsAdmin started as a port of MerbAdmin to Rails 3 and was implemented as a Ruby Summer of Code project by Bogdan Gaza with mentors Erik Michaels-Ober, Yehuda Katz, Luke van der Hoeven, and Rein Henrichs.

It currently offers the following features:

  • Display database tables
  • Create new data
  • Easily update data
  • Safely delete data
  • Automatic form validation
  • Search
  • Authentication (via Devise)
  • User action history

Supported ORMs:

  • ActiveRecord

Information about support for other ORMs.

Help

If you have a question, you can ask the official RailsAdmin mailing list or ping sferik on IRC in #railsadmin on irc.freenode.net.

Screenshots

List view Edit view

Installation

In your Gemfile, add the following dependency: gem 'devise' # Devise must be required before RailsAdmin gem 'rails_admin', :git => 'git://github.com/sferik/rails_admin.git' Run: $ bundle install And then run: $ rails generate rails_admin:install_admin This task will install RailsAdmin and Devise if you don't already have it installed. Devise is strongly recommended to protect your data from anonymous users.

If you plan to use Devise, but want to use a custom model for authentication (default is User) you can provide that as an argument for the installer. For example to override the default with a Member model run: $ rails generate rails_admin:install_admin member

If you want to use the CKEditor, you need to download it from source and unpack the 'ckeditor' folder into your default 'public/javascripts' folder. If you're using any non-Windows system, you can try to use the automatic downloader: $ rake admin:ckeditor_download

When running RailsAdmin in production the images, stylesheets, and javascript assets may return 404 not found error's depending on your servers static assets configuration. To prevent this issue you can copy assets directly into your application by running: $ rake admin:copy_assets

Usage

Start the server: $ rails server You should now be able to administer your site at http://localhost:3000/admin

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

Hiding a model

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

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 two examples also work as a generic example of how most of the configuration options function within RailsAdmin. 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

NOTE - The hide_from_navigation method was originally implemented as hide_in_navigation but that name is now deprecated - you should change your code to use hide_from_navigation.

Setting the model's label

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 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

which allows both forms of configuration value passing as well.

To enable CKEditor for a field

Configure the model/field like so:

RailsAdmin.config do |config|

config.model MyModel do
  edit do
    field :description, :text do
      ckeditor do 
        true
      end
    end
  end
end

end

Configuring the number of visible tabs

You can configure the number of tabs visible in the top navigation:

RailsAdmin.config do |config|
  config.navigation.max_visible_tabs 3
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 could also pass in a block which would be evaluated at runtime.

List view

  • Number of items per page
  • Number of items per page per model
  • Default sorting
    • Configure globaly
    • Configure per model
  • Fields
    • Visibility and ordering
    • Label
    • Output formatting
    • Sortability
    • Column CSS class
    • Column width
    • The object_label method

Number of items per page

You can configure the default number of rows rendered per page:

RailsAdmin.config do |config|
  config.list.default_items_per_page = 50
end

Number of items per page per model

You can also configure it per model:

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

Default sorting

By default, rows sorted by the field id in reverse order

You can change default behavior with use two options: sort_by and sort_reverse

Default sorting - Configure globaly

RailsAdmin.config do |config|
  config.models do
    list do
      sort_by :updated_at
      sort_reverse true
    end
  end
end

Default sorting - Configure per model

RailsAdmin.config do |config|
  config.model Player do
    list do
      sort_by :name
      sort_reverse { false }
    end
  end
end

Fields - Visibility and ordering

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.

Fields - Label

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".

Fields - Output formatting

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.

The field declarations also have access to a bindings hash which contains the 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
    list do
      field :name do
        formatted_value do
          bindings[:view].tag(:img, { :src => bindings[:object].logo_url }) << value
        end
      end
      field :created_at
    end
  end
end

This would output the name column prepended with team's logo using the tag view helper. This example uses value method to access the name field's value, 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
    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.

Fields - Sortability

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

Fields - Column CSS class

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
        css_class "customClass"
      end
    end
  end
end

This would render the "created at" field's header and body columns with a CSS class named "customClass".

Fields - Column width

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

Fields - The object_label method

List section has a configuration option object_label which configures the title of a single database record.

By default it queries if the record in question has columns named "name" or "title". If neither is found it returns the model's classname appended with its database identifier. You can add label methods (or replace the default [:name, :title]) with:

RailsAdmin.config {|c| c.label_methods << :description}

This value is used in a number of places in RailsAdmin - for instance as the output of belongs to associations in the listing views of related models, as the option labels of the relational fields' input widgets in the edit views of related models and as 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
    list do
      object_label do
        "#{bindings[:object].name} - #{bindings[:object].league.name}"
      end
    end
  end
end

This would output "Team's name - Team's league's name" in all the places mentioned in paragraph above example.

Create and update views

  • Field groupings
    • Visibility
    • Labels
    • Syntax
  • Fields
    • Rendering
    • Overriding field type
    • Available field types
    • Creating a custom field type
    • Creating a custom field factory

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 groupings - visibility

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 groupings - labels

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.

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
    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.

Fields

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.

Fields - rendering

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
    edit do
      field :name do
        partial "my_awesome_partial"
      end
    end
  end
end

The partial should be placed in your applications template folder, such as app/views/rails_admin/main/_my_awesome_partial.html.erb.

One can also completely override the rendering logic:

RailsAdmin.config do |config|
  config.model Team do
    edit do
      field :name do
        render do
          bindings[:view].render :partial => partial.to_s, :locals => {:field => self}
        end
      end
    end
  end
end

That example is just the default rendering method, but it shows you that you have access to the current template's scope with bindings[:view]. There's also bindings[:object] available, which is the database record being edited. Bindings concept was introduced earlier in this document and the functionality is the same.

Fields - overriding field type

If you'd like to override the type of the field that gets instantiated, the 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
    edit do
      field :description, :string do
         # configuration here
      end
    end
  end
end

If no configuration needs to take place the configuration block could have been left out:

RailsAdmin.config do |config|
  config.model Team do
    edit do
      field :description, :string
    end
  end
end

A word of warning, if you make field declarations for the same field a number of times with a type defining second argument in place, the type definition will ditch the old field configuration and load a new field instance in place.

Fields - Available field types

RailsAdmin ships with the following field types:

  • belongs_to_association
  • boolean
  • date
  • datetime
  • decimal
  • file_upload does not initialize automatically
  • paperclip_file initializes automatically if Paperclip is present
  • float
  • has_and_belongs_to_many_association
  • has_many_association
  • has_one_association
  • integer
  • password initializes if string type column's name is password
  • string
  • text
  • time
  • timestamp
  • virtual useful for displaying data that is calculated a runtime (for example a method call on model instance)

Fields - Creating a custom field type

If you have a reuseable field you can define a custom class extending RailsAdmin::Config::Fields::Base and register it for RailsAdmin:

RailsAdmin::Config::Fields::Types::register(:my_awesome_type, MyAwesomeFieldClass)

Then you can use your custom class in a field:

RailsAdmin.config do |config|
  config.model Team do
    edit do
      field :name, :my_awesome_type do
         # configuration here
      end
    end
  end
end

Fields - Creating a custom field factory

Type guessing can be overridden by registering a custom field "factory", but for now you need to study lib/rails_admin/config/fields/factories/* for examples if you want to use that mechanism.

Mass Assignment Operations

  • Mass assign for every model configuration
  • Mass assign for every section (create, list, navigation and update)
  • Mass assign by field type

Mass assign for every model configuration

Mass assignment operations are used to pass in configuration blocks for multiple targets at once. For instance, the code below configures every models' label displayed uppercased in the list view.

RailsAdmin.config do |config|
  config.models do
    list do
      label do
        label.upcase # in this context label refers to default label method
      end
    end
  end
end

Mass assign for every section (create, list, navigation and update)

If one would like to assign that same behavior for all the different views in RailsAdmin (create, list, navigation and update) one could pass the label definition one level higher:

RailsAdmin.config do |config|
  config.models do
    label do
      label.upcase
    end
  end
end

Naturally this also works for a single model configuration:

RailsAdmin.config do |config|
  config.model Team do
    label do
      label.upcase
    end
  end
end

Mass assign by field type

One can also assign configurations for all fields by type. For instance modifying the date presentation of all datetime fields in all sections can be accomplished like this:

RailsAdmin.config do |config|
  config.models do
    fields_of_type :datetime do
      strftime_format "%Y-%m-%d"
    end
  end
end

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):

require "rails_admin/application_controller"

module RailsAdmin
  class ApplicationController < ::ApplicationController
    filter_access_to :all
  end
end

By default, access to the controllers will be denied to all users, so you need to write some authz rules so that the appropriate users can get access. These rules will vary, but here's an example:

authorization do
  role :admin do
    has_permission_on :rails_admin_history, :to => :list
    has_permission_on :rails_admin_main, :to => [:index, :show, :new, :edit, :create, :update, :destroy, :list, :delete, :get_pages, :show_history]
  end
end

This will allow the :admin role to do everything, and will prevent all other roles from doing anything.

Contributing

In the spirit of free software, everyone is encouraged to help improve this project.

Here are some ways you can contribute:

  • by using alpha, beta, and prerelease versions
  • by reporting bugs
  • by suggesting new features
  • by translating to a new language
  • by writing or editing documentation
  • by writing specifications
  • by writing code (no patch is too small: fix typos, add comments, clean up inconsistent whitespace)
  • by refactoring code
  • by resolving issues
  • by reviewing patches

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

  1. Fork the project.
  2. Create a topic branch.
  3. Implement your feature or bug fix. NOTE - there's a small test app located in the spec/dummy_app directory that you can use to experiment with rails_admin.
  4. Add documentation for your feature or bug fix.
  5. Run bundle exec rake doc:yard. If your changes are not 100% documented, go back to step 4.
  6. Add specs for your feature or bug fix.
  7. Run bundle exec rake spec. If your changes are not 100% covered, go back to step 6.
  8. Commit and push your changes.
  9. 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.)

Contact

If you have questions about contributing to RailsAdmin, please contact Erik Michaels-Ober and Bogdan Gaza.