administrate 0.4.0 → 0.5.0

data/config/locales/administrate.nl.yml

@@ -6,6 +6,8 @@ nl:
       destroy: Verwijder
       edit: Bewerk
       show: Toon
+      new: Nieuw
+      back: Terug
     controller:
       create:
         success: "%{resource} was succesvol aangemaakt."

data/config/locales/administrate.pl.yml

@@ -6,6 +6,8 @@ pl:
       destroy: Usuń
       edit: Edytuj
       show: Wyświetl
+      new: Nowy
+      back: Plecy
     controller:
       create:
         success: "Zasób %{resource} został pomyślnie utworzony."

data/config/locales/administrate.pt-BR.yml

@@ -7,6 +7,8 @@ pt-BR:
       destroy: Deletar
       edit: Editar
       show: Visualizar
+      new: Criar
+      back: Voltar
     controller:
       create:
         success: "%{resource} foi criado com sucesso."

data/config/locales/administrate.pt.yml

@@ -0,0 +1,26 @@
+# encoding: UTF-8
+---
+pt:
+  administrate:
+    actions:
+      confirm: Tem certeza?
+      destroy: Remover
+      edit: Editar
+      show: Visualizar
+      new: Novo
+      back: Voltar atrás
+    controller:
+      create:
+        success: "%{resource} foi criado com sucesso."
+      destroy:
+        success: "%{resource} foi removido com sucesso."
+      update:
+        success: "%{resource} foi actualizado com sucesso."
+    fields:
+      has_many:
+        more: "Mostrando %{count} de %{total_count}"
+        none: Nenhum
+      polymorphic:
+        not_supported: Relações polimórficas nos formulários não são suportadas.
+      has_one:
+        not_supported: Relações um para muitos nos formulários não são suportadas.

data/config/locales/administrate.ru.yml

@@ -6,6 +6,8 @@ ru:
       destroy: Удалить
       edit: Редактировать
       show: Показать
+      new: Новый
+      back: Вернуться назад
     controller:
       create:
         success: "%{resource} был успешно создан."

data/config/locales/administrate.sv.yml

@@ -6,6 +6,8 @@ sv:
       destroy: Ta bort
       edit: Ändra
       show: Visa
+      new: Ny
+      back: Tillbaka
     controller:
       create:
         success: "%{resource} har skapats."

data/config/locales/administrate.uk.yml

@@ -6,6 +6,8 @@ uk:
       destroy: Видалити
       edit: Редагувати
       show: Показати
+      new: новий
+      back: назад
     controller:
       create:
         success: "%{resource} було успішно створено."

data/config/locales/administrate.vi.yml

@@ -6,6 +6,8 @@ vi:
       destroy: Xóa
       edit: Sửa
       show: Xem
+      new: Mới
+      back: Trở lại
     controller:
       create:
         success: "%{resource} đã được tạo thành công."

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

@@ -6,6 +6,8 @@ zh-CN:
       destroy: 删除
       edit: 编辑
       show: 查看
+      new: 新建
+      back: 返回
     controller:
       create:
         success: "%{resource} 创建成功."

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

@@ -6,6 +6,8 @@ zh-TW:
       destroy: 刪除
       edit: 編輯
       show: 檢視
+      new: 删除
+      back: 背部
     controller:
       create:
         success: "已成功新增 %{resource}。"

data/docs/adding_custom_field_types.md

