crud_components 0.2.1 → 0.3.0

data/lib/crud_components/admin.rb

@@ -0,0 +1,92 @@
+require_relative 'admin/configuration'
+require_relative 'admin/dependents'
+require_relative 'admin/entry'
+require_relative 'admin/gate'
+require_relative 'admin/registry'
+require_relative 'admin/view_helpers'
+
+module CrudComponents
+  # The optional, mountable admin UI:
+  #
+  #   mount CrudComponents::Admin::Engine => '/admin'
+  #
+  # See docs/admin.md.
+  module Admin
+    class Error < CrudComponents::Error; end
+
+    # Raised when the admin has no way to tell who may in: `auth_with :cancan`
+    # and nothing that answers `can?`.
+    class UnauthorizedError < Error; end
+
+    # Raised when the ability denies the action behind the request. Rendered as
+    # 403 by the engine's controllers.
+    class ForbiddenError < Error; end
+
+    class << self
+      def config
+        @config ||= Configuration.new
+      end
+
+      def configure
+        yield config
+        registry.reload!
+        config
+      end
+
+      def registry
+        @registry ||= Registry.new(config)
+      end
+
+      # Drops both the configuration and the resolved registry.
+      def reset!
+        @config = nil
+        @registry = nil
+        @mount_path = nil
+      end
+
+      # The admin layout's own stylesheet, read once from the packaged file.
+      def bundled_css
+        @bundled_css ||= File.read(
+          File.expand_path('../../app/assets/stylesheets/crud_components_admin.css', __dir__)
+        )
+      end
+
+      # Where the host mounted the engine, or nil when it did not.
+      def mount_path
+        return @mount_path if @mount_path
+        return nil unless defined?(Engine) && defined?(Rails) && Rails.application
+
+        route = Rails.application.routes.routes.find do |candidate|
+          candidate.app.respond_to?(:app) && candidate.app.app == Engine
+        end
+        path = route&.path&.spec.to_s
+        @mount_path = path == '/' ? '' : path.presence
+      end
+
+      # The admin's path for a record (or a model class, for its index), or nil
+      # when the admin isn't mounted, the model isn't registered, or the action
+      # is not enabled for it.
+      def path_for(subject, action = :show)
+        model = subject.is_a?(Class) ? subject : subject.class
+        entry = registry[model]
+        return nil unless entry&.allows?(action) && mount_path
+
+        helper, args = helper_for(entry, action, subject)
+        return nil unless Engine.routes.url_helpers.respond_to?(helper)
+
+        Engine.routes.url_helpers.public_send(helper, *args, script_name: mount_path)
+      end
+
+      private
+
+      def helper_for(entry, action, subject)
+        case action.to_sym
+        when :index then ["#{entry.route_key}_path", []]
+        when :new   then ["new_#{entry.singular_route_key}_path", []]
+        when :edit  then ["edit_#{entry.singular_route_key}_path", [subject]]
+        else ["#{entry.singular_route_key}_path", [subject]]
+        end
+      end
+    end
+  end
+end

data/lib/crud_components/builder.rb

@@ -18,7 +18,8 @@ module CrudComponents
   class Builder
     attr_reader :model, :declarations, :actions, :fieldsets,
                 :label_decl, :identify_by_decl, :search_decl,
-                :label_preload_decl, :preload_decl, :icon_decl
+                :label_preload_decl, :preload_decl, :icon_decl, :admin_decl,
+                :app_path_decl
 
     # @param model [Class] the ActiveRecord model being described.
     # @yield the `crud_structure` block, evaluated against this Builder.
@@ -151,8 +152,62 @@ module CrudComponents
       @fieldsets[name] = Fieldset.new(name, fields, actions: actions, filters: filters)
     end
 
