|
| 1 | +## Default |
| 2 | + |
| 3 | +Actions used to be static and hard-coded. A community request was that they could be added/removed/customized. |
| 4 | + |
| 5 | +This is now possible. |
| 6 | + |
| 7 | +By default, to keep existing installation safe, all actions are added as they used to be. |
| 8 | + |
| 9 | +Default is equivalent to: |
| 10 | + |
| 11 | +```ruby |
| 12 | +# config/initializers/rails_admin.rb |
| 13 | +RailsAdmin.config do |config| |
| 14 | + config.actions do |
| 15 | + # root actions |
| 16 | + dashboard # mandatory |
| 17 | + # collection actions |
| 18 | + index # mandatory |
| 19 | + new |
| 20 | + export |
| 21 | + history_index |
| 22 | + bulk_delete |
| 23 | + # member actions |
| 24 | + show |
| 25 | + edit |
| 26 | + delete |
| 27 | + history_show |
| 28 | + show_in_app |
| 29 | + end |
| 30 | +end |
| 31 | +``` |
| 32 | + |
| 33 | +## Use existing actions and customize them |
| 34 | + |
| 35 | +Simply list them and pass an optional block, like so: |
| 36 | + |
| 37 | +```ruby |
| 38 | +config.actions do |
| 39 | + dashboard do |
| 40 | + i18n_key :dash |
| 41 | + end |
| 42 | + index |
| 43 | + new |
| 44 | +end |
| 45 | +``` |
| 46 | + |
| 47 | +Please note that `dashboard` and `index` are mandatory for the moment, but this may change in the future. |
| 48 | + |
| 49 | +## Define actions |
| 50 | + |
| 51 | +- `root` defines root level actions (Dashboard, etc.) |
| 52 | +- `collection` defines collection level actions (Index, New, etc.) |
| 53 | +- `member` defines member level actions (Show, Edit, etc.) |
| 54 | + |
| 55 | +First argument is the key of the action. |
| 56 | +It will be the `i18n_key`, the `route_fragment`, the `action_name`, the `authorization_key`, etc. |
| 57 | +You can override each of these individually. See the respective class and the [Base Action class](../lib/rails_admin/config/actions/base.rb) to get the list of these options. |
| 58 | + |
| 59 | +Second (optional) argument is the key of the parent class. It can be any existing Action class. If none given, it will be `Base`. |
| 60 | + |
| 61 | +Then you can pass the configuration block. |
| 62 | + |
| 63 | +Then add `app/views/rails_admin/main/my_action.html.<erb|haml>` in your application, where you will be able to access: |
| 64 | + |
| 65 | +- `@abstract_model` (except for root actions, give the RailsAdmin representation of the model. Use .model to have your ActiveRecord original model) |
| 66 | +- `@model_config` (except for root actions, give the RailsAdmin configuration of the model) |
| 67 | +- `@objects = list_entries` (for collection actions, list the entries as specified in params, see the :index action and template) |
| 68 | +- `@object` (member actions only, ActiveRecord object) |
| 69 | + |
| 70 | +```ruby |
| 71 | +config.actions do |
| 72 | + root :my_dashboard, :dashboard # subclass Dashboard. Accessible at /admin/my_dashboard |
| 73 | + collection :my_collection_action do # subclass Base. Accessible at /admin/<model_name>/my_collection_action |
| 74 | + ... |
| 75 | + end |
| 76 | + member :my_member_action do # subclass Base. Accessible at /admin/<model_name>/<id>/my_member_action |
| 77 | + i18n_key :edit # will have the same menu/title labels as the Edit action. |
| 78 | + end |
| 79 | +end |
| 80 | + |
| 81 | +``` |
| 82 | + |
| 83 | +## Create a reusable action |
| 84 | + |
| 85 | +```ruby |
| 86 | +# somewhere in your lib/ directory: |
| 87 | + |
| 88 | +require 'rails_admin/config/actions' |
| 89 | +require 'rails_admin/config/actions/base' |
| 90 | + |
| 91 | +module RailsAdmin |
| 92 | + module Config |
| 93 | + module Actions |
| 94 | + class MyAction < RailsAdmin::Config::Actions::Base |
| 95 | + RailsAdmin::Config::Actions.register(self) |
| 96 | + register_instance_option :my_option do |
| 97 | + :default_value |
| 98 | + end |
| 99 | + end |
| 100 | + end |
| 101 | + end |
| 102 | +end |
| 103 | + |
| 104 | +# use it like this: |
| 105 | + |
| 106 | +config.actions do |
| 107 | + my_action do |
| 108 | + my_option :another_value |
| 109 | + end |
| 110 | +end |
| 111 | +``` |
| 112 | + |
| 113 | +If you want to share it as a gem, see [custom action](custom-action.md). |
| 114 | + |
| 115 | +## Action wording for title, menu, breadcrumb and links |
| 116 | + |
| 117 | +Default I18n key is action name underscored. You can change it like so: |
| 118 | + |
| 119 | +```ruby |
| 120 | +config.actions do |
| 121 | + dashboard do |
| 122 | + i18n_key :customized |
| 123 | + end |
| 124 | + ... |
| 125 | +end |
| 126 | +``` |
| 127 | + |
| 128 | +Then head for your `config/locales/rails_admin.xx.yml` file: |
| 129 | + |
| 130 | +```yaml |
| 131 | +xx: |
| 132 | + admin: |
| 133 | + actions: |
| 134 | + <customized>: |
| 135 | + title: "..." |
| 136 | + menu: "..." |
| 137 | + breadcrumb: "..." |
| 138 | + link: "..." |
| 139 | +``` |
| 140 | +
|
| 141 | +See [rails_admin.en.yml](../config/locales/rails_admin.en.yml) to get an idea. |
| 142 | +
|
| 143 | +Actions can provide specific option configuration, check their respective wiki page. |
| 144 | +
|
| 145 | +## Controlling visibility |
| 146 | +
|
| 147 | +### Through authorization |
| 148 | +
|
| 149 | +Authorization is done automatically before any link is displayed, any page accessed, etc. |
| 150 | +Check [CanCanCan](cancancan.md) for the list of key used by RailsAdmin default actions. |
| 151 | +
|
| 152 | +You can change the authorization key with: |
| 153 | +
|
| 154 | +```ruby |
| 155 | +config.actions do |
| 156 | + dashboard do |
| 157 | + authorization_key :customized |
| 158 | + end |
| 159 | + ... |
| 160 | +end |
| 161 | +``` |
| 162 | + |
| 163 | +### Per-model basis |
| 164 | + |
| 165 | +```ruby |
| 166 | +config.actions do |
| 167 | + edit do |
| 168 | + only ['Player'] |
| 169 | + end |
| 170 | + delete do |
| 171 | + except ['Team', 'Ball'] |
| 172 | + end |
| 173 | +end |
| 174 | +``` |
| 175 | + |
| 176 | +### Visible block |
| 177 | + |
| 178 | +You can use these 3 bindings to decide whereas the action should be visible or not: |
| 179 | + |
| 180 | +- `bindings[:controller]` is current controller instance |
| 181 | +- `bindings[:abstract_model]` is checked abstract model (except root actions) |
| 182 | +- `bindings[:object]` is checked instance object (member actions only) |
| 183 | + |
| 184 | +For instance, if you want to allow editing of games, but only if they haven't yet started: |
| 185 | + |
| 186 | +```ruby |
| 187 | +config.actions do |
| 188 | + edit do |
| 189 | + visible do |
| 190 | + object = bindings[:object] |
| 191 | + case object |
| 192 | + when Game then !object.started? # only allow editing games if they haven't started |
| 193 | + when Player then true # allow editing of Players any time |
| 194 | + else false # don't allow editing anything else |
| 195 | + end |
| 196 | + end |
| 197 | + end |
| 198 | +end |
| 199 | +``` |
| 200 | + |
| 201 | +Have a look at [Show in App implementation](../lib/rails_admin/config/actions/show_in_app.rb) for a better idea of how you can take advantage of this. |
| 202 | + |
| 203 | +Important: at some point of the application lifecycle, bindings can be nil: |
| 204 | + |
| 205 | +- when RailsAdmin creates the route |
| 206 | +- when RailsAdmin defines the action in its controller |
| 207 | + |
| 208 | +These bindings are available in all options. |
0 commit comments