mini-max-mod 0.0.1

data/administrate-1.0.0/docs/customizing_page_views.md

@@ -0,0 +1,143 @@
+---
+title: Customizing page views
+---
+
+You can provide replacements for any of Administrate's templates.
+This way you can change the appearance of any page or element of
+the interface.
+
+In general, you can override any of the views under Administrate's
+[/app/views][1].
+For example, say that you want to customize the template used for flash
+messages. You can provide your own as
+`app/views/admin/application/_flashes.html.erb`, and it will replace
+Administrate's own.
+
+Figuring out which views are available and where can be repetitive. You can
+spare yourself some effort by using the built-in view generators.
+
+[1]: https://github.com/thoughtbot/administrate/tree/master/app/views
+
+## Customizing for all resources
+
+In order to change the appearance of views for all resource types,
+call the generators with no arguments.
+
+```bash
+rails generate administrate:views:index
+ # -> app/views/admin/application/index.html.erb
+ # -> app/views/admin/application/_collection.html.erb
+
+rails generate administrate:views:show
+ # -> app/views/admin/application/show.html.erb
+
+rails generate administrate:views:edit
+ # -> app/views/admin/application/edit.html.erb
+ # -> app/views/admin/application/_form.html.erb
+
+rails generate administrate:views:new
+ # -> app/views/admin/application/new.html.erb
+ # -> app/views/admin/application/_form.html.erb
+
+rails generate administrate:views
+ # -> all of the above
+```
+
+The generators copy over the default views that Administrate uses,
+so you have a good starting point for customizations.
+Feel free to change up the file type,
+add extra sections to the page,
+or blow it all away for your own custom look.
+
+## Customizing for a specific resource
+
+In order to change a dashboard page for a single type of resource,
+pass in the resource name to the view generators.
+
+```bash
+rails generate administrate:views:index User
+ # -> app/views/admin/users/index.html.erb
+ # -> app/views/admin/users/_collection.html.erb
+
+rails generate administrate:views:show User
+ # -> app/views/admin/users/show.html.erb
+
+rails generate administrate:views:edit User
+ # -> app/views/admin/users/edit.html.erb
+ # -> app/views/admin/users/_form.html.erb
+
+rails generate administrate:views:new User
+ # -> app/views/admin/users/new.html.erb
+ # -> app/views/admin/users/_form.html.erb
+
+rails generate administrate:views User
+ # -> all of the above
+```
+
+Any changes to these template files
+will *only* affect pages that display customers,
+and will leave the show pages for other resources unchanged.
+
+## Customizing layouts
+
+Many developers need to customize the layouts of their admin dashboard.
+It's as easy as passing in the "layout" keyword to the view generators.
+
+```bash
+rails generate administrate:views:layout
+ # -> app/views/layouts/admin/application.html.erb
+ # -> app/views/admin/application/_navigation.html.erb
+ # -> app/views/admin/application/_javascript.html.erb
+ # -> app/views/admin/application/_flashes.html.erb
+
+ rails generate administrate:views:navigation
+ # It only generates the sidebar partial
+ # -> app/views/admin/application/_navigation.html.erb
+```
+
+## Customizing for a specific layout
+
+You can use several hook points to add elements to specific layouts or specific pages:
+
+* header_middle
+* header_last
+* before_main
+* main
+* after_main
+
+For example, you can add a button in the middle of the header as follows:
+
+```eruby
+<%# app/views/admin/customers/_index_header.html.erb %>
+
+<% content_for(:header_middle) do %>
+  <div>
+    You are logged in as <em><%= pundit_user.name %></em>.
+    <%= link_to("Become the Admin", become_admin_customer_path("admin")) unless pundit_user.admin? %>
+  </div>
+<% end %>
+
+<%= render template: 'administrate/application/_index_header', locals: local_assigns %>
+```
+
+## Adding custom CSS and JS
+
+You can add custom CSS and JS to Administrate. Put the files in the
+appropriate folders (typically under `assets`) and point Administrate to them
+using the following API, preferably in an initializer. For example, if your
+files are called `admin.css` and `admin.js`:
+
+```
+/// config/initializers/administrate.rb
+Administrate::Engine.add_stylesheet("admin")
+Administrate::Engine.add_javascript("admin")
+```
+
+Then make sure to list them in your manifest file (Rails will helpfully remind
+you of this step if you miss it):
+
+```
+/// app/assets/config/manifest.js
+//= link admin.css
+//= link admin.js
+```