+    # The host application's own page for a record, when it is not the
+    # conventional route (`main_app.book_path(book)`). Runs in the view
+    # context; return nil to suppress the link for a record.
+    #   app_path { |book| main_app.publisher_book_path(book.publisher, book) }
+    # @yield [record] the record to link to.
+    # @return [void]
+    def app_path(&block)
+      raise DefinitionError, "#{model}: app_path requires a block" unless block
+      raise DefinitionError, "#{model}: app_path declared twice" if defined?(@app_path_decl) && @app_path_decl
+
+      @app_path_decl = block
+    end
+
+    # How this model appears in the mounted admin UI (inert without it).
+    # @param enabled [Boolean] `false` keeps the model out of the admin entirely.
+    # @param options [Hash] `actions:` (a subset of
+    #   `%i[index show new create edit update destroy]`), `group:`, `label:`,
+    #   `fieldset:`, `scope:` (a callable narrowing the base relation).
+    # @return [void]
+    def admin(enabled = true, **options)
+      raise DefinitionError, "#{model}: admin declared twice" if defined?(@admin_decl) && !@admin_decl.nil?
+
+      unless [true, false].include?(enabled)
+        raise DefinitionError, "#{model}: admin takes true or false, got #{enabled.inspect}"
+      end
+
+      if enabled == false && options.any?
+        raise DefinitionError, "#{model}: `admin false` takes no options — #{options.keys.map(&:inspect).join(', ')} " \
+                               'would never apply'
+      end
+
+      validate_admin_options!(options)
+      @admin_decl = enabled ? options : false
+    end
+
     private
 
+    ADMIN_OPTIONS = %i[actions group label fieldset scope].freeze
+
+    def validate_admin_options!(options)
+      unknown = options.keys - ADMIN_OPTIONS
+      unless unknown.empty?
+        raise DefinitionError, "#{model}: admin got unknown option(s) #{unknown.map(&:inspect).join(', ')} — " \
+                               "known: #{ADMIN_OPTIONS.map(&:inspect).join(', ')}"
+      end
+
+      actions = options[:actions]
+      return if actions.nil?
+
+      bad = Array(actions).map(&:to_sym) - Admin::Entry::ALL_ACTIONS
+      return if bad.empty?
+
+      raise DefinitionError, "#{model}: admin actions #{bad.map(&:inspect).join(', ')} are not RESTful actions — " \
+                             "known: #{Admin::Entry::ALL_ACTIONS.map(&:inspect).join(', ')}"
+    end
+
     # Normalize a preload value to an array of includes-specs, leaving a nested
     # hash (`{ publisher: :books }`) intact (Array() would split it).
     def preload_list(value)

data/lib/crud_components/helpers.rb

@@ -40,15 +40,22 @@ module CrudComponents
     #   it (from a persisted preference, or from the param via
     #   {CrudComponents.selected_columns}). A forged/stale name can only hide or
     #   reorder, never reveal a column the `if:` gate forbids.
+    # @param extra_actions [Array<CrudComponents::Action>, nil] row actions to append
+    #   beyond the model's own — for a button that belongs to this surface rather
+    #   than to the model. Subject to the same permission and route resolution.
+    # @param except_actions [Array<Symbol>, nil] action names this render drops,
+    #   whatever the model declares (e.g. replacing `:destroy` with a button of
+    #   your own). Applies to row, collection and selection actions.
     # @return [ActiveSupport::SafeBuffer] the rendered HTML.
     def crud_collection(records, fieldset: nil, layout: :table, query: :auto, param_prefix: nil,
                         actions: true, search_bar: true, group_by: nil, extra_columns: nil,
-                        picker: false, picked_columns: :auto)
+                        picker: false, picked_columns: :auto, extra_actions: nil, except_actions: nil)
       presenter = Presenters::Collection.new(view: self, records: records, fieldset: fieldset,
                                              query: query, layout: layout, param_prefix: param_prefix,
                                              actions: actions, search_bar: search_bar, group_by: group_by,
                                              extra_columns: extra_columns,
-                                             picker: picker, picked_columns: picked_columns)
+                                             picker: picker, picked_columns: picked_columns,
+                                             extra_actions: extra_actions, except_actions: except_actions)
       render "crud_components/layouts/#{presenter.layout}", collection: presenter
     end
 
@@ -71,12 +78,17 @@ module CrudComponents
     # @param extra_columns [Array<CrudComponents::DynamicColumn>, nil] user-defined
     #   columns whose data lives outside the model's table, shown as extra rows
     #   (same as {#crud_collection}'s `extra_columns:`, for a detail view).
