Skip to content

UPGRADING.md

Latest commit

 

History

History
225 lines (172 loc) · 11 KB

UPGRADING.md

File metadata and controls

225 lines (172 loc) · 11 KB

Upgrading Guide

From v3 to v4 (beta)

ActiveAdmin v4 uses TailwindCSS. It has mobile web, dark mode and RTL support with a default theme that can be customized through partials and CSS. This release assumes cssbundling-rails and importmap-rails is installed and configured in the host app. Partials can be modified to include a different asset library, e.g. shakapacker.

IMPORTANT: there is no sortable functionality for has-many forms in this release so if needed, do not upgrade. We are open to community proposals. The add/remove functionality for has-many forms remains supported.

These instructions assume the cssbundling-rails and importmap-rails gems are already installed and you have run their install commands in your app. If you haven't done so, please do before continuing.

Update your Gemfile with gem "activeadmin", "4.0.0.beta3" and then run gem install activeadmin --pre.

Now, run rails generate active_admin:assets to replace the old assets with the new files.

Then add the npm package and update the build:css script.

yarn add @activeadmin/activeadmin@4.0.0-beta3
npm pkg set scripts.build:css="tailwindcss -i ./app/assets/stylesheets/active_admin.css -o ./app/assets/builds/active_admin.css --minify -c tailwind-active_admin.config.js"

If you are already using Tailwind in your app, then update the build:css script to chain the above command to your existing one, e.g. "tailwindcss ... && tailwindcss ...", so both stylesheets are generated.

Many configs have been removed (meta tags, asset registration, utility nav, etc.) that can now be modified more naturally through partials.

Open the config/initializers/active_admin.rb file and remove these deleted configs.

site_title_link
site_title_image
logout_link_method
favicon
meta_tags
meta_tags_for_logged_out_pages
register_stylesheet
register_javascript
head
footer
use_webpacker

Now, run rails g active_admin:views which will copy the partials to your app so you can customize if needed.

Note that the templates can and will change across releases. There are additional partials that can be copied but they are considered private so you do so at your own risk. You will have to keep those up to date per release.

IMPORTANT: if your project has copied any ActiveAdmin, Devise, or Kaminari templates from earlier releases, those templates must be updated from this release to avoid potential errors. Path helpers in Devise templates may require using the main_app proxy. The Kaminari templates have moved to app/views/active_admin/kaminari.

With the setup complete, please review the Breaking Changes section and resolve any that may or may not impact your integration.

Breaking Changes

  • jQuery and jQuery UI have been removed.

  • The columns component has been removed. Use div's with Tailwind classes for modern, responsive layout.

    Columns Component Migration Alternative

    If you did not specify any parameters for column and if all you need is equal width columns, then this single component will restore that functionality for any number of columns.

    # app/admin/components/columns.rb
class Columns < ActiveAdmin::Component
  builder_method :columns

  def build(*args)
    super
    add_class "grid auto-cols-fr grid-flow-col gap-4 mb-4"
  end

  def column(*args, &block)
    insert_tag Arbre::HTML::Div, *args, &block
  end
end

    Using Tailwind modifiers you can further customize the number of columns for responsive/mobile support.

  • Replace default_main_content with render "show_default".

    Show Default Alternative

    If block form default_main_content do ... end was used or looking for a partial file alternative, then replace with existing, public methods.

    attributes_table_for(resource) do
  rows *active_admin_config.resource_columns
  row :a
  row :b
  # ...
end
active_admin_comments_for(resource) if active_admin_config.comments?

  • Replace as: :datepicker with Formtastic's as: :date_picker for native HTML date input.

  • Replace active_admin_comments with active_admin_comments_for(resource).

  • In a sidebar section, replace attributes_table with attributes_table_for(resource).

  • The IndexAsBlog, IndexAsBlock and IndexAsGrid components have been removed. Please create your own custom index-as components which remain supported.

  • Batch Actions Form DSL has been replaced with Rails partial support so you can supply your own custom form and modal.

    Batch Action Partial Example

    Assuming a Post resource (in the default namespace) with a mark_published batch action, we set the partial name and a set of HTML data attributes to trigger a modal using Flowbite which is included by default.

    Note that you can use any modal JS library you want as long as it can be triggered to open using data attributes. Flowbite usage is not a requirement.

    batch_action(
  :mark_published,
  partial: "mark_published_batch_action",
  link_html_options: {
    "data-modal-target": "mark-published-modal",
    "data-modal-show": "mark-published-modal"
  }
) do |ids, inputs|
  # ...
