semantic-administrate 0.1.0

data/docs/customizing_page_views.md

@@ -0,0 +1,78 @@
+# Customizing page views
+
+In order to change the appearance of any page,
+you can write custom Rails views.
+
+## Customizing for all resources
+
+The easiest way to get started is by using the built-in generators.
+In order to change the appearance of views for all resource types,
+call the generators with no arguments.
+
+```bash
+rails generate administrate:views:index
+ # -> app/views/admin/application/index.html.erb
+ # -> app/views/admin/application/_collection.html.erb
+
+rails generate administrate:views:show
+ # -> app/views/admin/application/show.html.erb
+
+rails generate administrate:views:edit
+ # -> app/views/admin/application/edit.html.erb
+ # -> app/views/admin/application/_form.html.erb
+
+rails generate administrate:views:new
+ # -> app/views/admin/application/new.html.erb
+ # -> app/views/admin/application/_form.html.erb
+
+rails generate administrate:views
+ # -> all of the above
+```
+
+The generators copy over the default views that Administrate uses,
+so you have a good starting point for customizations.
+Feel free to change up the file type,
+add extra sections to the page,
+or blow it all away for your own custom look.
+
+## Customizing for a specific resource
+
+In order to change a dashboard page for a single type of resource,
+pass in the resource name to the view generators.
+
+```bash
+rails generate administrate:views:index User
+ # -> app/views/admin/users/index.html.erb
+ # -> app/views/admin/users/_collection.html.erb
+
+rails generate administrate:views:show User
+ # -> app/views/admin/users/show.html.erb
+
+rails generate administrate:views:edit User
+ # -> app/views/admin/users/edit.html.erb
+ # -> app/views/admin/users/_form.html.erb
+
+rails generate administrate:views:new User
+ # -> app/views/admin/users/new.html.erb
+ # -> app/views/admin/users/_form.html.erb
+
+rails generate administrate:views User
+ # -> all of the above
+```
+
+Any changes to these template files
+will *only* affect pages that display customers,
+and will leave the show pages for other resources unchanged.
+
+## Customizing layouts
+
+Many developers need to customize the layouts of their admin dashboard.
+It's so easy that pass in the "layout" key word to the view generators.
+
+```bash
+rails generate administrate:views:layout
+ # -> app/views/layouts/admin/application.html.erb
+ # -> app/views/admin/application/_navigation.html.erb
+ # -> app/views/admin/application/_javascript.html.erb
+ # -> app/views/admin/application/_flashes.html.erb
+```

data/docs/getting_started.md

