viniBaxterDesk 0.13.1

data/docs/adding_custom_field_types.md

@@ -0,0 +1,81 @@
+---
+title: 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,63 @@
+---
+title: 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/authorization.md

@@ -0,0 +1,71 @@
+---
+title: 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/contributing.md

@@ -0,0 +1 @@
+../CONTRIBUTING.md

data/docs/customizing_attribute_partials.md

@@ -0,0 +1,56 @@
+---
+title: 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`
+- `date`
+- `email`
+- `has_many`
+- `has_one`
+- `number`
+- `polymorphic`
+- `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,58 @@
+---
+title: 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
+```
+
+## 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/customizing_dashboards.md

@@ -0,0 +1,303 @@
+---
+title: 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::Number,
+    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::Date`
+- `Field::Email`
+- `Field::HasMany`
+- `Field::HasOne`
+- `Field::Number`
+- `Field::Polymorphic`
+- `Field::Select`
+- `Field::String`
+- `Field::Text`
+- `Field::Password`
+
+## 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` - 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`.
+
+`:scope` - Specifies a custom scope inside a callable. Useful for preloading.
+Example: `.with_options(scope: -> { MyModel.includes(:rel).limit(5) })`
+
+`:class_name` - Specifies the name of the associated class.
+Defaults to `:#{attribute}.to_s.singularize.camelcase`.
+
+`:searchable` - Specify if the attribute should be considered when searching.
+Default is `false`.
+
+`searchable_field` - Specify which column to use on the search, only applies
+if `searchable` is `true`
+
+For example:
+
+```ruby
+  country: Field::BelongsTo.with_options(
+    searchable: true,
+    searchable_field: 'name',
+  )
+```
+
+with this, you will be able to search through the column `name` from the
+association `belongs_to :country`, from your model.
+
+**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`
+
+`:class_name` - Specifies the name of the associated class.
+Defaults to `:#{attribute}.to_s.singularize.camelcase`.
+
+**Field::HasOne**
+
+`:class_name` - Specifies the name of the associated class.
+Defaults to `:#{attribute}.to_s.singularize.camelcase`.
+
+`:searchable` - Specify if the attribute should be considered when searching.
+Default is `false`.
+
+`searchable_field` - Specify which column to use on the search, only applies if
+`searchable` is `true`
+
+For example:
+
+```ruby
+  cities: Field::HasMany.with_options(
+    searchable: true,
+    searchable_field: 'name',
+  )
+```
+
+with this, you will be able to search through the column `name` from the
+association `has_many :cities`, from your model.
+
+**Field::Number**
+
+`:searchable` - Specify if the attribute should be considered when searching.
+Note that currently number fields are searched like text, which may yield
+more results than expected. Default is `false`.
+
+`: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 `[]`.
+
+`: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::Date**
+
+`:format` - Specify what format, using `strftime` you would like `Date`
+objects to display as.
+
+**Field::Select**
+
+`:collection` - Specify the options shown on the select field. It accept either
+an array or an object responding to `:call`. 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`.
+
+**Field::Password**
+
+`:searchable` - Specify if the attribute should be considered when searching.
+Default is `false`.
+
+`:truncate` - Set the number of characters to display in the views.
+Defaults to `50`.
+
+`:character` - Set the replace character.
+Defaults to `•`.
+
+### 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
+        other: Happy Customers
+```
+
+## Collection Filters
+
+Resources can be filtered with pre-set filters. For example if we added:
+
+```ruby
+COLLECTION_FILTERS = {
+  inactive: ->(resources) { resources.where("login_at < ?", 1.week.ago) }
+}
+```
+
+…to a dashboard, we can query the resources of that dashboard with:
+
+```ruby
+bob inactive:
+```
+
+…to find users named "bob" who hasn't logged in the last week.
+
+If you already had the `inactive` scope you could define the filter like so to
+take advantage of existing ActiveRecord scopes (and other class methods on the
+resource class).
+
+```ruby
+COLLECTION_FILTERS = {
+  inactive: ->(resources) { resources.inactive }
+}
+```