@@ -0,0 +1,79 @@
+# Adding Custom Field Types
+
+If your application deals with a nonstandard data type,
+you can create an `Administrate::Field` object to help display
+the custom data type across the dashboard.
+
+`Administrate::Field` objects consist of two parts:
+a Ruby class and associated views.
+
+For example, let's create a `Field` that displays [Gravatars] based on an email.
+
+[Gravatars]: https://gravatar.com/
+
+First, we'll run a generator to set us up with the files we need:
+
+```bash
+rails generate administrate:field gravatar
+```
+
+This creates a few files:
+
+- `app/fields/gravatar_field.rb`
+- `app/views/fields/gravatar_field/_show.html.erb`
+- `app/views/fields/gravatar_field/_index.html.erb`
+- `app/views/fields/gravatar_field/_form.html.erb`
+
+We can edit the `app/fields/gravatar_field.rb` to add some custom logic:
+
+```ruby
+# app/fields/gravatar_field.rb
+require 'digest/md5'
+
+class GravatarField < Administrate::Field::Base
+  def gravatar_url
+    email_address = data.downcase
+    hash = Digest::MD5.hexdigest(email_address)
+    "http://www.gravatar.com/avatar/#{hash}"
+  end
+end
+```
+
+Next, we can customize the partials to display data how we'd like.
+Open up the `app/views/fields/gravatar_field/_show.html.erb` partial.
+By default, it looks like:
+
+```eruby
+<%= field.to_s %>
+```
+
+Since we want to display an image, we can change it to:
+
+```eruby
+<%= image_tag field.gravatar_url %>
+```
+
+You can customize the other generated partials in the same way
+for custom behavior on the index and form pages.
+
+## Using your custom field
+
+We need to tell Administrate which attributes we'd like to be displayed as a
+gravatar image.
+
+Open up a dashboard file, and add the gravatar field into the `ATTRIBUTE_TYPES`
+hash. It should look something like:
+
+```ruby
+class UserDashboard < Administrate::BaseDashboard
+  ATTRIBUTE_TYPES = {
+    created_at: Field::DateTime,
+    updated_at: Field::DateTime,
+    name: Field::String,
+    email: GravatarField,    # Update this email to use your new field class
+    # ...
+  }
+end
+```
+
+[Customizing Attribute Partials]: /customizing_attribute_partials

data/docs/authentication.md

@@ -0,0 +1,60 @@
+# Authenticating admin users
+
+Authentication is left for you to implement after you install Administrate into
+your app. You can easily plugin your existing authentication system.
+
+The base `Admin::ApplicationController` has a `TODO` to be completed:
+
+```ruby
+class Admin::ApplicationController < Administrate::ApplicationController
+  before_action :authenticate_admin
+
+  def authenticate_admin
+    # TODO Add authentication logic here.
+  end
+end
+```
+
+## Using Clearance
+
+[Clearance][clearance] provides Rails authentication with email & password.
+
+```ruby
+class Admin::ApplicationController < Administrate::ApplicationController
+  include Clearance::Controller
+  before_action :require_login
+end
+```
+
+## Using Devise
+
+[Devise][devise] is an authentication solution for Rails with Warden. Include
+the authentication method for your model as a `before_action`:
+
+```ruby
+class Admin::ApplicationController < Administrate::ApplicationController
+  before_action :authenticate_user!
+end
+```
+
+## Using HTTP Basic authentication
+
+Rails includes the [`http_basic_authenticate_with`][rails-http-basic-auth]
+method which can be added to your base admin controller:
+
+```ruby
+class Admin::ApplicationController < Administrate::ApplicationController
+  http_basic_authenticate_with(
+    name: ENV.fetch("ADMIN_NAME"),
+    password: ENV.fetch("ADMIN_PASSWORD")
+  )
+end
+```
+
+With this approach consider using [dotenv][dotenv] to setup your environment and
+avoid committing secrets in your repository.
+
+[clearance]: https://github.com/thoughtbot/clearance
+[devise]: https://github.com/plataformatec/devise
+[rails-http-basic-auth]: http://api.rubyonrails.org/classes/ActionController/HttpAuthentication/Basic.html
+[dotenv]: https://github.com/bkeepers/dotenv

data/docs/customizing_attribute_partials.md

@@ -0,0 +1,34 @@
+# Customizing attribute partials
+
+Occasionally you might want to change how specific types of attributes appear
+across all dashboards.
+For example, you might want all `Number` values to round to three decimal points.
+
+To get started, run the appropriate rails generator:
+
+```bash
+rails generate administrate:views:field number
+```
+
+This will generate three files:
+
+- `app/view/fields/number/_form.html.erb`
+- `app/view/fields/number/_index.html.erb`
+- `app/view/fields/number/_show.html.erb`
+
+The generated templates will have documentation
+describing which variables are in scope.
+The rendering part of the partial will look like:
+
+```eruby
+<%= field.data %>
+```
+
+Changing numbers to display to three decimal places might look like this:
+
+```eruby
+<%= field.data.round(3) %>
+```
+
+If you only want to change how an attribute appears
+on a single page (e.g. `index`), you may delete the unnecessary templates.

data/docs/customizing_controller_actions.md

