Move docs from wiki to the project repository itself

Moving the docs allows them to more easily be developed in a first-class manner through pull requests. The docs can stay aligned with code changes as they happen within the same commit. For example, as the code gets refactored, docs may become incorrect or out of date. With the docs in the repository, this can be caught during development and review. Contributors can provide reviewable documentaiton-only changes, even small ones, thus improving the community experience. An up to date version of the docs were cloned and copied using: git clone https://github.com/railsadminteam/rails_admin.wiki.git The docs were left as-is as much as possible. If there are desired changes, these can now be opened as future pull requests. Articles that are linked to internally are not included. Changes to the wiki articles: - All previous wiki links have been converted to be compatible with GitHub flavored Markdown so links continue to work as before. - Small formatting changes to be compliant with Prettier. - References to *.coffee files were updated to *.js. - Renamed index.md to home.md to follow conventions. - Added an H1 header to all articles which was previously implicitly added by the wiki engine. Once this change lands, the wiki can be removed so as to avoid confusion for new users.
railsadminteam · Nov 28, 2021 · ee0abe7 · ee0abe7
1 parent fa0db21
commit ee0abe7
Show file tree

Hide file tree

Showing 91 changed files with 5,718 additions and 7 deletions.
diff --git a/README.md b/README.md
@@ -29,7 +29,7 @@ RailsAdmin is a Rails engine that provides an easy-to-use interface for managing
 
 [demo]: http://rails-admin-tb.herokuapp.com/
 [dummy_app]: https://github.com/bbenezech/dummy_app
-[docs]: https://github.com/railsadminteam/rails_admin/wiki
+[docs]: docs/index.md
 
 ## Features
 
@@ -59,9 +59,9 @@ RailsAdmin is a Rails engine that provides an easy-to-use interface for managing
 
 In `config/initializers/rails_admin.rb`:
 