+    # @param extra_actions [Array<CrudComponents::Action>, nil] actions to append
+    #   beyond the model's own (same as {#crud_collection}'s `extra_actions:`).
+    # @param except_actions [Array<Symbol>, nil] action names this render drops
+    #   (same as {#crud_collection}'s `except_actions:`).
     # @return [ActiveSupport::SafeBuffer] the rendered HTML.
     def crud_record(record, fieldset: nil, actions: true, layout: :record, picked_columns: :auto,
-                    param_prefix: nil, extra_columns: nil)
+                    param_prefix: nil, extra_columns: nil, extra_actions: nil, except_actions: nil)
       presenter = Presenters::Record.new(view: self, record: record, fieldset: fieldset, actions: actions,
                                          picked_columns: picked_columns, param_prefix: param_prefix,
-                                         extra_columns: extra_columns)
+                                         extra_columns: extra_columns, extra_actions: extra_actions,
+                                         except_actions: except_actions)
       render "crud_components/#{layout}", record_presenter: presenter
     end
 
@@ -178,6 +190,25 @@ module CrudComponents
 
     # ── utilities (used by the gem's partials; useful in apps too) ─────────
 
+    # The host application's own page for a record — its `app_path` block, else
+    # the conventional route resolved against `main_app`. nil when there is
+    # none, so guard the link rather than assuming it resolves.
+    # @param record [ActiveRecord::Base]
+    # @return [String, nil]
+    def crud_app_path(record)
+      RouteResolver.app_path(self, record)
+    end
+
+    # The mounted admin's page for a record (or for a model class, its index).
+    # nil when the admin isn't mounted, the model isn't registered, or the
+    # action isn't enabled for it.
+    # @param subject [ActiveRecord::Base, Class]
+    # @param action [Symbol] `:show` (default), `:index`, `:edit` or `:new`.
+    # @return [String, nil]
+    def crud_admin_path(subject, action = :show)
+      Admin.path_for(subject, action)
+    end
+
     # The display label for a record — its declared `label`, else a humanized guess.
     # @param record [ActiveRecord::Base]
     # @return [String]

data/lib/crud_components/presenters/collection.rb

@@ -16,7 +16,8 @@ module CrudComponents
 
       def initialize(view:, records:, fieldset: nil, query: :auto, layout: :table,
                      param_prefix: nil, actions: true, search_bar: true, group_by: nil,
-                     extra_columns: nil, picker: false, picked_columns: :auto)
+                     extra_columns: nil, picker: false, picked_columns: :auto, extra_actions: nil,
+                     except_actions: nil)
         super(view: view)
         unless records.respond_to?(:klass)
           raise ArgumentError,
@@ -31,6 +32,8 @@ module CrudComponents
         @layout = layout
         @param_prefix = param_prefix
         @actions_enabled = actions
+        @extra_actions = Array(extra_actions)
+        @except_actions = Array(except_actions).map(&:to_sym)
         @search_bar_enabled = search_bar
         # Two orthogonal column-picker knobs (see ColumnSelection): the gear is on
         # iff `picker`; the selection comes from the param (`:auto`) or verbatim
@@ -385,7 +388,7 @@ module CrudComponents
         return nil unless @actions_enabled
 
         @collection_actions ||= Actions.new(view: view, subject: model, structure: structure,
-                                            actions: structure.fieldset_actions(fieldset, on: :collection),
+                                            actions: keep(structure.fieldset_actions(fieldset, on: :collection)),
                                             owner: owner)
       end
 
@@ -398,7 +401,8 @@ module CrudComponents
         return nil unless @actions_enabled
 
         @selection_actions ||= Actions.new(view: view, subject: model, structure: structure,
-                                           actions: structure.fieldset_actions(fieldset, on: :selection),
+                                           actions: keep(structure.fieldset_actions(fieldset, on: :selection)) +
+                                                    @extra_actions.select { |action| action.on == :selection },
                                            owner: owner)
       end
 
@@ -489,7 +493,15 @@ module CrudComponents
       end
 
       def row_action_definitions
-        @row_action_definitions ||= structure.fieldset_actions(fieldset, on: :row)
+        @row_action_definitions ||= keep(structure.fieldset_actions(fieldset, on: :row)) +
+                                    @extra_actions.select { |action| action.on == :row }
+      end
+
+      # Actions this render drops, whatever the model declares.
+      def keep(actions)
+        return actions if @except_actions.empty?
+
+        actions.reject { |action| @except_actions.include?(action.name) }
       end
 
       def pn(key)

data/lib/crud_components/presenters/record.rb

