administrate 0.8.1 → 0.9.0

data/config/locales/administrate.zh-TW.yml

@@ -5,8 +5,9 @@ zh-TW:
       confirm: 確定？
       destroy: 刪除
       edit: 編輯
-      show: 檢視
-      new: 新增
+      edit_resource: 編輯 %{name}
+      show_resource: 檢視 %{name}
+      new_resource: 新增 %{name}
       back: 返回
     controller:
       create:
@@ -19,10 +20,9 @@ zh-TW:
       has_many:
         more: 顯示 %{total_count} 筆中的 %{count} 筆資料
         none: 無
-      polymorphic:
-        not_supported: 表單尚未支援 Polymorphic 關聯。
-      has_one:
-        not_supported: 表單尚未支援 HasOne 關聯。
+    form:
+      error: error
+      errors: "%{pluralized_errors} prohibited this %{resource_name} from being saved:"
     search:
       clear: 清除搜索
       label: 搜索 %{resource}

data/docs/authorization.md

@@ -0,0 +1,69 @@
+# Authorization
+
+The default configuration of Administrate is "authenticate-only" - once a
+user is authenticated, that user has access to every action of every object.
+
+You can add more fine-grained authorization by overriding methods in the
+controller.
+
+## Using Pundit
+
+If your app already uses [Pundit](https://github.com/elabs/pundit) for
+authorization, you just need to add one line to your
+`Admin::ApplicationController`:
+
+```ruby
+include Administrate::Punditize
+```
+
+This will use all the policies from your main app to determine if the
+current user is able to view a given record or perform a given action.
+
+### Further limiting scope
+
+You may want to limit the scope for a given user beyond what they
+technically have access to see in the main app. For example, a user may
+have all public records in their scope, but you want to only show *their*
+records in the admin interface to reduce confusion.
+
+In this case, you can add an additional `resolve_admin` to your policy's
+scope and Administrate will use this instead of the `resolve` method.
+
+For example:
+
+```ruby
+class PostPolicy < ApplicationPolicy
+  class Scope < Scope
+    def resolve
+      scope.all
+    end
+    
+    def resolve_admin
+      scope.where(owner: user)
+    end
+  end
+end
+```
+
+## Authorization without Pundit
+
+If you use a different authorization library, or you want to roll your own,
+you just need to override a few methods in your controllers or
+`Admin::ApplicationController`. For example:
+
+```ruby
+# Limit the scope of the given resource
+def scoped_resource
+  super.where(user: current_user)
+end
+
+# Raise an exception if the user is not permitted to access this resource
+def authorize_resource(resource)
+  raise "Erg!" unless show_action?(params[:action], resource)
+end
+
+# Hide links to actions if the user is not allowed to do them      
+def show_action?(action, resource)
+  current_user.can? action, resource
+end
+```

data/docs/customizing_attribute_partials.md

@@ -1,7 +1,20 @@
 # Customizing attribute partials
 
 Occasionally you might want to change how specific types of attributes appear
-across all dashboards.
+across all dashboards. You can customize the following built in field types:
+
+- `belongs_to`
+- `boolean`
+- `date_time`
+- `email`
+- `has_many`
+- `has_one`
+- `number`
+- `polymporphic`
+- `select`
+- `string`
+- `text`
+
 For example, you might want all `Number` values to round to three decimal points.
 
 To get started, run the appropriate rails generator:
@@ -16,6 +29,12 @@ This will generate three files:
 - `app/view/fields/number/_index.html.erb`
 - `app/view/fields/number/_show.html.erb`
 
+You can generate the partials for all field types by passing `all` to the generator.
+
+```bash
+rails generate administrate:views:field all
+```
+
 The generated templates will have documentation
 describing which variables are in scope.
 The rendering part of the partial will look like:

data/docs/customizing_dashboards.md

@@ -70,6 +70,16 @@ specify, including:
 Each of the `Field` types take a different set of options,
 which are specified through the `.with_options` class method:
 
+**Field::BelongsTo**
+
+`:order` - Specifies the order of the dropdown menu, can be ordered by more
+than one column. e.g.: `"name, email DESC"`.
+
+`:primary_key` - Specifies object's primary_key. Defaults to `:id`.
+
+`:foreign_key` - Specifies the name of the foreign key directly.
+Defaults to `:#{attribute}_id`.
+
 **Field::HasMany**
 
 `:limit` - Set the number of resources to display in the show view. Default is
@@ -79,6 +89,10 @@ which are specified through the `.with_options` class method:
 
 `:direction` - What direction the sort should be in, `:asc` (default) or `:desc`.
 
+`:primary_key` - Specifies object's primary_key. Defaults to `:id`.
+
+`:foreign_key` - Specifies the name of the foreign key directly. Defaults to `:#{attribute}_id`
+
 **Field::Number**
 
 `:decimals` - Set the number of decimals to display. Defaults to `0`.
@@ -105,6 +119,22 @@ Or, to display a distance in kilometers:
   )
 ```
 
+**Field::Polymorphic**
+
+`:classes` - Specify a list of classes whose objects will be used to populate select boxes for editing this polymorphic field.
+Default is `[]`.
+
+`:order` - What to sort the association by in the form select.
+Default is `nil`.
+
+**Field::DateTime**
+
+`:format` - Specify what format, using `strftime` you would like `DateTime`
+objects to display as.
+
+`:timezone` - Specify which timezone `Date` and `DateTime` objects are based
+in.
+
 **Field::Select**
 
 `:collection` - Specify the array or range to select from.  Defaults to `[]`.
@@ -157,3 +187,27 @@ end
 ````
 
 [define your own]: /adding_custom_field_types
+
+To change the dashboard name in sidebar menu, sub-header and search string use default ActiveRecord i18n translations for models:
+
+```yaml
+en:
+  activerecord:
+    models:
+      customer:
+        one: Happy Customer
+        others: Happy Customers
+```
+
+## Customizing Actions
+
+To enable or disable certain actions you could override `valid_action?` method in your dashboard controller like this:
+
+```ruby
+# disable 'edit' and 'destroy' links
+def valid_action?(name, resource = resource_class)
+  %w[edit destroy].exclude?(name.to_s) && super
+end
+```
+
+Action is one of `new`, `edit`, `show`, `destroy`.

data/docs/getting_started.md

@@ -29,6 +29,20 @@ 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.
 
@@ -59,10 +73,54 @@ namespace :admin do
 end
 ```
 
