From bcfbd172c6aeeaf553146d72814090f76dc282a0 Mon Sep 17 00:00:00 2001 From: Javier Julio Date: Sat, 29 Jul 2023 00:33:58 -0400 Subject: [PATCH 01/12] Sidebars and Panels update --- docs/6-show-pages.md | 1 + docs/7-sidebars.md | 1 + 2 files changed, 2 insertions(+) diff --git a/docs/6-show-pages.md b/docs/6-show-pages.md index e5f3bd1256d..4d64ad16e14 100644 --- a/docs/6-show-pages.md +++ b/docs/6-show-pages.md @@ -70,6 +70,7 @@ ActiveAdmin.register Book do end sidebar :details, only: :show do + h3 "Details" attributes_table_for book do row :title row :author diff --git a/docs/7-sidebars.md b/docs/7-sidebars.md index 4c5e5e000a0..db410176d31 100644 --- a/docs/7-sidebars.md +++ b/docs/7-sidebars.md @@ -18,6 +18,7 @@ You can also use [Arbre](https://github.com/activeadmin/arbre) to define HTML co ```ruby sidebar :help do + h3 "Help" ul do li "Second List First Item" li "Second List Second Item" From 7e8d09c65dd1dc122dde4445d676af873e6fad11 Mon Sep 17 00:00:00 2001 From: Javier Julio Date: Sat, 22 Jul 2023 16:54:43 -0400 Subject: [PATCH 02/12] StatusTag updates --- docs/12-arbre-components.md | 35 +++++++++++++++++++++-------------- 1 file changed, 21 insertions(+), 14 deletions(-) diff --git a/docs/12-arbre-components.md b/docs/12-arbre-components.md index 13b14da38ce..950b4d4d85e 100644 --- a/docs/12-arbre-components.md +++ b/docs/12-arbre-components.md @@ -164,31 +164,38 @@ end ## Status tag Status tags provide convenient syntactic sugar for styling items that have -status. A common example of where the status tag could be useful is for orders -that are complete or in progress. `status_tag` takes a status, like -"In Progress", and a hash of options. The status_tag will generate HTML markup -that Active Admin CSS uses in styling. +status. A common usage is for boolean fields or a named status like "Complete" +or "In progress". The `status_tag` will generate HTML markup and a base style +is applied. Customize with your own CSS classes and styles. ```ruby status_tag 'In Progress' -# => In Progress +# => In Progress -status_tag 'active', class: 'important', id: 'status_123', label: 'on' -# => on +status_tag 'Active', class: 'important', id: 'status_123', label: 'on' +# => on ``` -When providing a `true` or `false` value, the `status_tag` will display "Yes" -or "No". This can be configured through the `"en.active_admin.status_tag"` -locale. +When providing a `true`, `false`, or `nil` value, the `status_tag` will display +"Yes", "No", or "Unknown" by default. ```ruby status_tag true -# => Yes +# => Yes +``` + +```ruby +status_tag false +# => No ``` -In the case that a boolean field is `nil`, it will display "No" as a default. -But using the `"en.active_admin.status_tag.unset"` locale key, it can be -configured to display something else. +```ruby +status_tag nil +# => Unknown +``` + +The default labels can be configured through the `"en.active_admin.status_tag"` +locale. ## Tabs From 482b45b2b5143763c4f2a4d7407665f17acd502a Mon Sep 17 00:00:00 2001 From: Javier Julio Date: Fri, 29 Dec 2023 10:52:13 -0500 Subject: [PATCH 03/12] Columns component was removed --- docs/12-arbre-components.md | 78 ------------------------------------- 1 file changed, 78 deletions(-) diff --git a/docs/12-arbre-components.md b/docs/12-arbre-components.md index 950b4d4d85e..feb287419b7 100644 --- a/docs/12-arbre-components.md +++ b/docs/12-arbre-components.md @@ -52,84 +52,6 @@ show do end ``` -## Columns - -The Columns component allows you draw content into scalable columns. All you -need to do is define the number of columns and the component will take care of -the rest. - -### Simple Columns - -To create simple columns, use the `columns` method. Within the block, call -the #column method to create a new column. - -```ruby -columns do - column do - span "Column #1" - end - - column do - span "Column #2" - end -end -``` - -### Spanning Multiple Columns - -To create columns that have multiple spans, pass the :span option to the column -method. - -```ruby -columns do - column span: 2 do - span "Column # 1" - end - column do - span "Column # 2" - end -end -``` - -By default, each column spans 1 column. The above layout would have 2 columns, -the first being twice as large as the second. - -### Custom Column Widths - -Active Admin uses a fluid width layout, causing column width to be defined -using percentages. Due to using this style of layout, columns can shrink or -expand past points that may not be desirable. To overcome this issue, -columns provide `:max_width` and `:min_width` options. - -```ruby -columns do - column max_width: "200px", min_width: "100px" do - span "Column # 1" - end - column do - span "Column # 2" - end -end -``` - -In the above example, the first column will not grow larger than 200px and will -not shrink less than 100px. - -### Custom Column Class - -Pass the `:class` option to the column method to set a custom class. - -```ruby -columns do - column class: "important" do - span "Column # 1" - end - column do - span "Column # 2" - end -end -``` - ## Table For Table For provides the ability to create tables like those present From 956dbe24341b240425497bd49fe48915f7b82fc5 Mon Sep 17 00:00:00 2001 From: Javier Julio Date: Fri, 29 Dec 2023 11:05:38 -0500 Subject: [PATCH 04/12] Docs: remove deeply nested menus --- docs/2-resource-customization.md | 15 +++------------ 1 file changed, 3 insertions(+), 12 deletions(-) diff --git a/docs/2-resource-customization.md b/docs/2-resource-customization.md index fa4ef03ed61..87359e22148 100644 --- a/docs/2-resource-customization.md +++ b/docs/2-resource-customization.md @@ -174,11 +174,10 @@ The menu method accepts a hash with the following options: * `:label` - The string or proc label to display in the menu. If it's a proc, it will be called each time the menu is rendered. -* `:parent` - The string id (or label) of the parent used for this menu, or an array - of string ids (or labels) for a nested menu +* `:parent` - The string id (or label) of the parent used for this menu. * `:if` - A block or a symbol of a method to call to decide if the menu item - should be displayed -* `:priority` - The integer value of the priority, which defaults to `10` + should be displayed. +* `:priority` - The integer value of the priority, which defaults to `10`. ### Labels @@ -238,14 +237,6 @@ end Note that the "Blog" parent menu item doesn't even have to exist yet; it can be dynamically generated for you. -To further nest an item under a submenu, provide an array of parents. - -```ruby -ActiveAdmin.register Post do - menu parent: ["Admin", "Blog"] -end -``` - ### Customizing Parent Menu Items All of the options given to a standard menu item are also available to From ccd203ef55e4c355a07f6e3c85ea6fef99151c4d Mon Sep 17 00:00:00 2001 From: Javier Julio Date: Fri, 29 Dec 2023 17:51:04 -0500 Subject: [PATCH 05/12] Helpers reload bug has been fixed --- docs/14-gotchas.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/docs/14-gotchas.md b/docs/14-gotchas.md index efcff41cd41..c9726419e49 100644 --- a/docs/14-gotchas.md +++ b/docs/14-gotchas.md @@ -27,15 +27,9 @@ post](https://www.mobomo.com/2013/03/rails-assets-prefix-may-disable-your-sessio ## Helpers -There are two known gotchas with helpers. This hopefully will help you to +There is a known gotcha with helpers. This hopefully will help you to find a solution. -### Helpers are not reloading in development - -This is a known and still open -[issue](https://github.com/activeadmin/activeadmin/issues/697) the only way is -to restart your server each time you change a helper. - ### Helper maybe not included by default If you use `config.action_controller.include_all_helpers = false` in your From ae13426182bc956439a16d0319987eaae0279b9a Mon Sep 17 00:00:00 2001 From: Javier Julio Date: Tue, 2 Jan 2024 18:05:50 -0500 Subject: [PATCH 06/12] The default_main_content method was removed --- docs/6-show-pages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/6-show-pages.md b/docs/6-show-pages.md index 4d64ad16e14..973fbe59164 100644 --- a/docs/6-show-pages.md +++ b/docs/6-show-pages.md @@ -85,7 +85,7 @@ If you want to keep the default show contents, but add something else around it: ```ruby show do - default_main_content + render "show_default" h3 "Other Details" # ... end From ef19435bdd2987805522586c7c49e547df095d2b Mon Sep 17 00:00:00 2001 From: Javier Julio Date: Fri, 29 Dec 2023 18:17:20 -0500 Subject: [PATCH 07/12] Remove grid/block/blog index docs --- docs/3-index-pages.md | 7 +-- docs/3-index-pages/index-as-block.md | 19 -------- docs/3-index-pages/index-as-blog.md | 69 ---------------------------- docs/3-index-pages/index-as-grid.md | 27 ----------- 4 files changed, 1 insertion(+), 121 deletions(-) delete mode 100644 docs/3-index-pages/index-as-block.md delete mode 100644 docs/3-index-pages/index-as-blog.md delete mode 100644 docs/3-index-pages/index-as-grid.md diff --git a/docs/3-index-pages.md b/docs/3-index-pages.md index ff1a8edd3a6..acb87ee93de 100644 --- a/docs/3-index-pages.md +++ b/docs/3-index-pages.md @@ -8,12 +8,7 @@ Filtering and listing resources is one of the most important tasks for administering a web application. Active Admin provides many different tools for you to build a compelling interface into your data for the admin staff. -Built in, Active Admin has the following index renderers: - -* *Table*: A table drawn with each row being a resource ([View Table Docs](3-index-pages/index-as-table.md)) -* *Grid*: A set of rows and columns each cell being a resource ([View Grid Docs](3-index-pages/index-as-grid.md)) -* *Blocks*: A set of rows (not tabular) each row being a resource ([View Blocks Docs](3-index-pages/index-as-block.md)) -* *Blog*: A title and body content, similar to a blog index ([View Blog Docs](3-index-pages/index-as-blog.md)) +Built in, Active Admin has the *Table* index renderer. ([View Table Docs](3-index-pages/index-as-table.md)) All index pages also support scopes, filters, pagination, action items, and sidebar sections. diff --git a/docs/3-index-pages/index-as-block.md b/docs/3-index-pages/index-as-block.md deleted file mode 100644 index db5c32c1252..00000000000 --- a/docs/3-index-pages/index-as-block.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -redirect_from: /docs/3-index-pages/index-as-block.html ---- - -# Index as a Block - -If you want to fully customize the display of your resources on the index -screen, Index as a Block allows you to render a block of content for each -resource. - -```ruby -index as: :block do |product| - div for: product do - resource_selection_cell product - h2 auto_link product.title - div simple_format product.description - end -end -``` diff --git a/docs/3-index-pages/index-as-blog.md b/docs/3-index-pages/index-as-blog.md deleted file mode 100644 index 212646c578e..00000000000 --- a/docs/3-index-pages/index-as-blog.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -redirect_from: /docs/3-index-pages/index-as-blog.html ---- - -# Index as Blog - -Render your index page as a set of posts. The post has two main options: -title and body. - -```ruby -index as: :blog do - title :my_title # Calls #my_title on each resource - body :my_body # Calls #my_body on each resource -end -``` - -## Post Title - -The title is the content that will be rendered within a link to the -resource. There are two main ways to set the content for the title - -First, you can pass in a method to be called on your resource. For example: - -```ruby -index as: :blog do - title :a_method_to_call -end -``` - -Second, you can pass a block to the tile option which will then be -used as the contents of the title. The resource being rendered -is passed in to the block. For Example: - -```ruby -index as: :blog do - title do |post| - span post.title, class: 'title' - span post.created_at, class: 'created_at' - end -end -``` - -## Post Body - -The body is rendered underneath the title of each post. The same two -style of options work as the Post Title above. - -Call a method on the resource as the body: - -```ruby -index as: :blog do - title :my_title - body :my_body -end -``` - -Or, render a block as the body: - -```ruby -index as: :blog do - title :my_title - body do |post| - div truncate post.title - div class: 'meta' do - span "Post in #{post.categories.join(', ')}" - end - end -end -``` diff --git a/docs/3-index-pages/index-as-grid.md b/docs/3-index-pages/index-as-grid.md deleted file mode 100644 index c4e5f92ae73..00000000000 --- a/docs/3-index-pages/index-as-grid.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -redirect_from: /docs/3-index-pages/index-as-grid.html ---- - -# Index as a Grid - -Sometimes you want to display the index screen for a set of resources as a grid -(possibly a grid of thumbnail images). To do so, use the :grid option for the -index block. - -```ruby -index as: :grid do |product| - link_to image_tag(product.image_path), admin_product_path(product) -end -``` - -The block is rendered within a cell in the grid once for each resource in the -collection. The resource is passed into the block for you to use in the view. - -You can customize the number of columns that are rendered using the columns -option: - -```ruby -index as: :grid, columns: 5 do |product| - link_to image_tag(product.image_path), admin_product_path(product) -end -``` From 041e03545bfdcfa5cb53d93a746a2e4fc4dad8cf Mon Sep 17 00:00:00 2001 From: Javier Julio Date: Fri, 29 Dec 2023 18:26:52 -0500 Subject: [PATCH 08/12] Remove configs that no longer exist These have been replaced with partials that can be extracted and customized. We'll add new docs on what those partials are. --- docs/1-general-configuration.md | 34 +-------------------------------- 1 file changed, 1 insertion(+), 33 deletions(-) diff --git a/docs/1-general-configuration.md b/docs/1-general-configuration.md index ac4bfb5b24a..31acf52f995 100644 --- a/docs/1-general-configuration.md +++ b/docs/1-general-configuration.md @@ -37,11 +37,7 @@ Every page has what's called the site title on the left side of the menu bar. If you want, you can customize it. ```ruby -config.site_title = "My Admin Site" -config.site_title_link = "/" -config.site_title_image = "site_image.png" -config.site_title_image = "https://www.google.com/images/logos/google_logo_41.png" -config.site_title_image = ->(context) { context.current_user.company.logo_url } +config.site_title = "My Admin Site" ``` ## Internationalization (I18n) @@ -193,31 +189,3 @@ Remember to indicate where to place the comments and form with: ```ruby active_admin_comments_for(resource) ``` - -## Utility Navigation - -The "utility navigation" shown at the top right normally shows the current user -and a link to log out. However, the utility navigation is just like any other -menu in the system; you can provide your own menu to be rendered in its place. - -```ruby -ActiveAdmin.setup do |config| - config.namespace :admin do |admin| - admin.build_menu :utility_navigation do |menu| - menu.add label: "ActiveAdmin.info", url: "https://www.activeadmin.info", - html_options: { target: "_blank" } - admin.add_current_user_to_menu menu - admin.add_logout_button_to_menu menu - end - end -end -``` - -## Footer Customization - -By default, Active Admin displays a "Powered by ActiveAdmin" message on every -page. You can override this message and show domain-specific messaging: - -```ruby -config.footer = "MyApp Revision v1.3" -``` From 28322afdccd2f712e483ab071640e3186deaa0de Mon Sep 17 00:00:00 2001 From: Javier Julio Date: Fri, 29 Dec 2023 19:33:01 -0500 Subject: [PATCH 09/12] Update table_for docs for responsive support --- docs/12-arbre-components.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/12-arbre-components.md b/docs/12-arbre-components.md index feb287419b7..3baabc157bb 100644 --- a/docs/12-arbre-components.md +++ b/docs/12-arbre-components.md @@ -71,6 +71,19 @@ The `column` method can take a title as its first argument and data (`:your_method`) as its second (or first if no title provided). Column also takes a block. +### Responsive Support + +For a mobile friendly `table_for`, you'll need to wrap it with a `div` and apply +horizontal overflow to enable horizontal scrolling. + +```ruby +div class: "overflow-x-auto" do + table_for payments do + # ... + end +end +``` + ### Internationalization To customize the internationalization for the component, specify a resource to From 2907428db95d9c4b95e33cb350936dd56b04bb50 Mon Sep 17 00:00:00 2001 From: Javier Julio Date: Fri, 29 Dec 2023 18:17:48 -0500 Subject: [PATCH 10/12] Remove jQuery UI/datepicker docs These no longer apply as jQuery UI has been removed and we now use the native HTML date input. Formtastic fields already accept input html options so data attributes can be set on existing date input field. --- docs/5-forms.md | 24 ++---------------------- 1 file changed, 2 insertions(+), 22 deletions(-) diff --git a/docs/5-forms.md b/docs/5-forms.md index 19f3ddb0325..0dda8c3c51d 100644 --- a/docs/5-forms.md +++ b/docs/5-forms.md @@ -152,28 +152,8 @@ in the list. ## Datepicker -ActiveAdmin offers the `datepicker` input, which uses the [jQuery UI -datepicker](https://jqueryui.com/datepicker/). The datepicker input accepts any -of the options available to the standard jQueryUI Datepicker. For example: - -```ruby -form do |f| - f.input :starts_at, as: :datepicker, - datepicker_options: { - min_date: "2013-10-8", - max_date: "+3D" - } - - f.input :ends_at, as: :datepicker, - datepicker_options: { - min_date: 3.days.ago.to_date, - max_date: "+1W +5D" - } -end -``` - -Datepicker also accepts the `:label` option as a string or proc to display. -If it's a proc, it will be called each time the datepicker is rendered. +ActiveAdmin will use the native HTML date input as a default datepicker. You can +supply your own datepicker alternative and use JS to override any date input. ## Displaying Errors From 5e8d5e4f2d88cf99b73bd448cf099fd0330c7d30 Mon Sep 17 00:00:00 2001 From: Javier Julio Date: Thu, 10 Oct 2024 00:54:17 -0400 Subject: [PATCH 11/12] Add partial to batch actions forms docs --- docs/9-batch-actions.md | 77 ++++++++++++++++++++--------------------- 1 file changed, 38 insertions(+), 39 deletions(-) diff --git a/docs/9-batch-actions.md b/docs/9-batch-actions.md index 3331ad8008e..03bef522c9c 100644 --- a/docs/9-batch-actions.md +++ b/docs/9-batch-actions.md @@ -120,53 +120,52 @@ end ### Batch Action forms If you want to capture input from the user as they perform a batch action, -Active Admin has just the thing for you: +you can supply a partial (e.g. modal form) that will be included +automatically in the index page output. -```ruby -batch_action :flag, form: { - type: %w[Offensive Spam Other], - reason: :text, - notes: :textarea, - hide: :checkbox, - date: :datepicker -} do |ids, inputs| - # inputs is a hash of all the form fields you requested - redirect_to collection_path, notice: [ids, inputs].to_s -end -``` - -If you pass a nested array, it will behave just like Formtastic would, with the first -element being the text displayed and the second element being the value. +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. ```ruby -batch_action :doit, form: {user: [['Jake',2], ['Mary',3]]} do |ids, inputs| - User.find(inputs[:user]) - # ... +ActiveAdmin.register Post do + 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| + # inputs is a hash of all the form fields you requested + redirect_to collection_path, notice: [ids, inputs].to_s + end end ``` -When you have dynamic form inputs you can pass a proc instead: - -```ruby -batch_action :doit, form: -> { {user: User.pluck(:name, :id)} } do |ids, inputs| - User.find(inputs[:user]) - # ... -end +::: tip +You can use any modal JS library as long as it can be triggered to open +using data attributes. Flowbite usage is optional. +::: + +Assuming a partial named `_mark_published_batch_action.html.erb` exists in +the `app/views/admin/posts` directory, the contents will be included automatically +in the index page output for you. + +Now update the partial with the modal form HTML where the root `id` attribute must +match the data attributes supplied in the earlier `batch_action` example. The +form **must** have an empty `data-batch-action-form` attribute. + +```erb + ``` -Under the covers this is powered by the JS `ActiveAdmin.ModalDialog` which you -can use yourself: - -```coffee -if $('body.admin_users').length - $('a[data-prompt]').click -> - ActiveAdmin.ModalDialog $(@).data('prompt'), comment: 'textarea', - (inputs)=> - $.post "/admin/users/#{$(@).data 'id'}/change_state", - comment: inputs.comment, state: $(@).data('state'), - success: -> - window.location.reload() -``` +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. ### Translation From a0f9932afd08f091941b3a63b9572bf0713c0113 Mon Sep 17 00:00:00 2001 From: Javier Julio Date: Fri, 5 Jan 2024 14:23:31 -0500 Subject: [PATCH 12/12] Update general docs/install --- docs/0-installation.md | 29 ++--------------------------- 1 file changed, 2 insertions(+), 27 deletions(-) diff --git a/docs/0-installation.md b/docs/0-installation.md index c12951ef43e..6260531fda1 100644 --- a/docs/0-installation.md +++ b/docs/0-installation.md @@ -44,9 +44,9 @@ After installing the gem, you need to run the generator. Here are your options: The generator adds these core files, among others: * `app/admin/dashboard.rb` -* `app/assets/javascripts/active_admin.js` -* `app/assets/stylesheets/active_admin.scss` +* `app/assets/stylesheets/active_admin.css` * `config/initializers/active_admin.rb` +* `tailwind-active_admin.config.js` Now, migrate and seed your database before starting the server: @@ -114,30 +114,6 @@ Draper::CollectionDecorator.send :delegate, :per_page_kaminari If you're getting the error `wrong number of arguments (6 for 4..5)`, [read #2703]. -## webpacker - -You can **opt-in to using Webpacker for ActiveAdmin assets** as well by updating your configuration to turn on the `use_webpacker` option, either at installation time or manually. - -* at active_admin installation: - - ```sh - rails g active_admin:install --use_webpacker - ``` - -* manually: - - ```ruby - ActiveAdmin.setup do |config| - config.use_webpacker = true - end - ``` - - And run the generator to get default Active Admin assets: - - ```sh - rails g active_admin:webpacker - ``` - ## vite_rails To use Active Admin with Vite, make sure the `@activeadmin/activeadmin` dependency is added to your `package.json` using e.g. Yarn: @@ -148,7 +124,6 @@ yarn add @activeadmin/activeadmin@^3 Then follow the steps outlined in this discussion comment: https://github.com/activeadmin/activeadmin/discussions/7947#discussioncomment-5867902 - [CHANGELOG]: https://github.com/activeadmin/activeadmin/blob/master/CHANGELOG.md [dashboard.rb]: https://github.com/activeadmin/activeadmin/blob/master/lib/generators/active_admin/install/templates/dashboard.rb [active_admin.rb]: https://github.com/activeadmin/activeadmin/blob/master/lib/generators/active_admin/install/templates/active_admin.rb.erb