presentability 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67ea66c2c975ecb5064c9ddb9c0be1a203b0e9e9944dfc3f3821f07e360fc726
-  data.tar.gz: c13fdaccf960dc87d3feaed73e2a22a96ad805aed83cadbadeeee9cc60e80e49
+  metadata.gz: a47d99629c4294cef8b308ac17e98f5be3967d9c2663caab2ab633c81d512d2e
+  data.tar.gz: 0c325f17f38543a9a7420a9e1ecf727140ecfdc449853ea434f7643343b710e3
 SHA512:
-  metadata.gz: 550a710c7ae589dfc6ebb1ed801508c8e2d347dbd37e1cdd19e3f3699b5b203ad38b7f2dc6a917e71d3e3dd3711e4eefe8c01594a1f4d92f10b120c4fe1e0a82
-  data.tar.gz: 07d9674d3ad188b6b19923153accddf6175bf61d238d79867b7237a34a10595e066e10f4d37cc702bbcca8b7dcf65fd7df75ad0eb2fa0c4557716be3a370090b
+  metadata.gz: e5a49d7d49f0b9f0bc780097620394ecd8d96d62722e746bd34bb9834ba080b767d01527f2417bfb8b8e85c8cda6522621c6b9e0184b0791361343c2fb7b6461
+  data.tar.gz: dbc38700dccecb3e48c18525a836a6b5f2115e6fae5c662e2df7f325e54cd68b82d1940178ab98be41a89fda98a97dc502a18c6038cbd39c2c2e86a5d45890d5

data/GettingStarted.md