data/administrate-1.0.0/docs/extending_administrate.md

@@ -0,0 +1,27 @@
+---
+title: Extending Administrate
+---
+
+Apart from the configuration described in these pages, it is possible to
+extend Administrate's capabilities with the use of plugins. There are a
+number of plugins available, many of which can be found at [RubyGems.org].
+These are some popular examples:
+
+1. [ActiveStorage support](https://github.com/Dreamersoul/administrate-field-active_storage)
+2. [Enum field](https://github.com/Valiot/administrate-field-enum)
+3. [Nested has-many forms](https://github.com/nickcharlton/administrate-field-nested_has_many)
+4. [Belongs-to with Ajax search](https://github.com/fishbrain/administrate-field-belongs_to_search)
+5. [JSONb field plugin for Administrate](https://github.com/codica2/administrate-field-jsonb/)
+
+See many more at https://rubygems.org/gems/administrate/reverse_dependencies.
+
+Please note that these plugins are written by third parties. We do not
+have any control over them, and we cannot give any assurances as to how
+well they perform their advertised functions.
+
+You can write your own plugins too! We don't document this specifically,
+but you can have a look at the existing plugins for some directions.
+In general, Administrate tries to abide by Rails's conventions, so that
+hopefully should help!
+
+[RubyGems.org]: https://rubygems.org

data/administrate-1.0.0/docs/getting_started.md

@@ -0,0 +1,150 @@
+---
+title: Getting Started
+---
+
+Administrate is released as a Ruby gem, and can be installed on Rails
+applications version 6.0 or greater. We support Ruby 3.0 and up.
+
+First, add the following to your Gemfile:
+
+```ruby
+# Gemfile
+gem "administrate"
+```
+
+Re-bundle with `bundle install`, then run the installer:
+
+```bash
+$ rails generate administrate:install
+```
+
+The installer adds some new routes to your `config/routes.rb`,
+and creates a controller at `app/controllers/admin/application_controller.rb`
+
+In addition, the generator creates a `Dashboard` and a `Controller` for each of
+your ActiveRecord resources:
+
+- `app/controllers/admin/foos_controller.rb`
+- `app/dashboards/foo_dashboard.rb`
+
+The `Admin::ApplicationController` can be customized to add
+authentication logic, authorization, pagination,
+or other controller-level concerns.
+
+You will also want to add a `root` route to show a dashboard when you go to `/admin`.
+
+```ruby
+Rails.application.routes.draw do
+  namespace :admin do
+    # Add dashboard for your models here
+    resources :customers
+    resources :orders
+
+    root to: "customers#index" # <--- Root route
+  end
+ end
+```
+
+The routes can be customized to show or hide
+different models on the dashboard.
+
+Each `FooDashboard` specifies which attributes should be displayed
+on the admin dashboard for the `Foo` resource.
+
+Each `Admin::FooController` can be overwritten to specify custom behavior.
+
+Once you have Administrate installed,
+visit <http://localhost:3000/admin> to see your new dashboard in action.
+
+### Errors about assets?
+
+If your apps uses Sprockets 4, you'll need to add Administrate's assets to
+your `manifest.js` file. To do this, add these two lines to the file:
+
+```
+//= link administrate/application.css
+//= link administrate/application.js
+```
+
+Otherwise, your app will show you this error:
+
+```
+Asset `administrate/application.css` was not declared to be precompiled in production.
+Declare links to your assets in `app/assets/config/manifest.js`.
+```
+
+For more information on why this is necessary, see Richard Schneeman's article
+["Self Hosted Config: Introducing the Sprockets manifest.js"][]
+
+[schneems]: https://www.schneems.com/2017/11/22/self-hosted-config-introducing-the-sprockets-manifestjs
+
+## Create Additional Dashboards
+
+In order to create additional dashboards, pass in the resource name to
+the dashboard generator. A dashboard and controller will be created.
+
+```bash
+$ rails generate administrate:dashboard Foo
+```
+
+Then add a route for the new dashboard.
+
+```ruby
+# config/routes.rb
+
+namespace :admin do
+  resources :foos
+end
+```
+
+## Using a Custom Namespace
+
+Administrate supports using a namespace other than `Admin`, such as
+`Supervisor`. This will also change the route it's using:
+
+```sh
+rails generate administrate:install --namespace=supervisor
+```
+
+## Keep Dashboards Updated as Model Attributes Change
+
+If you've installed Administrate and generated dashboards and _then_
+subsequently added attributes to your models you'll need to manually add
+these additions (or removals) to your dashboards.
+
+Example:
+
+```ruby
+# app/dashboards/your_model_dashboard.rb
+
+  ATTRIBUTE_TYPES = {
+    # ...
+    the_new_attribute: Field::String,
+    # ...
+  }.freeze
+
+  SHOW_PAGE_ATTRIBUTES = [
+    # ...
+    :the_new_attribute,
+    # ...
+  ].freeze
+
+  FORM_ATTRIBUTES = [
+    # ...
+    :the_new_attribute,
+    # ...
+  ].freeze
+
+  COLLECTION_ATTRIBUTES = [
+    # ...
+    :the_new_attribute, # if you want it on the index, also.
+    # ...
+  ].freeze
+```
+
+It's recommended that you make this change at the same time as you add the
+attribute to the model.
+
+The alternative way to handle this is to re-run `rails g administrate:install`
+and carefully pick through the diffs. This latter method is probably more
+cumbersome.

data/administrate-1.0.0/docs/guides/customising_search.md

@@ -0,0 +1,149 @@
+---
+title: Customising the search
+---
+
+Administrate dashboards provide a search function, but it is quite basic.
+Things like search across complex associations, inside JSON columns, or outside
+the database (eg: an Elasticsearch index) are not possible out of the box.
+
+Fortunately, Administrate is just Rails, so you can use your existing Rails
+knowledge to customize the search feature. Let's look into that.
+
+## In short
+
+Override the `filter_resources` method in your admin controllers in order
+to customize the search.
+
+It has two parameters:
+
+* `resources`: an ActiveRecord relation for the model on whose dashboard the
+               search originated.
+* `search_term:`: a string representing the search query entered by the user.
+
+Return an ActiveRecord relation for the same model as `resources`, matching
+the desired search results.
+
+## In more detail
+
+When you install Administrate in your application, it generates an admin
+controller for each of your ActiveRecord models, as well as a base controller
+that all of these inherit from.
+
+For example, if you have two ActiveRecord models: `Person` and `Address`,
+running `rails generate administrate:install` will get you the following
+files (plus others that are not relevant here):
+
+* `app/controllers/admin/people_controller.rb`
+* `app/controllers/admin/addresses_controller.rb`
+* `app/controllers/admin/application_controller.rb`
+
+By default, searches are handled by the `index` action of the controller that
+the user was visiting when they performed the search. For example, if a user
+is visiting the People dashboard and submits a search, the user is sent to
+the path `/admin/people?search=<search query>`. This is routed to
+`Admin::PeopleController#index`, where the search query can be read as
+`params[:search]`.
+
+By default, these controllers are empty. Administrate's code is implemented
+at `Administrate::ApplicationController`, from which all inherit. This is
+where search is implemented. You can read the code yourself at:
+https://github.com/thoughtbot/administrate/blob/main/app/controllers/administrate/application_controller.rb.
+
+It is in the linked code that you can see what Administrate actually does.
+For example, this is the `index` action at the time of writing these lines:
+
+```ruby
+    def index
+      authorize_resource(resource_class)
+      search_term = params[:search].to_s.strip
+      resources = filter_resources(scoped_resource, search_term: search_term)
+      resources = apply_collection_includes(resources)
+      resources = order.apply(resources)
+      resources = resources.page(params[:_page]).per(records_per_page)
+      page = Administrate::Page::Collection.new(dashboard, order: order)
+
+      render locals: {
+        resources: resources,
+        search_term: search_term,
+        page: page,
+        show_search_bar: show_search_bar?,
+      }
+    end
+```
+
+What the above does is applying a few transforms
+to the variable `resources`, filtering it, applying includes for associations,
+ordering the results, paginating them, and finally handing them over to the
+template in order to be rendered. All this is pretty standard Rails, although
+split into individual steps that can be overriden by developers in order
+to add customizations, and ultimately wrapped in an instance of
+`Administrate::Page::Collection` which will read your dashboard definitions
+and figure out what fields you want displayed.
+
+It is the filtering part where the search is implemented. You will notice the
+`filter_resources` method, which takes a parameter `search_term`. This is what
+this method looks like at the moment:
+
+```ruby
+    def filter_resources(resources, search_term:)
+      Administrate::Search.new(
+        resources,
+        dashboard,
+        search_term,
+      ).run
+    end
+```
+
+The class `Administrate::Search` implements the default search facilities
+within Administrate... but you do not have to worry about it! You can ignore
+it and implement your own search in `filter_resources`. For example, you
+could write your own version in your controller, to override Administrate's
+own. Something like this:
+
+```ruby
+    def filter_resources(resources, search_term:)
+      resources.where(first_name: search_term)
+        .or(People.where(last_name: search_term))
+    end
+```
+
+It can be as complex (or simple) as you want, as long as the return value
+of the method is an ActiveRecord relation.
+
+What if you do not want to search in the DB? For example, say that your records
+are indexed by Elasticsearch or something like that. You can still search
+in your external index and convert the results to an ActiveRecord relation.
+Here's an example:
+
+```ruby
+    def filter_resources(resources, search_term:)
+      # Run the search term through your search facility
+      results = MySuperDuperSearchSystem.search_people(search_term)
+
+      # Collect the ids of the results. This assumes that they will
+      # be the same ones as in the DB.
+      record_ids = results.entries.map(&:id)
+
+      # Use the ids to create an ActiveRecord relation and return it
+      People.where(id: record_ids)
+    end
+```
+
+Note though: the records must still exist in the DB. Administrate does
+require ActiveRecord in order to show tables, and to display, create and edit
+records.
+
+## A working example
+
+The [Administrate demo app](https://administrate-demo.herokuapp.com/admin)
+includes an example of custom search in the "Log Entries" dashboard.
+In this app, each `LogEntry` instance has a polymorphic `belongs_to`
+association to a `:logeable`. Logeables are other models for which logs can be
+created. At the moment these are `Order` and `Customer`.
+
+Administrate's default search is not able to search across polymorphic
+associations, and therefore it is not possible to search logs by the contents
+of their logeables. Fortunately this can be fixed with a custom search. This is
+done by implementing `Admin::LogEntriesController#filter_resources` to override
+the default search. You can see the code at
+https://github.com/thoughtbot/administrate/blob/main/spec/example_app/app/controllers/admin/log_entries_controller.rb

data/administrate-1.0.0/docs/guides/hiding_dashboards_from_sidebar.md

@@ -0,0 +1,21 @@
+---
+title: Hiding Dashboards from the Sidebar
+---
+
+Resources can be removed from the sidebar by removing their `index` action
+from the routes. For example:
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  namespace :admin do
+    resources :line_items, except: :index
+    resources :orders
+    resources :products
+    root to: "customers#index"
+  end
+end
+```
+
+In this case, only Orders and Products will appear in the sidebar, while
+Line Items can still appear as an association.

data/administrate-1.0.0/docs/guides/scoping_has_many_relations.md

@@ -0,0 +1,27 @@
+---
+title: Scoping HasMany Relations
+---
+
+To show a subset of a has_many relationship, create a new [has_many](https://apidock.com/rails/ActiveRecord/Associations/ClassMethods/has_many) relationship in your model (using the `scope` argument) and add it to the model's dashboard.
+
+## Creating a scoped has_many relationship
+
+Models can define subsets of a `has_many` relationship by passing a callable (i.e. proc or lambda) as its second argument.
+
+```ruby
+class Customer < ApplicationRecord
+   has_many :orders
+   has_many :processed_orders, ->{ where(processed: true) }, class_name: "Order"
+```
+
+Since ActiveRecord infers the class name from the first argument, the new `has_many` relation needs to specify the model using the `class_name` option.
+
+## Add new relationship to dashboard
+
+Your new scoped relation can be used in the dashboard just like the original `HasMany`.
+
+```ruby
+ATTRIBUTE_TYPES = {
+  orders: Field::HasMany,
+  processed_orders: Field::HasMany
+```

data/administrate-1.0.0/docs/guides/switching_templates_with_view_variants.md

@@ -0,0 +1,45 @@
+---
+title: Switching templates with view variants
+---
+
+You can switch to different templates using Rails' support for [view
+variants][], which can be used to override the template used inside the
+controller.
+
+By setting the `request.variant` option to any value (in this case, `:admin`)
+at any point in any controller, you can add a new variant to Rails' template
+lookup tree (in this case, `.html+admin.erb`).
+
+For example, to add a button to become the admin to view certain functionality:
+
+```ruby
+class CustomersController < Admin::ApplicationController
+  before_action :with_variant, only: %i[index]
+
+  private
+
+  def with_variant
+    if @current_user.admin?
+      request.variant = :admin
+    end
+  end
+end
+```
+
+```erb
+<!-- app/views/admin/customers/_index_header.html.erb -->
+<p class="identity__banner">
+  You are logged in as <em><%= pundit_user.name %></em>.
+  <%= link_to("Become the Admin", become_admin_customer_path("admin"),
+        class: "identity__become-action")%>
+</p>
+```
+
+```erb
+<!-- app/views/admin/customers/_index_header.html+admin.erb -->
+<p class="identity__banner identity__banner--admin">
+  You are logged in as <em><%= pundit_user.name %></em>.
+</p>
+```
+
+[view variants]: https://guides.rubyonrails.org/layouts_and_rendering.html#the-variants-option

data/administrate-1.0.0/docs/guides.md

@@ -0,0 +1,8 @@
+---
+title: Guides
+---
+
+- [Hiding Dashboards from the Sidebar](./guides/hiding_dashboards_from_sidebar)
+- [Customising the search](./guides/customising_search)
+- [Scoping HasMany Relations](./guides/scoping_has_many_relations.md)
+- [Switching templates with view variants](./guides/switching_templates_with_view_variants.md)

data/administrate-1.0.0/docs/migrating-to-v1.md

@@ -0,0 +1,34 @@
+---
+title: Migrating to v1
+---
+
+In the release of v1.0.0, we [began bundling assets in the gem itself][2397].
+In the future, this should mean that any changes made to assets (coming
+from you or from Administrate updates) should not have an effect on you.
+However, this is quite a big change and so you might find some problems.
+
+As with most upgrades, if you're upgrading between versions with changes to the
+templates, and if you've customised them, you may need to apply recent changes.
+You can see those which changed in the [CHANGELOG][].
+
+This applies to both modified files in `app/views/admin` and `app/views/fields`
+if you have your own Field classes defined. A good way is to use the same 
+command to generate the view as for the earlier version:
+`rails generate administrate:views:ACTION MyModel`
+noting the changes and re-applying the modifications
+
+[2397]: https://github.com/thoughtbot/administrate/pull/2397
+[CHANGELOG]: https://github.com/thoughtbot/administrate/blob/main/CHANGELOG.md
+
+## Reported issues
+
+### Removal of the `sprockets-rails` transitive dependency
+
+[Issue][2514]
+
+Previously, Administrate depended on [`sprockets-rails`][], if you have a
+dependency which requires this, you may now need to add a direct dependency on
+your application.
+
+[2514]: https://github.com/thoughtbot/administrate/issues/2514
+[`sprockets-rails`]: https://rubygems.org/gems/sprockets-rails

data/administrate-1.0.0/docs/rails_api.md

@@ -0,0 +1,45 @@
+---
+title: Rails API
+---
+
+Since Rails 5.0, we've been able to have API only applications. Yet, sometimes
+we still want to have an admin.
+
+To get this working, we recommend updating this config:
+
+```ruby
+# config/application.rb
+config.api_only = false
+```
+
+That means, when your app _boots_, we'll have access to flashes and such. We
+also don't use your `ApplicationController`. Instead, Administrate provides its
+own. Meaning you're free to specify `ActionController::API` as your parent
+controller to make sure no flash, session, or cookie middleware is used by your
+API.
+
+Alternatively, if your application needs to have `config.api_only = true`, we
+recommend you add the following lines to your `config/application.rb`
+
+```ruby
+# Enable Flash, Cookies, MethodOverride for Administrate Gem
+config.middleware.use ActionDispatch::Flash
+config.session_store :cookie_store
+config.middleware.use ActionDispatch::Cookies
+config.middleware.use ActionDispatch::Session::CookieStore, config.session_options
+config.middleware.use ::Rack::MethodOverride
+```
+
+You must also ensure that all the required controller actions are available
+and accessible as routes since generators in API-only applications only
+generate some of the required actions. Here is an example:
+
+```ruby
+# routes.rb
+namespace :admin do
+  resources :name, only: %i(index show new create edit update destroy)
+end
+
+# names_controller.rb
+# Ensure each of those methods are defined
+```