magic-presenter 1.2.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d5fe98ce37280316a18f2600366cd5fbcde0b12f447bf6a00821a356f140e061
-  data.tar.gz: e9b90001111944c9f353ebc82851233a24d93ad316d45e5535cdc1d968e86c11
+  metadata.gz: 018f8d173f204bef93fdaf99a35417b1018a81517231f673a0dd44a1644ee61b
+  data.tar.gz: e0ca0e5a3b439b40e20d429f7f7ba35c48390f51debb30510445d4e1d682b948
 SHA512:
-  metadata.gz: 3416439e712b63b70cbabce8c74806489023fe5335f29a2a4efca7edca94324dbb966b834f9fc3e8f6a20022c5fc6acf45b7fe45219c1e50edc80226378ff3e2
-  data.tar.gz: bdfe8668cfec9f90267617c82da4cda1afecff36223e3312243fd850a865b6979350c3bc94f44e0a0646c825e29731de527a9e50b37e4bc866ab559a040555d6
+  metadata.gz: 3c2913873efd49741bf0991eb34cfd30e32ceede34a84eef752b86c951625cd173db3b4069473f16a0ecfc6e1ea8d26c9a75a8d8525a4e35c5d8e81e38346841
+  data.tar.gz: e28356ed613cc0f68f46618ba989956fd3dd467d91ec0bf81f1d9aced9f6504208a7dedff8ebd05bdfcb2bf7214d5dadc97ba961738928ee2fe09578a7b66eb5

data/README.md

@@ -55,6 +55,8 @@ person = Person.new(first_name: 'John', last_name: 'Smith').decorate
 person.name # => "John Smith"
 ```
 
+Use [load hooks](#load-hooks) to extend the base presenter functionality.
+
 ### `Magic::Presentable`
 
 This module includes `Magic::Decoratable` and allows a descendant to be decorated by presenters only.
@@ -64,6 +66,26 @@ When no presenter is found,
 - `#decorate!` raises `Magic::Lookup::Error`,
 - `#decorated` returns the original object.
 
+Use [load hooks](#load-hooks) to extend the functionality.
+
+#### Collections
+
+Active Record relations are presentable as collections. Define a collection presenter inside the matching presenter to customize collection behavior:
+
+```ruby
+class PersonPresenter < Magic::Presenter::Base
+  collection_presenter do
+    def names = map(&:name).to_sentence
+  end
+end
+
+Person.all.decorated.names
+```
+
+Under the hood, `.collection_presenter` defines `PersonPresenter::Collection < Magic::Presenter::Collection` in the above example and evaluates the block within that class’ context. 
+It looks for a collection presenter class in ancestor classes to be inherited from, up to `Magic::Presenter::Collection`.
+One can also define a collection presenter class explicitly, following the same pattern.
+
 ### Generators
 
 A generator can be used to generate a presenter:
@@ -103,6 +125,25 @@ end
 > [!NOTE]
 > A valid `request` may be needed for URL helpers to get host data.
 
+### Load hooks
+
+Load hooks are triggered when `Magic::Presenter::Base` or `Magic::Presentable` are loaded.
+They allow you to run custom initialization code for configuration or to extend the functionality.
+
+```ruby
+ActiveSupport.on_load :presenter do
+  # Put the code to be executed when Magic::Presenter is loaded here.
+  # It runs in the context of Magic::Presenter::Base class.
+end
+```
+
+```ruby
+ActiveSupport.on_load :presentable do
+  # Put the code to be executed when Magic::Presentable is loaded here.
+  # It runs in the context of Magic::Presentable module.
+end
+```
+
 ## 🧙 Magic
 
 > [!IMPORTANT]
@@ -110,6 +151,8 @@ end
 > 	https://github.com/Alexander-Senko/magic-decorator#magic
 > ), so get familiar with that one as well.
 
+In short, the phylosophy is: _**define presenters you need and expect them to be applied automagically to all the corresponding objects** in every appropriate (view) context_.
+
 ### Presentable scope
 
 `Magic::Presentable` is mixed into `ActiveModel::API` by default.
@@ -149,6 +192,7 @@ Missing class methods of a presenter are delegated to a matching model class if
 > [!NOTE]
 > Every object passed to views is decorated automagically.
 > This involves both implicit instance variables and `locals` passed explicitly.
