administrate 0.10.0 → 0.15.0

data/docs/getting_started.md

@@ -1,16 +1,18 @@
-# Getting Started
+---
+title: Getting Started
+---
 
 Administrate is released as a Ruby gem, and can be installed on Rails
-applications version 4.2 or greater.
+applications version 5.0 or greater. We support Ruby 2.4 and up.
 
-Add the following to your Gemfile:
+First, add the following to your Gemfile:
 
 ```ruby
 # Gemfile
 gem "administrate"
 ```
 
-Re-bundle, then run the installer:
+Re-bundle with `bundle install`, then run the installer:
 
 ```bash
 $ rails generate administrate:install
@@ -35,13 +37,13 @@ You will also want to add a `root` route to show a dashboard when you go to `/ad
 Rails.application.routes.draw do
   namespace :admin do
     # Add dashboard for your models here
-    resources :customers,
+    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.
@@ -54,6 +56,28 @@ 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
@@ -63,7 +87,7 @@ the dashboard generator. A dashboard and controller will be created.
 $ rails generate administrate:dashboard Foo
 ```
 
-Add a route for the new dashboard.
+Then add a route for the new dashboard.
 
 ```ruby
 # config/routes.rb
@@ -73,10 +97,19 @@ namespace :admin do
 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 
+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:
@@ -89,7 +122,7 @@ Example:
     the_new_attribute: Field::String,
     # ...
   }.freeze
-  
+
   SHOW_PAGE_ATTRIBUTES = [
     # ...
     :the_new_attribute,
@@ -101,7 +134,7 @@ Example:
     :the_new_attribute,
     # ...
   ].freeze
-  
+
   COLLECTION_ATTRIBUTES = [
     # ...
     :the_new_attribute, # if you want it on the index, also.
@@ -109,49 +142,9 @@ Example:
   ].freeze
 ```
 
-It's recommended that you make this change at the same time as you add the 
+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.
-
-## 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 the 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
-```
+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/docs/guides.md

@@ -0,0 +1,5 @@
+---
+title: Guides
+---
+
+* [Hiding Dashboards from the Sidebar](./guides/hiding_dashboards_from_sidebar)

data/docs/guides/hiding_dashboards_from_sidebar.md