@@ -7,13 +7,15 @@ module CrudComponents
       attr_reader :record, :model, :structure, :fieldset, :param_prefix
 
       def initialize(view:, record:, fieldset: nil, actions: true, picked_columns: :auto,
-                     param_prefix: nil, extra_columns: nil)
+                     param_prefix: nil, extra_columns: nil, extra_actions: nil, except_actions: nil)
         super(view: view)
         @record = record
         @model = record.class
         @structure = Structure.for(@model)
         @fieldset = @structure.fieldset(fieldset || :show)
         @actions_enabled = actions
+        @extra_actions = Array(extra_actions).select { |action| action.on == :row }
+        @except_actions = Array(except_actions).map(&:to_sym)
         @param_prefix = param_prefix
         # Dynamic columns work on a detail view too — user-defined properties
         # whose data lives outside the model's table, shown as extra rows.
@@ -49,9 +51,19 @@ module CrudComponents
         return nil unless @actions_enabled
 
         @actions ||= Actions.new(view: view, subject: record, structure: structure,
-                                 actions: structure.fieldset_actions(fieldset, on: :row),
+                                 actions: declared_row_actions + @extra_actions,
                                  suppress_show: true)
       end
+
+      private
+
+      # Actions this render drops, whatever the model declares.
+      def declared_row_actions
+        actions = structure.fieldset_actions(fieldset, on: :row)
+        return actions if @except_actions.empty?
+
+        actions.reject { |action| @except_actions.include?(action.name) }
+      end
     end
   end
 end

data/lib/crud_components/route_resolver.rb

@@ -7,10 +7,7 @@ module CrudComponents
     module_function
 
     def action_path(view, action, record: nil, model: nil, owner: nil)
-      if action.path_block
-        subject = record || model
-        return view.instance_exec(subject, &action.path_block)
-      end
+      return safe_block(view, record || model, action.path_block) if action.path_block
 
       if action.collection?
         collection_path(view, action, model, owner)
@@ -19,6 +16,20 @@ module CrudComponents
       end
     end
 
+    # The host application's own page for a record — the same candidate logic,
+    # resolved against `main_app` instead of the current route set. A declared
+    # `app_path` block wins. nil when nothing resolves.
+    def app_path(view, record)
+      structure = Structure.for(record.class)
+      if (block = structure.app_path_block)
+        return safe_block(view, record, block)
+      end
+
+      return nil unless view.respond_to?(:main_app)
+
+      try_helpers(view.main_app, member_candidates(nil, record, nil))
+    end
+
     # The plain link to a record (label cells, association cells):
     # show route, then edit. Returns [path, kind] or nil.
     def record_path(view, record, owner: nil)
@@ -79,6 +90,24 @@ module CrudComponents
       nil
     end
 
+    # A path block naming a route helper that does not exist here — the same
+    # page rendered under a mount that lacks it — yields nil, so the button is
+    # omitted. Anything else the block gets wrong is the app's own error and
+    # stays loud.
+    def safe_block(view, subject, block)
+      view.instance_exec(subject, &block)
+    rescue ActionController::UrlGenerationError
+      nil
+    rescue NameError => e
+      raise unless missing_route_helper?(e)
+
+      nil
+    end
+
+    def missing_route_helper?(error)
+      error.name.to_s.end_with?('_path', '_url')
+    end
+
     def safe_url(view, helper, *args, **kwargs)
       kwargs.empty? ? view.public_send(helper, *args) : view.public_send(helper, *args, **kwargs)
     rescue ActionController::UrlGenerationError, NoMethodError
@@ -107,12 +136,13 @@ module CrudComponents
       candidates
     end
 
-    def try_helpers(view, candidates)
+    # `helpers` is anything exposing route helpers — the view, or `main_app`.
+    def try_helpers(helpers, candidates)
       candidates.each do |helper, args|
-        next unless view.respond_to?(helper)
+        next unless helpers.respond_to?(helper)
 
         begin
-          return view.public_send(helper, *args)
+          return helpers.public_send(helper, *args)
         rescue ActionController::UrlGenerationError, NoMethodError
           next
         end

data/lib/crud_components/structure.rb

@@ -42,7 +42,9 @@ module CrudComponents
     # identity_preloads: associations to eager-load whenever this model is shown
     # as another model's association cell (its label/render dependencies), from
     # `label …, preload:` and the standalone `preload` declaration.
-    attr_reader :model, :identify_by, :identity_preloads
+    # admin_options: the `admin` declaration — a Hash of options, `false` when
+    # the model opted out, nil when it said nothing.
+    attr_reader :model, :identify_by, :identity_preloads, :admin_options, :app_path_block
 
     def initialize(model, builder = nil)
       @model = model