+## 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.
+
 ## 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, please update this config:
+we still want to have an admin. 
+
+To get this working, we recommend updating this config:
 
 ```ruby
 # config/application.rb
@@ -74,3 +132,26 @@ 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
+```

data/lib/administrate/field/associative.rb

@@ -24,6 +24,10 @@ module Administrate
       def primary_key
         options.fetch(:primary_key, :id)
       end
+
+      def foreign_key
+        options.fetch(:foreign_key, :"#{attribute}_id")
+      end
     end
   end
 end

data/lib/administrate/field/base.rb

@@ -24,7 +24,7 @@ module Administrate
         @options = options
       end
 
-      def self.permitted_attribute(attr)
+      def self.permitted_attribute(attr, _options = nil)
         attr
       end
 

data/lib/administrate/field/belongs_to.rb

@@ -3,12 +3,12 @@ require_relative "associative"
 module Administrate
   module Field
     class BelongsTo < Associative
-      def self.permitted_attribute(attr)
+      def self.permitted_attribute(attr, _options = nil)
         :"#{attr}_id"
       end
 
       def permitted_attribute
-        self.class.permitted_attribute(attribute)
+        foreign_key
       end
 
       def associated_resource_options
@@ -24,7 +24,8 @@ module Administrate
       private
 
       def candidate_resources
-        associated_class.all
+        order = options.delete(:order)
+        order ? associated_class.order(order) : associated_class.all
       end
 
       def display_candidate_resource(resource)

data/lib/administrate/field/date_time.rb

@@ -4,11 +4,18 @@ module Administrate
   module Field
     class DateTime < Base
       def date
-        I18n.localize(data.to_date, format: format)
+        I18n.localize(
+          data.in_time_zone(timezone).to_date,
+          format: format,
+        )
       end
 
       def datetime
-        I18n.localize(data, format: format, default: data)
+        I18n.localize(
+          data.in_time_zone(timezone),
+          format: format,
+          default: data,
+        )
       end
 
       private
@@ -16,6 +23,10 @@ module Administrate
       def format
         options.fetch(:format, :default)
       end
+
+      def timezone
+        options.fetch(:timezone, "UTC")
+      end
     end
   end
 end

data/lib/administrate/field/deferred.rb

@@ -25,11 +25,12 @@ module Administrate
         options.fetch(:searchable, deferred_class.searchable?)
       end
 
-      delegate(
-        :html_class,
-        :permitted_attribute,
-        to: :deferred_class,
-      )
+      def permitted_attribute(attr, _options = nil)
+        options.fetch(:foreign_key,
+          deferred_class.permitted_attribute(attr, options))
+      end
+
+      delegate :html_class, to: :deferred_class
     end
   end
 end

data/lib/administrate/field/has_many.rb

@@ -7,8 +7,8 @@ module Administrate
     class HasMany < Associative
       DEFAULT_LIMIT = 5
 
-      def self.permitted_attribute(attribute)
-        { "#{attribute.to_s.singularize}_ids".to_sym => [] }
+      def self.permitted_attribute(attr, _options = nil)
+        { "#{attr.to_s.singularize}_ids".to_sym => [] }
       end
 
       def associated_collection

data/lib/administrate/field/has_one.rb

@@ -3,25 +3,33 @@ require_relative "associative"
 module Administrate
   module Field
     class HasOne < Associative
-      def initialize(attribute, data, page, options = {})
-        resolver = Administrate::ResourceResolver.new("admin/#{attribute}")
-        @nested_form = Administrate::Page::Form.new(
+      def nested_form
+        @nested_form ||= Administrate::Page::Form.new(
           resolver.dashboard_class.new,
           data || resolver.resource_class.new,
         )
-
-        super
       end
 
-      def self.permitted_attribute(attr)
+      def self.permitted_attribute(attr, options = nil)
+        associated_class_name =
+          if options
+            options.fetch(:class_name, attr.to_s.singularize.camelcase)
+          else
+            attr
+          end
         related_dashboard_attributes =
-          Administrate::ResourceResolver.new("admin/#{attr}").
+          Administrate::ResourceResolver.new("admin/#{associated_class_name}").
             dashboard_class.new.permitted_attributes + [:id]
 
         { "#{attr}_attributes": related_dashboard_attributes }
       end
 
-      attr_reader :nested_form
+      private
+
+      def resolver
+        @resolver ||=
+          Administrate::ResourceResolver.new("admin/#{associated_class_name}")
+      end
     end
   end
 end