@@ -0,0 +1,32 @@
+# Customizing controller actions
+
+When you install Administrate into your app,
+we generate empty controllers for each of your resources.
+If you want to create more complex application behavior for a dashboard,
+simply overwrite controller actions.
+
+The generated controller will look something like:
+
+```ruby
+# app/controllers/admin/foos_controller.rb
+
+class Admin::FoosController < Admin::ApplicationController
+
+  # Overwrite any of the RESTful controller actions to implement custom behavior
+  # For example, you may want to send an email after a foo is updated.
+  #
+  # def update
+  #   foo = Foo.find(params[:id])
+  #   foo.update(params[:foo])
+  #   send_foo_updated_email
+  # end
+
+  # Override this method to specify custom lookup behavior.
+  # This will be used to set the resource for the `show`, `edit`, and `update`
+  # actions.
+  #
+  # def find_resource(param)
+  #   Foo.find_by!(slug: param)
+  # end
+end
+```

data/docs/customizing_dashboards.md

@@ -0,0 +1,143 @@
+# Customizing Dashboards
+
+In order to customize which attributes get displayed for each resource,
+edit the dashboard file generated by the installation generator.
+
+By default, the file will look something like this:
+
+```ruby
+require "administrate/dashboard/base"
+
+class CustomerDashboard < Administrate::Dashboard::Base
+  ATTRIBUTE_TYPES = {
+    id: Field::Integer,
+    name: Field::String,
+    email: Field::String,
+    created_at: Field::DateTime,
+    updated_at: Field::DateTime,
+    orders: Field::HasMany,
+  }
+
+  COLLECTION_ATTRIBUTES = [
+    :id,
+    :name,
+    :email,
+    :created_at,
+    :updated_at,
+    :orders,
+  ]
+
+  SHOW_PAGE_ATTRIBUTES = [
+    :id,
+    :name,
+    :email,
+    :created_at,
+    :updated_at,
+    :orders,
+  ]
+
+  FORM_ATTRIBUTES = [
+    :name,
+    :email,
+    :orders,
+  ]
+end
+```
+
+To change which attributes appear on each of the `index`, `show`, and `edit`
+pages, add or remove attributes to each constant array.
+
+Finally, the `ATTRIBUTE_TYPES` method defines how each attribute is displayed
+throughout the dashboard. There are a number of `Field` classes that you can
+specify, including:
+
+- `Field::BelongsTo`
+- `Field::Boolean`
+- `Field::DateTime`
+- `Field::Email`
+- `Field::HasMany`
+- `Field::HasOne`
+- `Field::Number`
+- `Field::Polymorphic`
+- `Field::Select`
+- `Field::String`
+
+## Customizing Fields
+
+### Setting Options
+
+Each of the `Field` types take a different set of options,
+which are specified through the `.with_options` class method:
+
+**Field::HasMany**
+
+`:limit` - Set the number of resources to display in the show view. Default is
+`5`.
+
+**Field::Number**
+
+`:decimals` - Set the number of decimals to display. Defaults to `0`.
+
+`:prefix` - Prefixes the number with a string. Defaults to `""`.
+
+For example, you might use the following to display U.S. currency:
+
+```ruby
+  unit_price: Field::Number.with_options(
+    prefix: "$",
+    decimals: 2,
+  )
+```
+
+**Field::Select**
+
+`:collection` - Specify the array or range to select from.  Defaults to `[]`.
+
+`:searchable` - Specify if the attribute should be considered when searching.
+Default is `true`.
+
+**Field::String**
+
+`:searchable` - Specify if the attribute should be considered when searching.
+Default is `true`.
+
+`:truncate` - Set the number of characters to display in the index view.
+Defaults to `50`.
+
+**Field::Text**
+
+`:searchable` - Specify if the attribute should be considered when searching.
+Default is `false`.
+
+`:truncate` - Set the number of characters to display in the index view.
+Defaults to `50`.
+
+### Defining Labels
+
+To change the user-facing label for an attribute,
+define a custom I18n translation:
+
+```yaml
+en:
+  helpers:
+    label:
+      customer:
+        name: Full Name
+```
+
+
+To change the labels used for resources in dashboard collections.
+Assume you have a users dashboard and you want to change "User #1" to "Testy
+McTesterson", the user's name.
+
+Add this method to the dashboard for Users.
+Use whatever attribute or method you like.
+Example for *user*:
+
+````ruby
+def display_resource(user)
+  user.name
+end
+````
+
+[define your own]: /adding_custom_field_types