@@ -0,0 +1,234 @@
+# Presentability - Getting Started
+
+To set up your own presentation layer, there are three steps:
+
+- Set up a Module as a presenter collection.
+- Declare one or more _presenters_ within the collection.
+- Use the collection to present entities from a service or other limited interface.
+
+For the purposes of this document, we'll pretend we're responsible for creating a JSON web service for Acme Widgets, Inc. We've declared all of our company's code inside the `Acme` namespace. We're using a generic Sinatra-like web framework that lets you declare endpoints like so:
+
+```ruby
+get '/status_check' do |parameters|
+    return { status: 'success' }.to_json
+end
+```
+
+
+## Create a Presenter Collection
+
+A _presenter collection_ is just a Module somewhere within your namespace that one can use to access the declared presenters. You designate it as a presenter collection simply by `extend`ing `Presentability`.
+
+We'll declare ours under `Acme` and call it `Presenters`:
+
+```ruby
+require 'presentability'
+
+require 'acme'
+
+module Acme::Presenters
+    extend Presentability
+
+    # Presenters will be declared here
+
+end # module Acme::Presenters
+```
+
+Since we haven't declared any presenters, the collection isn't really all that useful yet, so let's declare some.
+
+
+## Declare Presenters
+
+A _presenter_ is an object that is responsible for constructing a _representation_ of another object. There are a number of reasons to use a presenter:
+
+- Security: avoid exposing sensitive data from your domain objects to the public, e.g., passwords, internal prices, numeric IDs, etc.
+- Transform: normalize and flatten complex objects to some standard form, e.g., convert `Time` object timestamps to RFC 2822 form.
+- Consistency: change your model layer independently of your service's entities, e.g., adding a new column to a model doesn't automatically expose it in the service layer.
+
+The _representation_ is just a simple object that serves as an intermediate form for the transformed object until it is ultimately encoded. The default _representation_ is an empty `Hash`, but you can customize it to suit your needs.
+
+To declare a presenter, we'll call the `presenter_for` method on the presenter collection module, and then call `expose` or `expose_collection` for each attribute that should be exposed.
+
+The first argument to `presenter_for` is the type of object the presenter is for, which can be specified in a couple of different ways. The easiest is to just pass in the class itself. The domain class the Acme service is built around is the Widget, so let's declare a presenter for it:
+
+```ruby
+require 'acme/widget'
+
+module Acme::Presenters
+    extend Presentability
+
+    presenter_for Acme::Widget do
+        expose :name
+    end
+
+end # module Acme::Presenters
+```
+
+To present an object, call `.present` on the collection module with the object to be presented, and it will return a representation that is a `Hash` with a single `:name` key-value pair:
+
+```ruby
+widget = Acme::Widget.where( name: 'The Red One' )
+Acme::Presenters.present( widget )
+# => { name: "The Red One" }
+```
+
+If we want to add a `sku` field to all widgets served by our service, we just add another exposure:
+
+```ruby
+expose :sku
+```
+
+```ruby
+widget = Acme::Widget.where( name: 'The Red One' )
+Acme::Presenters.present( widget )
+# => { name: "The Red One", sku: 'DGG-17044-0822' }
+```
+
+### Overriding Exposures
+
+Sometime you want to alter the value that appears for a particular field. Say, for example, that the SKU that we exposed in our Widget presenter has an internal-only suffix in the form: `-xxxx` that we'd like to avoid exposing in a public-facing service. We can accomplish this by adding a block to it that alters the field from the model. Inside this block, the original object can be accessed via the `subject` method, so we can call the original `#sku` method and truncate it:
+
+```ruby
+expose :sku do
+    original = self.subject.sku
+    return original.sub(/-\d{4}/, '')
+end
+```
+
+Now the last part of the SKU will be removed in the representation:
+
+```ruby
+widget = Acme::Widget.where( name: 'The Red One' )
+Acme::Presenters.present( widget )
+# => { name: "The Red One", sku: 'DGG-17044' }
+```
+
+### Exposure Options
+
+You can also pass zero or more options as a keyword Hash when presenting:
+
+```ruby
+Acme::Presenters.present( widget, internal: true )
+```
+
+There are a few ways options can be used out of the box:
+
+#### Exposure Aliases
+
+Sometimes you want the field in the representation to have a different name than the method on the model object:
+
+```ruby
+presenter_for Acme::Company do
+    expose :id
+    expose :legal_entity, as: :name
+    expose :icon_url, as: :icon
+end
+```
+
+In the representation, the `#legal_entity` method will be called on the `Company` being presented and the return value associated with the `:name` key, and the same for `#icon_url` and `:icon`:
+
+```ruby
+{ id: 4, name: "John's Small Grapes", icon: "grapes-100.png" }
+```
+
+#### Conditional Exposure
+
+You can make an exposure conditional on an option being passed or not:
+
+```ruby
+# Don't include the price if presented with `public: true` option set
+expose :price, unless: :public
+
+# Only include the settings if presented with `detailed: true` option set
+expose :settings, if: :detailed
+```
+
+#### Collection Exposure
+
+A common use-case for conditional presentations is when you want an entity in a collection to be a less-detailed version. E.g.,
+
+```ruby
+presenter_for Acme::User do
+    expose :id
+    expose :username
+    expose :email
+
+    expose :settings, unless: :in_collection
+end
+```
+
+You can pass `in_collection: true` when you're presenting, but you can also use the `present_collection` convenience method which sets it for you:
+
+```ruby
+users = Acme::User.where( :activated ).limit( 20 )
+Acme::Presenters.present_collection( users )
+# => [{ id: 1, username: 'fran', email: 'fran@example.com'}, ...]
+```
+
+#### Custom Options
+
+You also have access to the presenter options (via the `#options` method) in a overridden exposure block. With this you can build your own presentation logic:
+
+```ruby
+presenter_for Acme::Widget do
+    expose :name
+    expose :sku
+
+    expose :scancode do
+        self.subject.make_scancode( self.options[:scantype] )
+    end
+end
+
+# In your service:
+widget = Acme::Widget[5]
+Acme::Presenters.present( widget, scantype: :qr )
+# { name: "Duck Quackers", sku: 'HBG-121-0424', scancode: '<qrcode data>'}
+```
+
+
+## Declare Serializers
+
+Oftentimes your model objects include values which are themselves not inherently serializable to your representation format. To help with this, you can also declare a "serializer" for one or more classes in your collection using the `.serializer_for` method:
+
+```ruby
+require 'time' # for Time#rfc2822
+
+module Acme::Presenters
+    extend Presentability
+
+    serializer_for :IPAddr, :to_s
+    serializer_for Time, :rfc2822
+    serializer_for Set, :to_a
+
+end # module Acme::Presenters
+```
+
+Now when one of your models includes any of the given types, the corresponding method will be called on it and the result used as the value instead.
+
+## Use the Roda Plugin
+
+If you're using the excellent [Roda](https://roda.jeremyevans.net/) web framework, `Presentability` includes a plugin for using it in your Roda application. To enable it, in your app just `require` your collection and enable the plugin. That will enable you to use `#present` and `#present_collection` in your routes:
+
+```ruby
+require 'roda'
+require 'acme/presenters'
+
+class Acme::WebService < Roda
+
+    plugin :presenters, collection: Acme::Presenters
+    plugin :json
+
+    route do |r|
+        r.on "users" do
+            r.is do
+                # GET /users
+                r.get do
+                    users = Acme::User.where( :activated )
+                    present_collection( users.all )
+                end
+            end
+        end
+    end
+end # class Acme::WebService
+```
+