+> Controller helper methods are also decorated when called from views.
 
 ### Helpers
 

data/app/models/concerns/magic/presentable/active_record_collection.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Magic
+	module Presentable
+		# = Presentable Active Record relation
+		#
+		# A tiny wrapper around `Presentable::Collection` for Active Record
+		# relations.
+		module ActiveRecordCollection
+			include Collection
+
+			def model_class = model
+		end
+	end
+end

data/app/models/concerns/magic/presentable/collection.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Magic
+	module Presentable
+		# = Presentable collection
+		#
+		# This module includes `Magic::Decoratable` and allows a descendant
+		# to be decorated by collection presenters only. Presenter class is
+		# being inferred automatically from a collection’s model class.
+		module Collection
+			include Decoratable
+
+			private
+
+			def decorator      = decorator_base.for model_class
+			def decorator_base = Presenter::Collection
+		end
+	end
+end

data/app/models/concerns/magic/presentable.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module Magic
+	# = Presentable object
+	#
 	# This module includes `Magic::Decoratable` and allows a descendant
 	# to be decorated by presenters only. Presenter class is being
 	# inferred automatically.
@@ -12,4 +14,6 @@ module Magic
 
 		def decorator_base = Presenter::Base
 	end
+
+	ActiveSupport.run_load_hooks :presentable, Presentable
 end

data/config/initializers/action_view.rb

@@ -22,6 +22,16 @@ ActiveSupport.on_load :action_view do # rubocop:disable Metrics/BlockLength
 		end
 	end
 
+	concerning :DecoratedHelpers, prepend: true do
+		require 'magic/decorator/core_ext/module'
+
+		def assign_controller controller
+			super
+
+			self.class.decorated_method controller._helper_methods
+		end
+	end
+
 	concerning :PresenterContext, prepend: true do
 		def in_rendering_context(...)
 			Magic::Presenter.with view_context: self do

data/config/initializers/presentable.rb

@@ -3,3 +3,7 @@
 Rails.application.config.to_prepare do
 	ActiveModel::API.include Magic::Presentable
 end
+
+ActiveSupport.on_load :active_record do
+	ActiveRecord::Relation.include Magic::Presentable::ActiveRecordCollection
+end

data/lib/magic/presenter/base.rb

@@ -18,6 +18,8 @@ module Magic
 			include GlobalID if defined? ::GlobalID
 			prepend Helpers  if defined? ::ActionView
 
+			Collection = Collection # for lookup
+
 			class << self
 				def name_for object_class
 					object_class
@@ -30,7 +32,35 @@ module Magic
 				def model_class = Presentable.for self
 
 				delegate_missing_to :model_class
+
+				private
+
+				# Define collection presenter from the given block.
+				#
+				#   class MyPresenter < Magic::Presenter::Base
+				#     collection_presenter do
+				#       def count = "#{super} items"
+				#     end
+				#   end
+				#
+				#   class MyModel < ApplicationRecord
+				#   end
+				#
+				#   MyModel.all.count           # =>  42
+				#   MyModel.all.decorated.count # => "42 items"
+				#
+				# It looks for a collection presenter class in ancestor classes
+				# to be inherited from, up to `Magic::Presenter::Collection`.
+				def collection_presenter(&)
+					if const_defined? :Collection, false
+						const_get :Collection
+					else
+						const_set :Collection, Class.new(const_get :Collection)
+					end.class_eval(&)
+				end
 			end
 		end
+
+		ActiveSupport.run_load_hooks :presenter, Base
 	end
 end

data/lib/magic/presenter/collection.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Magic
+	module Presenter
+		# = Collection presenter
+		#
+		# This presenter is used as a base class to decorate typed
+		# collections (e.g., Active Record relations).
+		#
+		# == Presenter class inference
+		#
+		# Collection presenters provide automatic class inference for any
+		# typed collection based on the class name of its elements powered
+		# by Magic Lookup.
+		# For example, a collection of `MyRecord`s (e.g., `MyRecord.all`)
+		# looks for `MyPresenter::Collection` first.
+		# If not found, it looks for collection presenters of its ancestor
+		# classes, up to `ObjectPresenter::Collection`.
+		class Collection < EnumerableDecorator
+			prepend Helpers if defined? ::ActionView
+
+			class << self
+				def name_for(...) = Base.name_for(...)
+						.concat('::Collection')
+			end
+
+			def item_presenter = model_class
+					&.then { Presenter.for it }
+
+			def model_class = __getobj__
+					.try :model_class
+
+			def to_a(...) = self.class.new super
+		end
+	end
+end