-[Details](https://github.com/railsadminteam/rails_admin/wiki/Base-configuration)
+[Details](docs/base-configuration.md)
 
-To begin with, you may be interested in setting up [Devise](https://github.com/railsadminteam/rails_admin/wiki/Devise), [CanCanCan](https://github.com/railsadminteam/rails_admin/wiki/Cancancan) or [Papertrail](https://github.com/railsadminteam/rails_admin/wiki/Papertrail)!
+To begin with, you may be interested in setting up [Devise](docs/devise.md), [CanCanCan](docs/cancancan.md) or [Papertrail](docs/papertrail.md)!
 
 ### Per model
 
@@ -78,14 +78,14 @@ class Ball < ActiveRecord::Base
 end
 ```
 
-Details: [Models](https://github.com/railsadminteam/rails_admin/wiki/Models), [Groups](https://github.com/railsadminteam/rails_admin/wiki/Groups), [Fields](https://github.com/railsadminteam/rails_admin/wiki/Fields)
+Details: [Models](docs/models.md), [Groups](docs/groups.md), [Fields](docs/fields.md)
 
 ## Support
 
 If you have a question, please check this README, the wiki, and the [list of
 known issues][troubleshoot].
 
-[troubleshoot]: https://github.com/railsadminteam/rails_admin/wiki/Troubleshoot
+[troubleshoot]: docs/troubleshoot.md
 
 If you still have a question, you can ask the [official RailsAdmin mailing
 list][list].

diff --git a/docs/actions.md b/docs/actions.md
@@ -0,0 +1,208 @@
+## Default
+
+Actions used to be static and hard-coded. A community request was that they could be added/removed/customized.
+
+This is now possible.
+
+By default, to keep existing installation safe, all actions are added as they used to be.
+
+Default is equivalent to:
+
+```ruby
+# config/initializers/rails_admin.rb
+RailsAdmin.config do |config|
+  config.actions do
+    # root actions
+    dashboard                     # mandatory
+    # collection actions
+    index                         # mandatory
+    new
+    export
+    history_index
+    bulk_delete
+    # member actions
+    show
+    edit
+    delete
+    history_show
+    show_in_app
+  end
+end
+```
+
+## Use existing actions and customize them
+
+Simply list them and pass an optional block, like so:
+
+```ruby
+config.actions do
+  dashboard do
+    i18n_key :dash
+  end
+  index
+  new
+end
+```
+
+Please note that `dashboard` and `index` are mandatory for the moment, but this may change in the future.
+
+## Define actions
+
+- `root` defines root level actions (Dashboard, etc.)
+- `collection` defines collection level actions (Index, New, etc.)
+- `member` defines member level actions (Show, Edit, etc.)
+
+First argument is the key of the action.
+It will be the `i18n_key`, the `route_fragment`, the `action_name`, the `authorization_key`, etc.
+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.
+
+Second (optional) argument is the key of the parent class. It can be any existing Action class. If none given, it will be `Base`.
+
+Then you can pass the configuration block.
+
+Then add `app/views/rails_admin/main/my_action.html.<erb|haml>` in your application, where you will be able to access:
+
+- `@abstract_model` (except for root actions, give the RailsAdmin representation of the model. Use .model to have your ActiveRecord original model)
+- `@model_config` (except for root actions, give the RailsAdmin configuration of the model)
+- `@objects = list_entries` (for collection actions, list the entries as specified in params, see the :index action and template)
+- `@object` (member actions only, ActiveRecord object)
+
+```ruby
+config.actions do
+  root :my_dashboard, :dashboard          # subclass Dashboard. Accessible at /admin/my_dashboard
+  collection :my_collection_action do     # subclass Base. Accessible at /admin/<model_name>/my_collection_action
+    ...
+  end
+  member :my_member_action do             # subclass Base. Accessible at /admin/<model_name>/<id>/my_member_action
+    i18n_key :edit                        # will have the same menu/title labels as the Edit action.
+  end
+end
+
+```
+
+## Create a reusable action
+
+```ruby
+# somewhere in your lib/ directory:
+
+require 'rails_admin/config/actions'
+require 'rails_admin/config/actions/base'
+
+module RailsAdmin
+  module Config
+    module Actions
+      class MyAction < RailsAdmin::Config::Actions::Base
+         RailsAdmin::Config::Actions.register(self)
+         register_instance_option :my_option do
+           :default_value
+         end
+      end
+    end
+  end
+end
+
+# use it like this:
+
+config.actions do
+  my_action do
+    my_option :another_value
+  end
+end
+```
+
+If you want to share it as a gem, see [custom action](custom-action.md).
+
+## Action wording for title, menu, breadcrumb and links
+
+Default I18n key is action name underscored. You can change it like so:
+
+```ruby
+config.actions do
+  dashboard do
+    i18n_key :customized
+  end
+  ...
+end
+```
+
+Then head for your `config/locales/rails_admin.xx.yml` file:
+
+```yaml
+xx:
+  admin:
+    actions:
+      <customized>:
+        title: "..."
+        menu: "..."
+        breadcrumb: "..."
+        link: "..."
+```
+
+See [rails_admin.en.yml](../config/locales/rails_admin.en.yml) to get an idea.
+
+Actions can provide specific option configuration, check their respective wiki page.
+
+## Controlling visibility
+
+### Through authorization
+
+Authorization is done automatically before any link is displayed, any page accessed, etc.
+Check [CanCanCan](cancancan.md) for the list of key used by RailsAdmin default actions.
+
+You can change the authorization key with:
+
+```ruby
+config.actions do
+  dashboard do
+    authorization_key :customized
+  end
+  ...
+end
+```
+
+### Per-model basis
+
+```ruby
+config.actions do
+  edit do
+    only ['Player']
+  end
+  delete do
+    except ['Team', 'Ball']
+  end
+end
+```
+
+### Visible block
+
+You can use these 3 bindings to decide whereas the action should be visible or not:
+
+- `bindings[:controller]` is current controller instance
+- `bindings[:abstract_model]` is checked abstract model (except root actions)
+- `bindings[:object]` is checked instance object (member actions only)
+
+For instance, if you want to allow editing of games, but only if they haven't yet started:
+
+```ruby
+config.actions do
+  edit do
+    visible do
+      object = bindings[:object]
+      case object
+      when Game then !object.started? # only allow editing games if they haven't started
+      when Player then true           # allow editing of Players any time
+      else false                      # don't allow editing anything else
+      end
+    end
+  end
+end
+```
+
+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.
+
+Important: at some point of the application lifecycle, bindings can be nil:
+
+- when RailsAdmin creates the route
+- when RailsAdmin defines the action in its controller
+
+These bindings are available in all options.
diff --git a/docs/actiontext.md b/docs/actiontext.md
@@ -0,0 +1,61 @@
+# ActionText
+
+Rails 6 is shipped with a new rich text editor, called ActionText. RailsAdmin can make use of it in two ways.
+
+## Easy-to-use setup
+
+Follow [the official documentation](https://edgeguides.rubyonrails.org/action_text_overview.html#installation) to configure ActionText.
+
+```bash
+$ rails action_text:install
+```
+
+```ruby
+class Message < ApplicationRecord
+  has_rich_text :content
+end
+```
+
+That's it, RailsAdmin will show the rich text editor in the edit form of Message model.
+
+Please note that this setup makes use of CDN-delivered assets for simplicity, hence it lacks some features like uploading attachments.
+
+## Full-featured setup using Webpacker
+
+First, you have to setup [Webpacker](https://github.com/rails/webpacker#installation) and [ActionText](https://edgeguides.rubyonrails.org/action_text_overview.html#installation) correctly. Watch out those issues if you're an early adopter:
+
+- https://github.com/rails/webpacker/issues/2109
+- https://github.com/rails/rails/issues/36368
+
+Create `app/javascript/packs/actiontext.js` with following content:
+
+```javascript
+require("trix");
+require("@rails/actiontext");
+```
+
+Configure your rich text field to pick up Webpacker-built asset:
+
+```ruby
+  config.model 'Message' do
+    field :content do
+      js_location { bindings[:view].asset_pack_path 'actiontext.js' }
+    end
+  end
+```
+
+ActiveStorage Blob view generated by ActionText shows wrong image URL when used inside engine's path, so apply this patch to `app/views/active_storage/blobs/_blob.html.erb`:
+
+```diff
+<figure class="attachment attachment--<%= blob.representable? ? "preview" : "file" %> attachment--<%= blob.filename.extension %>">
+   <% if blob.representable? %>
+-    <%= image_tag blob.representation(resize_to_limit: local_assigns[:in_gallery] ? [ 800, 600 ] : [ 1024, 768 ]) %>
++    <%= image_tag polymorphic_url(blob.representation(resize_to_limit: local_assigns[:in_gallery] ? [ 800, 600 ] : [ 1024, 768 ]), script_name: nil) %>
+   <% end %>
+
+   <figcaption class="attachment__caption">
+```
+
+Drag and drop an image to the editor and you can now see the image uploaded and stored into ActiveStorage.
+
+[More here](../lib/rails_admin/config/fields/types/action_text.rb)