data/History.md

@@ -1,6 +1,24 @@
 # Release History for presentability
 
 ---
+
+## v0.6.0 [2024-04-29] Michael Granger <ged@faeriemud.org>
+
+Improvements:
+
+- Added custom serialization, and better collection handling
+- Added a Roda plugin
+- Improved documentation
+
+
+## v0.5.0 [2023-11-06] Michael Granger <ged@faeriemud.org>
+
+Improvements:
+
+- Add recursive presentation
+- Allow presenters to be defined for objects with no instance variables
+
+
 ## v0.4.0 [2023-02-02] Michael Granger <ged@faeriemud.org>
 
 Improvements:

data/README.md

@@ -56,6 +56,8 @@ your data objects that return a limited representation of their subjects.
 More details can be found in the docs for the Presentability module, and in
 Presentability::Presenter.
 
+See GettingStarted to get started with your own presenters.
+
 
 ## Prerequisites
 
@@ -88,7 +90,7 @@ This will install dependencies, and do any other necessary setup for development
 
 ## License
 
-Copyright (c) 2022, Michael Granger
+Copyright (c) 2022-2024, Michael Granger
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

data/lib/presentability/presenter.rb

@@ -4,7 +4,119 @@ require 'loggability'
 
 require 'presentability' unless defined?( Presentability )
 
-# :include: Presenter.md
+#
+# A presenter (facade) base class.
+#
+#
+# ### Declaring Presenters
+#
+# When you declare a presenter in a Presentability collection, the result is a
+# subclass of Presentability::Presenter. The main way of defining a Presenter's
+# functionality is via the ::expose method, which marks an attribute of the underlying
+# entity object (the "subject") for exposure.
+#
+#     class MyPresenter < Presentability::Presenter
+#       expose :name
+#     end
+#
+#     # Assuming `entity_object' has a "name" attribute...
+#     presenter = MyPresenter.new( entity_object )
+#     presenter.apply
+#     # => { :name => "entity name" }
+#
+#
+# ### Presenter Collections
+#
+# Setting up classes manually like this is one option, but Presentability also lets you
+# set them up as a collection, which is what further examples will assume for brevity:
+#
+#     module MyPresenters
+#       extend Presentability
+#
+#       presenter_for( EntityObject ) do
+#         expose :name
+#       end
+#
+#     end
+#
+#
+# ### Complex Exposures
+#
+# Sometimes you want to do more than just use the presented entity's values as-is.
+# There are a number of ways to do this.
+#
+# The first of these is to provide a block when exposing an attribute. The subject
+# of the presenter is available to the block via the `subject` method:
+#
+#     require 'time'
+#
+#     presenter_for( LogEvent ) do
+#       # Turn Time objects into RFC2822-formatted time strings
+#       expose :timestamp do
+#         self.subject.timestamp.rfc2822
+#       end
+#
+#     end
+#
+# You can also declare the exposure using a regular method with the same name:
+#
+#     require 'time'
+#
+#     presenter_for( LogEvent ) do
+#       # Turn Time objects into RFC2822-formatted time strings
+#       expose :timestamp
+#
+#       def timestamp
+#         return self.subject.timestamp.rfc2822
+#       end
+#
+#     end
+#
+# This can be used to add presence checks:
+#
+#     require 'time'
+#
+#     presenter_for( LogEvent ) do
+#       # Require that presented entities have an `id` attribute
+#       expose :id do
+#         id = self.subject.id or raise "no `id' for %p" % [ self.subject ]
+#         raise "`id' for %p is blank!" % [ self.subject ] if id.blank?
+#
+#         return id
+#       end
+#     end
+#
+# or conditional exposures:
+#
+#     presenter_for( Acme::Product ) do
+#
+#       # Truncate the long description if presented as part of a collection
+#       expose :detailed_description do
+#         desc = self.subject.detailed_description
+#         if self.options[:in_collection]
+#           return desc[0..15] + '...'
+#         else
+#           return desc
+#         end
+#       end
+#
+#     end
+#
+#
+# ### Exposure Aliases
+#
+# If you want to expose a field but use a different name in the resulting data
+# structure, you can use the `:as` option in the exposure declaration:
+#
+#     presenter_for( LogEvent ) do
+#       expose :timestamp, as: :created_at
+#     end
+#
+#     presenter = MyPresenter.new( log_event )
+#     presenter.apply
+#     # => { :created_at => '2023-02-01 12:34:02.155365 -0800' }
+#
+#
 class Presentability::Presenter
 	extend Loggability
 