@@ -50,6 +52,8 @@ module CrudComponents
       @label_decl = builder&.label_decl
       @identify_by = builder&.identify_by_decl || :id
       @icon_decl = builder&.icon_decl
+      @admin_options = builder&.admin_decl
+      @app_path_block = builder&.app_path_decl
       @search_decl = builder&.search_decl
       @identity_preloads = ((builder&.label_preload_decl || []) + (builder&.preload_decl || [])).uniq
       @declared_actions = builder&.actions || {}
@@ -117,6 +121,9 @@ module CrudComponents
       @default_fieldset ||= Fieldset.new(:default, :all)
     end
 
+    # The fieldsets this model actually declared (no derived defaults).
+    def declared_fieldset_names = @declared_fieldsets.keys
+
     def fieldset_fields(fieldset)
       names = fieldset.all_fields? ? default_field_names : fieldset.field_names
       names.map { |name| field(name) }

data/lib/crud_components/version.rb

@@ -1,3 +1,3 @@
 module CrudComponents
-  VERSION = '0.2.1'.freeze
+  VERSION = '0.3.0'.freeze
 end

data/lib/crud_components.rb

@@ -54,6 +54,7 @@ require_relative 'crud_components/builder'
 require_relative 'crud_components/structure'
 require_relative 'crud_components/model'
 require_relative 'crud_components/query'
+require_relative 'crud_components/admin'
 
 module CrudComponents
   class << self
@@ -166,3 +167,4 @@ module CrudComponents
 end
 
 require_relative 'crud_components/engine' if defined?(Rails::Engine)
+require_relative 'crud_components/admin/engine' if defined?(Rails::Engine)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: crud_components
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Anatoly Zelenin
@@ -82,6 +82,10 @@ files:
 - RELEASING.md
 - Rakefile
 - app/assets/stylesheets/crud_components.css
+- app/assets/stylesheets/crud_components_admin.css
+- app/controllers/crud_components/admin/application_controller.rb
+- app/controllers/crud_components/admin/dashboard_controller.rb
+- app/controllers/crud_components/admin/resources_controller.rb
 - app/views/crud_components/_action_button.html.erb
 - app/views/crud_components/_actions.html.erb
 - app/views/crud_components/_column_header.html.erb
@@ -94,6 +98,14 @@ files:
 - app/views/crud_components/_selection_action.html.erb
 - app/views/crud_components/_sort_link.html.erb
 - app/views/crud_components/_toolbar.html.erb
+- app/views/crud_components/admin/_sidebar.html.erb
+- app/views/crud_components/admin/dashboard/show.html.erb
+- app/views/crud_components/admin/resources/_dependent_records.html.erb
+- app/views/crud_components/admin/resources/delete.html.erb
+- app/views/crud_components/admin/resources/edit.html.erb
+- app/views/crud_components/admin/resources/index.html.erb
+- app/views/crud_components/admin/resources/new.html.erb
+- app/views/crud_components/admin/resources/show.html.erb
 - app/views/crud_components/fields/_asciidoc.html.erb
 - app/views/crud_components/fields/_association.html.erb
 - app/views/crud_components/fields/_association_list.html.erb
@@ -129,9 +141,11 @@ files:
 - app/views/crud_components/form_fields/_string.html.erb
 - app/views/crud_components/form_fields/_text.html.erb
 - app/views/crud_components/layouts/_table.html.erb
+- app/views/layouts/crud_components/admin.html.erb
 - config/locales/crud_components.de.yml
 - config/locales/crud_components.en.yml
 - crud_components.gemspec
+- docs/admin.md
 - docs/extending.md
 - docs/fields.md
 - docs/filtering.md
@@ -141,6 +155,15 @@ files:
 - docs/views.md
 - lib/crud_components.rb
 - lib/crud_components/action.rb
+- lib/crud_components/admin.rb
+- lib/crud_components/admin/configuration.rb
+- lib/crud_components/admin/dependents.rb
+- lib/crud_components/admin/engine.rb
+- lib/crud_components/admin/entry.rb
+- lib/crud_components/admin/gate.rb
+- lib/crud_components/admin/registry.rb
+- lib/crud_components/admin/routes.rb
+- lib/crud_components/admin/view_helpers.rb
 - lib/crud_components/builder.rb
 - lib/crud_components/config.rb
 - lib/crud_components/dynamic_column.rb