semantic-administrate 0.1.0

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

@@ -0,0 +1,26 @@
+---
+zh-TW:
+  administrate:
+    actions:
+      confirm: 確定？
+      destroy: 刪除
+      edit: 編輯
+      show: 檢視
+      new: 新增
+      back: 返回
+    controller:
+      create:
+        success: "已成功新增 %{resource}。"
+      destroy:
+        success: "已成功刪除 %{resource}。"
+      update:
+        success: "已成功更新 %{resource}。"
+    fields:
+      has_many:
+        more: 顯示 %{total_count} 筆中的 %{count} 筆資料
+        none: 無
+      has_one:
+        not_supported: 表單尚未支援 HasOne 關聯。
+    search:
+      clear: 清除搜索
+      label: 搜索 %{resource}

data/config/routes.rb

@@ -0,0 +1,2 @@
+Administrate::Engine.routes.draw do
+end

data/config/unicorn.rb

@@ -0,0 +1,30 @@
+# https://devcenter.heroku.com/articles/rails-unicorn
+
+worker_processes (ENV["UNICORN_WORKERS"] || 3).to_i
+timeout (ENV["UNICORN_TIMEOUT"] || 15).to_i
+preload_app true
+
+before_fork do |_server, _worker|
+  Signal.trap "TERM" do
+    puts "Unicorn master intercepting TERM, sending myself QUIT instead"
+    Process.kill "QUIT", Process.pid
+  end
+
+  if defined? ActiveRecord::Base
+    ActiveRecord::Base.connection.disconnect!
+  end
+end
+
+after_fork do |_server, _worker|
+  Signal.trap "TERM" do
+    puts "Unicorn worker intercepting TERM, waiting for master to send QUIT"
+  end
+
+  if defined? ActiveRecord::Base
+    config = ActiveRecord::Base.configurations[Rails.env] ||
+      Rails.application.config.database_configuration[Rails.env]
+    config["reaping_frequency"] = (ENV["DB_REAPING_FREQUENCY"] || 10).to_i
+    config["pool"] = (ENV["DB_POOL"] || 2).to_i
+    ActiveRecord::Base.establish_connection(config)
+  end
+end

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,61 @@
+# Authenticating admin users
+
+Authentication is left for you to implement after you install Administrate into
+your app. It's expected that you can 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,53 @@
+# Customizing attribute partials
+
+Occasionally you might want to change how specific types of attributes appear
+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:
+
+```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`
+
+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:
+
+```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,42 @@
+# 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,
+you can 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
+  #
+  # Override this if you have certain roles that require a subset
+  # this will be used to set the records shown on the `index` action.
+  # def scoped_resource
+  #  if current_user.super_admin?
+  #    resource_class
+  #  else
+  #    resource_class.with_less_stuff
+  #  end
+  # end
+end
+```

data/docs/customizing_dashboards.md

@@ -0,0 +1,202 @@
+# 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`
+- `Field::Text`
+
+## 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::BelongsTo**
+
+`:order` - order of the dropdown menu, can be ordered by more than one column `"name, email DESC"`
+
+**Field::HasMany**
+
+`:limit` - Set the number of resources to display in the show view. Default is
+`5`.
+
+`:sort_by` - What to sort the association by in the show view.
+
+`: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::BelongsTo**
+
+`: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`.
+
+`:prefix` - Prefixes the number with a string. Defaults to `""`.
+
+`:suffix` - Suffixes 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,
+  )
+```
+
+Or, to display a distance in kilometers:
+
+```ruby
+  unit_price: Field::Number.with_options(
+    suffix: " km",
+    decimals: 2,
+  )
+```
+
+**Field::Polymorphic**
+
+`:classes` - Specify a list of classes whose objects will be used to populate select boxes for editing this polymorphic field.
+Default is `[]`.
+
+**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
+
+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`.