@@ -57,6 +169,14 @@ class Presentability::Presenter
 	end
 
 
+	### Set up an exposure of a collection with the given +name+. This means it will
+	### have the :in_collection option set by default.
+	def self::expose_collection( name, **options, &block )
+		options = options.merge( unless: :in_collection )
+		self.expose( name, **options, &block )
+	end
+
+
 	### Generate the body an exposure method that delegates to a method with the
 	### same +name+ on its subject.
 	def self::generate_expose_method( name, **options )
@@ -107,12 +227,14 @@ class Presentability::Presenter
 
 
 	### Apply the exposures to the subject and return the result.
-	def apply
+	def apply( presenters )
 		result = self.empty_representation
 
 		self.class.exposures.each do |name, exposure_options|
 			next if self.skip_exposure?( name )
+			self.log.debug "Presenting %p" % [ name ]
 			value = self.method( name ).call
+			value = presenters.present( value, **exposure_options )
 			key = exposure_options.key?( :as ) ? exposure_options[:as] : name
 			result[ key.to_sym ] = value
 		end

data/lib/presentability.rb

@@ -3,14 +3,118 @@
 require 'loggability'
 
 
-# :include: Presentability.md
+#
+# Facade-based presenter toolkit with minimal assumptions.
+#
+# ## Basic Usage
+#
+# Basic usage of Presentability requires two steps: declaring presenters and
+# then using them.
+#
+# ### Declaring Presenters
+#
+# Presenters are just regular Ruby classes with some convenience methods for
+# declaring exposures, but in a lot of cases you'll want to declare them all in
+# one place. Presentability offers a mixin that implements a simple DSL for
+# declaring presenters and their associations to entity classes, intended to be
+# used in a container module:
+#
+#     require 'presentability'
+#
+#     module Acme::Presenters
+#       extend Presentability
+#
+#       presenter_for( Acme::Widget ) do
+#           expose :sku
+#           expose :name
+#           expose :unit_price
+#       end
+#
+#     end
+#
+# The block of `presenter_for` is evaluated in the context of a new Presenter
+# class, so refer to that documentation for what's possible there.
+#
+# Sometimes you can't (or don't want to) have to load the entity class to
+# declare a presenter for it, so you can also declare it using the class's name:
+#
+#     presenter_for( 'Acme::Widget' ) do
+#         expose :sku
+#         expose :name
+#         expose :unit_price
+#     end
+#
+#
+# ### Using Presenters
+#
+# You use presenters by instantiating them with the object they are a facade for
+# (the "subject"), and then applying it:
+#
+#     acme_widget = Acme::Widget.new(
+#         sku: "FF-2237H455",
+#         name: "Throbbing Frobnulator",
+#         unit_price: 299,
+#         inventory_count: 301,
+#         wholesale_cost: 39
+#     )
+#     presentation = Acme::Presenters.present( acme_widget )
+#     # => { :sku => "FF-2237H455", :name => "Throbbing Frobnulator", :unit_price => 299 }
+#
+# If you want to present a collection of objects as a collection, you can apply
+# presenters to the collection instead:
+#
+#     widgets_in_stock = Acme::Widget.where { inventory_count > 0 }
+#     collection_presentation = Acme::Presenters.present_collection( widgets_in_stock )
+#     # => [ {:sku => "FF-2237H455", [...]}, {:sku => "FF-2237H460", [...]}, [...] ]
+#
+# The collection can be anything that is `Enumerable`.
+#
+#
+# ### Presentation Options
+#
+# Sometimes you want a bit more flexibility in what you present, allowing a single
+# uniform presenter to be used in multiple use cases. To facilitate this, you can pass
+# an options keyword hash to `#present`:
+#
+#     presenter_for( 'Acme::Widget' ) do
+#         expose :sku
+#         expose :name
+#         expose :unit_price
+#
+#         # Only expose the wholesale cost if presented via an internal API
+#         expose :wholesale_cost, if: :internal_api
+#     end
+#
+#     acme_widget = Acme::Widget.new(
+#         sku: "FF-2237H455",
+#         name: "Throbbing Frobnulator",
+#         unit_price: 299,
+#         inventory_count: 301,
+#         wholesale_cost: 39
+#     )
+#
+#     # External API remains unchanged:
+#     presentation = Acme::Presenters.present( acme_widget )
+#     # => { :sku => "FF-2237H455", :name => "Throbbing Frobnulator", :unit_price => 299 }
+#
+#     # But when run from an internal service:
+#     internal_presentation = Acme::Presenters.present( acme_widget, internal_api: true )
+#     # => { :sku => "FF-2237H455", :name => "Throbbing Frobnulator", :unit_price => 299,
+#     #      :wholesale_cost => 39 }
+#
+# There are some options that are set for you:
+#
+# <dl>
+# <td><code>:in_collection</code></td>
+# <dd>Set if the current object is being presented as part of a collection.</dd>
+# </dl>
+#
 module Presentability
 	extend Loggability
 
 
 	# Package version