@@ -0,0 +1,19 @@
+---
+title: Hiding Dashboards from the Sidebar
+---
+
+Resources can be removed form 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/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
+```

data/lib/administrate.rb

@@ -1,4 +1,23 @@
 require "administrate/engine"
 
 module Administrate
+  def self.warn_of_missing_resource_class
+    ActiveSupport::Deprecation.warn(
+      "Calling Field::Base.permitted_attribute without the option " +
+      ":resource_class is deprecated. If you are seeing this " +
+      "message, you are probably using a custom field type that" +
+      "does this. Please make sure to update it to a version that " +
+      "does not use a deprecated API",
+    )
+  end
+
+  def self.warn_of_deprecated_option(name)
+    ActiveSupport::Deprecation.warn(
+      "The option :#{name} is deprecated. " +
+      "Administrate should detect it automatically. " +
+      "Please file an issue at " +
+      "https://github.com/thoughtbot/administrate/issues " +
+      "if you think otherwise.",
+    )
+  end
 end

data/lib/administrate/base_dashboard.rb

@@ -1,6 +1,7 @@
 require "administrate/field/belongs_to"
 require "administrate/field/boolean"
 require "administrate/field/date_time"
+require "administrate/field/date"
 require "administrate/field/email"
 require "administrate/field/has_many"
 require "administrate/field/has_one"
@@ -10,12 +11,25 @@ require "administrate/field/select"
 require "administrate/field/string"
 require "administrate/field/text"
 require "administrate/field/time"
+require "administrate/field/url"
 require "administrate/field/password"
 
 module Administrate
   class BaseDashboard
     include Administrate
 
+    DASHBOARD_SUFFIX = "Dashboard".freeze
+
+    class << self
+      def model
+        to_s.chomp(DASHBOARD_SUFFIX).classify.constantize
+      end
+
+      def resource_name(opts)
+        model.model_name.human(opts)
+      end
+    end
+
     def attribute_types
       self.class::ATTRIBUTE_TYPES
     end
@@ -32,13 +46,20 @@ module Administrate
       end
     end
 
+    def all_attributes
+      attribute_types.keys
+    end
+
     def form_attributes
       self.class::FORM_ATTRIBUTES
     end
 
     def permitted_attributes
       form_attributes.map do |attr|
-        attribute_types[attr].permitted_attribute(attr)
+        attribute_types[attr].permitted_attribute(
+          attr,
+          resource_class: self.class.model,
+        )
       end.uniq
     end
 
@@ -54,15 +75,12 @@ module Administrate
       "#{resource.class} ##{resource.id}"
     end
 
-    def association_includes
-      association_classes = [Field::HasMany, Field::HasOne, Field::BelongsTo]
-
-      collection_attributes.map do |key|
-        field = self.class::ATTRIBUTE_TYPES[key]
+    def collection_includes
+      attribute_includes(collection_attributes)
+    end
 
-        next key if association_classes.include?(field)
-        key if association_classes.include?(field.try :deferred_class)
-      end.compact
+    def item_includes
+      attribute_includes(show_page_attributes)
     end
 
     private
@@ -70,5 +88,13 @@ module Administrate
     def attribute_not_found_message(attr)
       "Attribute #{attr} could not be found in #{self.class}::ATTRIBUTE_TYPES"
     end
+
+    def attribute_includes(attributes)
+      attributes.map do |key|
+        field = attribute_type_for(key)
+
+        key if field.associative?
+      end.compact
+    end
   end
 end

data/lib/administrate/custom_dashboard.rb

@@ -0,0 +1,15 @@
+module Administrate
+  class CustomDashboard
+    include Administrate
+
+    class << self
+      def resource_name(_opts)
+        named_resource.pluralize.titleize
+      end
+
+      def resource(resource_name)
+        define_singleton_method(:named_resource) { resource_name }
+      end
+    end
+  end
+end

data/lib/administrate/engine.rb

@@ -2,7 +2,7 @@ require "datetime_picker_rails"
 require "jquery-rails"
 require "kaminari"
 require "momentjs-rails"
-require "sass-rails"
+require "sassc-rails"
 require "selectize-rails"
 require "sprockets/railtie"
 
@@ -22,6 +22,13 @@ module Administrate
     @@javascripts = []
     @@stylesheets = []
 
+    initializer "administrate.assets.precompile" do |app|
+      app.config.assets.precompile += [
+        "administrate/application.js",
+        "administrate/application.css",
+      ]
+    end
+
     def self.add_javascript(script)
       @@javascripts << script
     end

data/lib/administrate/field/associative.rb

@@ -3,30 +3,74 @@ require_relative "base"
 module Administrate
   module Field
     class Associative < Base
+      def self.foreign_key_for(resource_class, attr)
+        reflection(resource_class, attr).foreign_key
+      end
+
+      def self.associated_class(resource_class, attr)
+        reflection(resource_class, attr).klass
+      end
+
+      def self.associated_class_name(resource_class, attr)
+        reflection(resource_class, attr).class_name
+      end
+
+      def self.reflection(resource_class, attr)
+        resource_class.reflect_on_association(attr)
+      end
+
       def display_associated_resource
         associated_dashboard.display_resource(data)
       end
 
       def associated_class
-        associated_class_name.constantize
+        if option_given?(:class_name)
+          associated_class_name.constantize
+        else
+          self.class.associated_class(resource.class, attribute)
+        end
       end
 
-      protected
+      private
 
       def associated_dashboard
         "#{associated_class_name}Dashboard".constantize.new
       end
 
       def associated_class_name
-        options.fetch(:class_name, attribute.to_s.singularize.camelcase)
+        if option_given?(:class_name)
+          deprecated_option(:class_name)
+        else
+          self.class.associated_class_name(
+            resource.class,
+            attribute,
+          )
+        end
       end
 
       def primary_key
-        options.fetch(:primary_key, :id)
+        if option_given?(:primary_key)
+          deprecated_option(:primary_key)
+        else
+          :id
+        end
       end
 
       def foreign_key
-        options.fetch(:foreign_key, :"#{attribute}_id")
+        if option_given?(:foreign_key)
+          deprecated_option(:foreign_key)
+        else
+          self.class.foreign_key_for(resource.class, attribute)
+        end
+      end
+
+      def option_given?(name)
+        options.key?(name)
+      end
+
+      def deprecated_option(name)
+        Administrate.warn_of_deprecated_option(name)
+        options.fetch(name)
       end
     end
   end