end

    In the app/views/admin/posts directory, create a _mark_published_batch_action.html.erb partial file which will be rendered and included automatically in the posts index admin page.

    Now add the modal HTML where the id attribute must match the data attributes supplied in the batch_action example. The form must have an empty data-batch-action-form attribute.

    <div id="mark-published-modal" class="hidden fixed top-0 ..." aria-hidden="true" ...>
  <!-- ... other modal content --->
  <%= form_tag false, "data-batch-action-form": "" do %>
    <!-- Declare your form inputs. You can use a different form builder too. -->
  <% end %>
</div>

    The data-batch-action-form attribute is a hook for a delegated JS event so when you submit the form, it will post and run your batch action block with the supplied form data, functioning as it did before.

  • Deeply nested submenus has been reverted. Only one level nested menu, e.g. menu parent: "Administrative", is supported.

  • Removed Panel#header_action method.

  • Removed index_column method from index table.

    Implementation Example

    You can re-implement this column with the following:

    column "Number", sortable: false do |item|
  @collection.offset_value + @collection.index(item) + 1
end

Resource named methods

With the extraction to partials, resource named methods, e.g. post or posts, used in blocks for action_item and sidebar will raise an error. You must use the resource or collection public helper method instead. For example:

action_item :view, if: ->{ post.published? } do link_to(resource) end
sidebar :author, if: ->{ post.published? }
# The above must now change to the following:
action_item :view, if: ->{ resource.published? } do link_to(resource) end
sidebar :author, if: ->{ resource.published? }

Note that @post can also be used here but make sure to call authorize! on it if using the authorization feature. The post usage would continue to work for sidebar :name do ... end content blocks because they can include Arbre but we advise using resource or collection instead where possible. This may impact other DSL's.

Visual Related Changes

  • The sidebar do ... end contents and the show resource attributes_table, are no longer wrapped in a panel so they can be customized.
  • Links in custom action_item's have no default styles. Apply your own or use the library's default action-item-button class.
  • The index table actions dropdown: true option will be ignored, reverting to original output.
  • An Arbre::Component will no longer add a CSS class using the component class name by default.
  • Typographic elements (other than links in main content) are not styled by default. Use the @tailwindcss/typography plugin or apply your own CSS alternative.

Enhancements

  • Dark mode support.
  • Mobile web support. For responsive table_for's, wrap them in a div with overflow for horizontal scrolling.
  • Customizable admin theme, including main menu and user menu, all through partials.
  • RTL support improved. Now using CSS Logical Properties.
  • Kaminari templates now consolidated into a single set you can customize.
  • Datepicker's now use the native HTML date input. Apply a custom datepicker of your choosing.
  • Batch Actions Form DSL has been replaced with partials and form builder for more customization. Please refer to earlier example.
  • The status_tag component now uses unique labels for false and nil values.
  • Several components: table_for, status_tag, etc. now use data attributes instead of classes for metadata: status, sort direction, column, etc.
  • Arbre builder methods have been reduced to the minimum so you can use elements or DSLs without clashing e.g. header, footer, columns, etc.
  • The app-helpers-not-reloading bug has been fixed and the engine namespace is now isolated.

Localization Updates

This release includes several locale changes. Please reivew the en.yml locale for the latest translations.

  • The dashboard_welcome, dropdown_actions, main_content and unsupported_browser keys have been removed.

  • Overriding Kaminari's previous and next pagination keys to only use words and remove HTML entities.

  • The active_admin.pagination keys have been rewritten to be less verbose.

    - one: "Displaying <b>1</b> %{model}"
+ one: "Showing <b>1</b> of <b>1</b>"
- one_page: "Displaying <b>all %{n}</b> %{model}"
+ one_page: "Showing <b>all %{n}</b>"
- multiple: "Displaying %{model} <b>%{from}&nbsp;-&nbsp;%{to}</b> of <b>%{total}</b> in total"
+ multiple: "Showing <b>%{from}-%{to}</b> of <b>%{total}</b>"
- multiple_without_total: "Displaying %{model} <b>%{from}&nbsp;-&nbsp;%{to}</b>"
+ multiple_without_total: "Showing <b>%{from}-%{to}</b>"
- per_page: "Per page: "
+ per_page: "Per page "

  • The search_status key contents has multiple, breaking changes:

    - headline: "Search status:"
- current_scope: "Scope:"
- current_filters: "Current filters:"
+ title: "Active Search"
+ title_with_scope: "Active Search for %{name}"
- no_current_filters: "None"
+ no_current_filters: "No filters applied"

  • The value for the status_tag.unset key has changed from "No" to "Unknown".

  • The comments.title_content text has been updated with an "All " prefix.

  • The comments.delete_confirmation text has been fixed to use singular form.

  • Inconsistent use of login/sign-in related terms so text now uses "Sign in", Sign out", and "Sign up" throughout.