data/lib/magic/presenter/engine.rb

@@ -2,7 +2,7 @@
 
 module Magic
 	module Presenter
-		class Engine < ::Rails::Engine # :nodoc:
+		class Engine < ::Rails::Engine
 			isolate_namespace Magic::Presenter
 
 			config.generators do

data/lib/magic/presenter/helpers.rb

@@ -44,7 +44,8 @@ module Magic
 
 			def respond_to_missing?(method, ...)
 				super or
-						(helpers if view_context).respond_to?(method, ...)
+						(helpers if view_context)
+								&.respond_to?(method, ...) # rubocop:disable Lint/RedundantSafeNavigation
 			end
 		end
 	end

data/lib/magic/presenter/version.rb

@@ -2,6 +2,6 @@
 
 module Magic
 	module Presenter
-		VERSION = '1.2.0'
+		VERSION = '1.4.0'
 	end
 end

data/lib/magic/presenter.rb

@@ -5,14 +5,15 @@ require 'magic/decorator'
 require_relative 'presenter/version'
 require_relative 'presenter/engine'
 
-module Magic # :nodoc:
+module Magic
 	# Presentation layer for Rails models
 	module Presenter
-		autoload :Base,      'magic/presenter/base'
-		autoload :Helpers,   'magic/presenter/helpers'
-		autoload :GlobalID,  'magic/presenter/global_id'
-		autoload :TestCase,  'magic/presenter/test_case'
-		autoload :Generator, 'generators/magic/presenter/generator'
+		autoload :Base,       'magic/presenter/base'
+		autoload :Collection, 'magic/presenter/collection'
+		autoload :Helpers,    'magic/presenter/helpers'
+		autoload :GlobalID,   'magic/presenter/global_id'
+		autoload :TestCase,   'magic/presenter/test_case'
+		autoload :Generator,  'generators/magic/presenter/generator'
 
 		singleton_class.delegate *%i[
 				for name_for

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: magic-presenter
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.4.0
 platform: ruby
 authors:
   - Alexander Senko
@@ -40,7 +40,7 @@ dependencies:
         -
           - ~>
           - !ruby/object:Gem::Version
-            version: "1.0"
+            version: "1.2"
     type: :runtime
     prerelease: false
     version_requirements: !ruby/object:Gem::Requirement
@@ -48,7 +48,7 @@ dependencies:
         -
           - ~>
           - !ruby/object:Gem::Version
-            version: "1.0"
+            version: "1.2"
   - !ruby/object:Gem::Dependency
     name: magic-lookup
     requirement: !ruby/object:Gem::Requirement
@@ -76,6 +76,8 @@ files:
   - README.md
   - Rakefile
   - app/models/concerns/magic/presentable.rb
+  - app/models/concerns/magic/presentable/active_record_collection.rb
+  - app/models/concerns/magic/presentable/collection.rb
   - config/initializers/action_controller.rb
   - config/initializers/action_view.rb
   - config/initializers/generators.rb
@@ -95,6 +97,7 @@ files:
   - lib/magic/presenter.rb
   - lib/magic/presenter/authors.rb
   - lib/magic/presenter/base.rb
+  - lib/magic/presenter/collection.rb
   - lib/magic/presenter/engine.rb
   - lib/magic/presenter/global_id.rb
   - lib/magic/presenter/helpers.rb
@@ -108,7 +111,7 @@ licenses:
 metadata:
   homepage_uri: "https://github.com/Alexander-Senko/magic-presenter"
   source_code_uri: "https://github.com/Alexander-Senko/magic-presenter"
-  changelog_uri: "https://github.com/Alexander-Senko/magic-presenter/blob/v1.2.0/CHANGELOG.md"
+  changelog_uri: "https://github.com/Alexander-Senko/magic-presenter/blob/v1.4.0/CHANGELOG.md"
 rdoc_options: []
 require_paths:
   - lib