-	VERSION = '0.4.0'
-
+	VERSION = '0.6.0'
 
 	# Automatically load subordinate components
 	autoload :Presenter, 'presentability/presenter'
@@ -20,15 +124,29 @@ module Presentability
 	log_as :presentability
 
 
+	#
+	# Hooks
+	#
+
 	### Extension hook -- decorate the including +mod+.
 	def self::extended( mod )
 		super
 		mod.singleton_class.attr_accessor :presenters
+		mod.singleton_class.attr_accessor :serializers
+
 		mod.presenters = {}
+		mod.serializers = {
+			Array => mod.method( :serialize_array ),
+			Hash => mod.method( :serialize_hash ),
+		}
 	end
 
 
 
+	#
+	# DSL Methods
+	#
+
 	### Set up a presentation for the given +entity_class+.
 	def presenter_for( entity_class, &block )
 		presenter_class = Class.new( Presentability::Presenter )
@@ -38,11 +156,30 @@ module Presentability
 	end
 
 
+	### Set up a rule for how to serialize objects of the given +type+ if there is
+	### no presenter declared for it.
+	def serializer_for( type, method )
+		self.serializers[ type ] = method
+	end
+
+
+	#
+	# Presentation Methods
+	#
+
 	### Return a representation of the +object+ by applying a declared presentation.
 	def present( object, **options )
 		representation = self.present_by_class( object, **options ) ||
-			self.present_by_classname( object, **options ) or
-			raise NoMethodError, "no presenter found for %p" % [ object ]
+			self.present_by_classname( object, **options ) ||
+			self.serialize( object, **options )
+
+		unless representation
+			if object.instance_variables.empty?
+				return object
+			else
+				raise NoMethodError, "no presenter found for %p" % [ object ], caller( 1 )
+			end
+		end
 
 		return representation
 	end
@@ -56,6 +193,37 @@ module Presentability
 	end
 
 
+	### Serialize the specified +object+ if a serializer has been declared for it
+	### and return the scalar result.
+	def serialize( object, ** )
+		serializer = self.serializers[ object.class ] ||
+			self.serializers[ object.class.name ] or
+			return nil
+		serializer_proc = serializer.to_proc
+
+		return serializer_proc.call( object )
+	end
+
+
+	### Default serializer for an Array; returns a new array of presented objects.
+	def serialize_array( object )
+		return object.map do |member|
+			self.present( member, in_collection: true )
+		end
+	end
+
+
+	### Default serializer for a Hash; returns a new Hash of presented keys and values.
+	def serialize_hash( object )
+		return object.each_with_object( {} ) do |(key, val), newhash|
+			p_key = self.present( key, in_collection: true )
+			p_val = self.present( val, in_collection: true )
+
+			newhash[ p_key ] = p_val
+		end
+	end
+
+
 	#########
 	protected
 	#########
@@ -66,7 +234,7 @@ module Presentability
 		presenter_class = self.presenters[ object.class ] or return nil
 		presenter = presenter_class.new( object, **presentation_options )
 
-		return presenter.apply
+		return presenter.apply( self )
 	end
 
 
@@ -77,7 +245,7 @@ module Presentability
 		presenter_class = self.presenters[ classname ] or return nil
 		presenter = presenter_class.new( object, **presentation_options )
 
-		return presenter.apply
+		return presenter.apply( self )
 	end
 
 end # module Presentability