@@ -0,0 +1,115 @@
+# Getting Started
+
+Administrate is released as a Ruby gem, and can be installed on Rails
+applications version 4.2 or greater.
+
+Add the following to your Gemfile:
+
+```ruby
+# Gemfile
+gem "administrate"
+```
+
+Re-bundle, then run the installer:
+
+```bash
+$ rails generate administrate:install
+```
+
+The installer adds some new routes to your `config/routes.rb`,
+and creates a controller at `app/controllers/admin/application_controller.rb`
+
+In addition, the generator creates a `Dashboard` and a `Controller` for each of
+your ActiveRecord resources:
+
+- `app/controllers/admin/foos_controller.rb`
+- `app/dashboards/foo_dashboard.rb`
+
+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.
+
+Each `FooDashboard` specifies which attributes should be displayed
+on the admin dashboard for the `Foo` resource.
+
+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.
+
+## Create Additional Dashboards
+
+In order to create additional dashboards, pass in the resource name to
+the dashboard generator. A dashboard and controller will be created.
+
+```bash
+$ rails generate administrate:dashboard Foo
+```
+
+Add a route for the new dashboard.
+
+```ruby
+# config/routes.rb
+
+namespace :admin do
+  resources :foos
+end
+```
+
+## 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
+```

data/lib/administrate.rb

@@ -0,0 +1,4 @@
+require "administrate/engine"
+
+module Administrate
+end

data/lib/administrate/base_dashboard.rb

@@ -0,0 +1,72 @@
+require "administrate/field/belongs_to"
+require "administrate/field/boolean"
+require "administrate/field/date_time"
+require "administrate/field/email"
+require "administrate/field/has_many"
+require "administrate/field/has_one"
+require "administrate/field/number"
+require "administrate/field/polymorphic"
+require "administrate/field/select"
+require "administrate/field/string"
+require "administrate/field/text"
+
+module Administrate
+  class BaseDashboard
+    include Administrate
+
+    def attribute_types
+      self.class::ATTRIBUTE_TYPES
+    end
+
+    def attribute_type_for(attribute_name)
+      attribute_types.fetch(attribute_name) do
+        fail attribute_not_found_message(attribute_name)
+      end
+    end
+
+    def attribute_types_for(attribute_names)
+      attribute_names.each_with_object({}) do |name, attributes|
+        attributes[name] = attribute_type_for(name)
+      end
+    end
+
+    def form_attributes
+      self.class::FORM_ATTRIBUTES
+    end
+
+    def permitted_attributes
+      form_attributes.map do |attr|
+        attribute_types[attr].permitted_attribute(attr)
+      end.uniq
+    end
+
+    def show_page_attributes
+      self.class::SHOW_PAGE_ATTRIBUTES
+    end
+
+    def collection_attributes
+      self.class::COLLECTION_ATTRIBUTES
+    end
+
+    def display_resource(resource)
+      "#{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]
+
+        next key if association_classes.include?(field)
+        key if association_classes.include?(field.try :deferred_class)
+      end.compact
+    end
+
+    private
+
+    def attribute_not_found_message(attr)
+      "Attribute #{attr} could not be found in #{self.class}::ATTRIBUTE_TYPES"
+    end
+  end
+end

data/lib/administrate/engine.rb

@@ -0,0 +1,44 @@
+require "datetime_picker_rails"
+require "jquery-rails"
+require "kaminari"
+require "momentjs-rails"
+require "sass-rails"
+require "selectize-rails"
+require "sprockets/railtie"
+
+require "administrate/page/form"
+require "administrate/page/show"
+require "administrate/page/collection"
+require "administrate/order"
+require "administrate/resource_resolver"
+require "administrate/search"
+require "administrate/namespace"
+require "administrate/namespace/resource"
+
+module Administrate
+  class Engine < ::Rails::Engine
+    isolate_namespace Administrate
+
+    @@javascripts = []
+    @@stylesheets = []
+
+    def self.add_javascript(script)
+      @@javascripts << script
+    end
+
+    def self.add_stylesheet(stylesheet)
+      @@stylesheets << stylesheet
+    end
+
+    def self.stylesheets
+      @@stylesheets
+    end
+
+    def self.javascripts
+      @@javascripts
+    end
+
+    add_javascript "administrate/application"
+    add_stylesheet "administrate/application"
+  end
+end

data/lib/administrate/field/associative.rb

@@ -0,0 +1,33 @@
+require_relative "base"
+
+module Administrate
+  module Field
+    class Associative < Base
+      def display_associated_resource
+        associated_dashboard.display_resource(data)
+      end
+
+      protected
+
+      def associated_dashboard
+        "#{associated_class_name}Dashboard".constantize.new
+      end
+
+      def associated_class
+        associated_class_name.constantize
+      end
+
+      def associated_class_name
+        options.fetch(:class_name, attribute.to_s.singularize.camelcase)
+      end
+
+      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

@@ -0,0 +1,54 @@
+require_relative "deferred"
+require "active_support/core_ext/string/inflections"
+
+module Administrate
+  module Field
+    class Base
+      def self.with_options(options = {})
+        Deferred.new(self, options)
+      end
+
+      def self.html_class
+        field_type.dasherize
+      end
+
+      def self.searchable?
+        false
+      end
+
+      def initialize(attribute, data, page, options = {})
+        @attribute = attribute
+        @data = data
+        @page = page
+        @resource = options.delete(:resource)
+        @options = options
+      end
+
+      def self.permitted_attribute(attr)
+        attr
+      end
+
+      def html_class
+        self.class.html_class
+      end
+
+      def name
+        attribute.to_s
+      end
+
+      def to_partial_path
+        "/fields/#{self.class.field_type}/#{page}"
+      end
+
+      attr_reader :attribute, :data, :page, :resource
+
+      protected
+
+      attr_reader :options
+
+      def self.field_type
+        to_s.split("::").last.underscore
+      end
+    end
+  end
+end

data/lib/administrate/field/belongs_to.rb

@@ -0,0 +1,36 @@
+require_relative "associative"
+
+module Administrate
+  module Field
+    class BelongsTo < Associative
+      def self.permitted_attribute(attr)
+        :"#{attr}_id"
+      end
+
+      def permitted_attribute
+        foreign_key
+      end
+
+      def associated_resource_options
+        [nil] + candidate_resources.map do |resource|
+          [display_candidate_resource(resource), resource.send(primary_key)]
+        end
+      end
+
+      def selected_option
+        data && data.send(primary_key)
+      end
+
+      private
+
+      def candidate_resources
+        order = options.delete(:order)
+        order ? associated_class.order(order) : associated_class.all
+      end
+
+      def display_candidate_resource(resource)
+        associated_dashboard.display_resource(resource)
+      end
+    end
+  end
+end