roda-phlex 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d4325bf47a07f07abf3c30722c16bcd2422559e3ae8ef3af32803efe081d640c
-  data.tar.gz: fe31c12b510c61204b61996b6f22a696a8e82ba1f6a491ffe399c71e30bae365
+  metadata.gz: 1012a871d2413c575d0807b04cfc92d9c39bbddc82b3a5769c398a82a1868951
+  data.tar.gz: 371dac4531e28280836ad52dcb623ef4fef01b7331c2a1a364c9f58fc0b598b8
 SHA512:
-  metadata.gz: 3174f3c8d94c44d3876a51fe5f5d531f3feee7e5143d0b98a43e6978537f1b4e070c260f73421fb5bd04e9d8619e83067ab34eef073c7f91836d3c9a2e94df32
-  data.tar.gz: c6eb86db087726ee22f7cf2d0df7c140c34433606279675bd56c26158b361c9b0b34f8369eb9a390c04193b5b5c8e17e6591bb599553a1ffef06499be901baf3
+  metadata.gz: 0a1221224003fa28b9ea5d73eccd8a93d60d0186d01dd05f2c28947cabfc3b7c1d7b1349159b2778777fe03af25affa4643780505a1b197ec80e9741ae191460
+  data.tar.gz: c044bf1340e4c95bd72d37c64f1f5af3a183950237b8884d451be51a74e3792eb4fc3a7c6b107779eacaec6e4ce0dd4570aaed7fb075a89664ffa3087ef8cd22

data/.rspec

@@ -1,3 +1,4 @@
 --format documentation
 --color
 --require spec_helper
+--tag ~isolate

data/CHANGELOG.md

@@ -18,6 +18,37 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 
 ### Security
 
+## [0.3.0] - 2025-01-27
+
+### Added
+
+- Support for Phlex Component context. (`HelloWorld.new.call(context: {some: :data})`).
+    + Like layout options, the `:context` plugin option can be used to set a default context.
+    The value will be`dup`ed on first use.
+    + `#phlex_context` method to access the context.
+    + `#set_phlex_context` method to set the context.
+- `:delegate_on` plugin option to specify the object to delegate methods to.
+  Defaults to `::Phlex::SGML` but its advised to set it to your own subclass of `::Phlex::SGML`.
+- `:delegate_name` plugin option to specify name of the method that delegates to the Roda app.
+  Defaults to `"app"`.
+
+### Changed
+
+- `#phlex_layout`, `#phlex_layout_opts`, `#phlex_layout_handler` no longer accept a value to set their value.
+  Use their corresponding `#set_*` methods instead.
+
+### Removed
+
+- `delegate: :all` plugin option removed. You need to specify the methods to delegate explicitly.
+- `delegate: <Symbol,String>` plugin option removed. Method names need to be specified as an array of
+  symbols or strings, even when delegating only one method.
+
+### Fixed
+
+- Mutating the layout options hash no longer affects subsequent requests.
+  The value passed as `:layout_opts` plugin config is now `dup`ed on first use.
+  Note, that mutating nested objects will still affect the original hash.
+
 ## [0.2.0] - 2024-12-13
 
 ### Added
@@ -41,7 +72,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 
 ________________________________________________________________________________
 
-[Unreleased]: https://github.com/fnordfish/roda-phlex/compare/v0.2.0...main
+[Unreleased]: https://github.com/fnordfish/roda-phlex/compare/v0.3.0...phlex-1
+[0.3.0]: https://github.com/fnordfish/roda-phlex/releases/tag/v0.3.0
 [0.2.0]: https://github.com/fnordfish/roda-phlex/releases/tag/v0.2.0
 [0.1.0]: https://github.com/fnordfish/roda-phlex/releases/tag/v0.1.0
 

data/README.md

@@ -30,17 +30,24 @@ gem install roda-phlex
 * `:layout_opts` (`Object`): Options that are passed to the layout
   class when it is instantiated. These options can be used to customize
   the behavior of the layout. Usually, this is a `Hash`.
+  To avoid external changes effecting subsequent requests, you should `.freeze` this
+  and all nested objects.
 * `:layout_handler` (`#call`): A custom handler for creating layout
   instances. This proc receives three arguments: the layout class, the
   layout options, and the object to be rendered. By default, it runs
   `layout.new(obj, **layout_opts)`, which instantiates the layout class with the
   provided view object and options as keyword arguments.
+* `:context` (`Hash`): The context that is passed to the rendering call. (default: `{}`)
+  To avoid external changes effecting subsequent requests, you should `.freeze` this
+  and all nested objects.
 * `:delegate`: Define if or which methods should be delegated to the Roda app:
     + `true` (default): Create a single `app` method that delegates to the Roda app.
     + `false`: Do not create any delegate methods.
-    + `:all`: Delegate all methods the Roda app responds to, to it. Be careful with this option.
-              It can lead to unexpected behavior if the Roda app has methods that conflict with Phlex methods.
-    + `Symbol`, `String`, `Array<Symbol,String>`: Delegate only the specified methods to the Roda app.
+    + `Array<Symbol,String>`: Delegate the named methods to the Roda app.
+* `:delegate_on`: Class or module to define delegation methods on. Defaults to `::Phlex::SGML`.
+    + Use this option to limit delegation methods to a application specific class or module
+     (like "ApplicationView") to avoid polluting the global namespace.
+* `:delegate_name`: The name of the method that delegates to the Roda app. Defaults to `"app"`.
 
 ## Usage
 
@@ -117,7 +124,7 @@ class Layout < Phlex::HTML
         # Standard site header and navigation.
         render Header.new
 
-        yield_content(&block)
+        yield
       }
     }
   end
@@ -142,16 +149,17 @@ end
 
 ```ruby
 # Define a default layout and layout options for the whole application
-plugin :phlex, layout: MyLayout, layout_opts: { title: +"My App" }
+plugin :phlex, layout: MyLayout, layout_opts: { title: "My App".freeze }.freeze
+
 route do |r|
   r.on "posts" do
     # redefine the layout and layout options for this route tree
-    phlex_layout MyPostLayout
-    phlex_layout_opts[:title] << " - Posts"
+    set_phlex_layout MyPostLayout
+    set_phlex_layout_opts phlex_layout_opts.merge(title: "#{phlex_layout_opts[:title]} - Posts")
 
     r.get 'new' do
       # Redefine the layout and layout options for this route
-      phlex_layout_opts[:title] = "Create new post"
+      phlex_layout_opts[:title] << " - Create new post"
       phlex MyView.new
     end
   end

data/Rakefile

@@ -7,4 +7,9 @@ RSpec::Core::RakeTask.new(:spec)
 
 require "standard/rake"
 
+Rake::Task["spec"].enhance do
+  sh "bundle", "exec", "rspec", "-t", "isolate", "spec/roda/delegation_error_spec.rb"
+  sh "bundle", "exec", "rspec", "-t", "isolate", "spec/roda/delegation_spec.rb"
+end
+
 task default: %i[spec standard]

data/lib/roda/phlex.rb

@@ -3,7 +3,7 @@
 class Roda
   module RodaPlugins
     module Phlex
-      VERSION = "0.2.0"
+      VERSION = "0.3.0"
     end
   end
 end

data/lib/roda/plugins/phlex.rb

@@ -17,16 +17,16 @@ class Roda
     #   layout options, and the object to be rendered. By default, it uses the
     #   `DEFAULT_LAYOUT_HANDLER`, which instantiates the layout class with the
     #   provided object and options as keyword arguments.
+    # - `:context` (+Hash+): The context that is passed to the rendering call. (default: `{}`)
     # - `:delegate`: Define if or which methods should be delegated to the Roda app:
     #     + `true` (default): Create a single `app` method that delegates to the Roda app.
     #     + `false`: Do not create any delegate methods.
-    #     + `:all`: Delegate all methods the Roda app responds to, to it. Be careful with this option.
-    #               It can lead to unexpected behavior if the Roda app has methods that conflict with Phlex methods.
-    #     + `Symbol`, `String`, `Array<Symbol,String>`: Delegate only the named methods to the Roda app.
+    #     + `Array<Symbol,String>`: Delegate the named methods to the Roda app.
+    # - `:delegate_on`: Class or module to define delegation methods on. Defaults to +::Phlex::SGML+.
+    #    + Use this option to limit delegation methods to a application specific class or module
+    #      (like "ApplicationView") to avoid polluting the global namespace.
+    # - `:delegate_name`: The name of the method that delegates to the Roda app. Defaults to `"app"`.
     module Phlex
-      Undefined = Object.new
-      private_constant :Undefined
-
       Error = Class.new(StandardError)
 
       # Custom TypeError class for Phlex errors.
@@ -53,129 +53,163 @@ class Roda
         layout_opts ? layout.new(obj, **layout_opts) : layout.new(obj)
       end
 
+      # @!visibility private
+      DELEGATE_ERROR_MESSAGE = "roda-phlex: :delegate is enabled, but :%s is to %s. Delegation will be disabled. Set :delegate to false to suppress this warning."
+      private_constant :DELEGATE_ERROR_MESSAGE
+
       # Configures the Phlex plugin for the Roda application.
       # @param app [Roda] The Roda application.
       # @param opts [Hash] The options for configuring the Phlex plugin.
       def self.configure(app, opts = OPTS)
-        delegate = opts.key?(:delegate) ? opts.delete(:delegate) : true
-        app.opts[:phlex] = opts
-        app.opts[:phlex][:layout_handler] ||= DEFAULT_LAYOUT_HANDLER
-
+        delegate = opts.fetch(:delegate, true)
         if delegate
-          overrides = Module.new do
-            def app
-              @_view_context
-            end
+          delegate_on = opts.fetch(:delegate_on) { ::Phlex::SGML }
+          delegate_name = opts.fetch(:delegate_name, "app")
 
-            case delegate
-            when :all
-              def method_missing(name, ...)
-                if app.respond_to?(name)
-                  app.send(name, ...)
-                else
-                  super
-                end
-              end
+          warn sprintf(DELEGATE_ERROR_MESSAGE, "delegate_on", delegate_on.inspect) unless delegate_on
+          warn sprintf(DELEGATE_ERROR_MESSAGE, "delegate_name", delegate_name.inspect) unless delegate_name
+        end
+
+        app.opts[:phlex] = opts.dup
+        app.opts[:phlex][:layout_handler] ||= DEFAULT_LAYOUT_HANDLER
+        app.opts[:phlex][:context] ||= {}
 
-              def respond_to_missing?(name, include_private = false)
-                app.respond_to?(name) || super
+        if delegate && delegate_on && delegate_name
+          delegate_mod = Module.new do
+            class_eval <<~RUBY, __FILE__, __LINE__ + 1
+              def #{delegate_name}
+                @_view_context
               end
+            RUBY
 
-            when Symbol, String, Array
-              Array(delegate).each do |delegate|
+            case delegate
+            when Array
+              delegate.each do |delegate|
                 class_eval <<~RUBY, __FILE__, __LINE__ + 1
                   def #{delegate}(...)
-                    app.#{delegate}(...)
+                    #{delegate_name}.#{delegate}(...)
                   end
                 RUBY
               end
             end
           end
 
-          ::Phlex::SGML.include(overrides)
+          delegate_on.include(delegate_mod)
         end
       end
 
       module InstanceMethods
-        # Retrieves or sets the layout.
-        # When no argument is provided, it returns the current layout.
-        # Use +nil+ or +false+ to disable layout.
-        #
-        # @param layout [Class, nil, false] The layout (a +Phlex::SGML+ class) to be set.
+        # Retrieves the layout class.
         # @return [Class, nil] The current layout (a +Phlex::SGML+ class) or nil if not set.
-        def phlex_layout(layout = Undefined)
-          case layout
-          when Undefined
-            opts.dig(:phlex, :layout)
-          when nil, false
-            opts[:phlex].delete(:layout)
-          else
-            if layout <= ::Phlex::SGML
-              opts[:phlex][:layout] = layout
-            else
-              raise TypeError.new(layout)
-            end
-          end
+        def phlex_layout
+          return @_phlex_layout if defined?(@_phlex_layout)
+          @_phlex_layout = opts.dig(:phlex, :layout)
         end
 
-        # Retrieves or sets the layout options.
-        # When no argument is provided, it returns the current layout options.
-        # Use +nil+ to delete layout options.
+        # Sets the layout class.
         #
-        # @note The {DEFAULT_LAYOUT_HANDLER} expects +layout_opts+ to be a +Hash+.
-        # @param layout_opts [Object, nil] The layout options to be set, usually a +Hash+.
-        # @return [Object, nil] The current layout options or nil if not set.
-        def phlex_layout_opts(layout_opts = Undefined)
-          case layout_opts
-          when Undefined
-            opts.dig(:phlex, :layout_opts)
-          when nil
-            opts[:phlex].delete(:layout_opts)
+        # @param layout [Class, nil] The layout class to be set.
+        # @return [Class, nil] The layout class that was set.
+        def set_phlex_layout(layout)
+          if !layout || layout <= ::Phlex::SGML
+            @_phlex_layout = layout
           else
-            opts[:phlex][:layout_opts] = layout_opts
+            raise TypeError.new(layout)
           end
         end
 
-        # Retrieves or sets the layout handler.
-        # When no argument is provided, it returns the current layout handler.
-        # Use +nil+ or +:default: to reset the layout handler to the {DEFAULT_LAYOUT_HANDLER}.
-        #
-        # @param handler [#call, nil, :default] The layout handler to be set.
+        # Retrieves the layout options hash.
+        # @return [Object, nil] The current layout options or nil if not set.
+        # @note Layout options set via the plugin configuration will get `dep`ed
+        #       for the current request. Be aware that this is a shallow copy and
+        #       changes to nested objects will affect the original object, that is
+        #       all subsequent requests. This is *unsafe* and should be avoided:
+        #       ```ruby
+        #       plugin :phlex, layout_opts: {key: {nested: "value"}}
+        #       # ...
+        #       # UNSAFE: Changes to phlex_layout_opts[:key] will affect the plugin config.
+        #       phlex_layout_opts[:key][:nested] = "other value"
+        #       ```
+        def phlex_layout_opts
+          return @_phlex_layout_opts if defined?(@_phlex_layout_opts)
+          @_phlex_layout_opts = opts.dig(:phlex, :layout_opts).dup
+        end
+
+        # Sets the layout options.
+        # @param layout_opts [Object, nil] The layout options to be set.
+        # @return [Object, nil] The layout options that were set.
+        # @note The {DEFAULT_LAYOUT_HANDLER} expects +layout_opts+ to be a +Hash+.
+        def set_phlex_layout_opts(layout_opts)
+          @_phlex_layout_opts = layout_opts
+        end
+
+        # Retrieves the layout handler.
         # @return [#call] The current layout handler.
-        def phlex_layout_handler(handler = Undefined)
-          case handler
-          when Undefined
-            opts.dig(:phlex, :layout_handler)
+        def phlex_layout_handler
+          return @_phlex_layout_handler if defined?(@_phlex_layout_handler)
+          @_phlex_layout_handler = opts.dig(:phlex, :layout_handler)
+        end
+
+        # Sets the layout handler.
+        # Use +nil+ or +:default: to reset the layout handler to the {DEFAULT_LAYOUT_HANDLER}.
+        def set_phlex_layout_handler(handler)
+          @_phlex_layout_handler = case handler
           when nil, :default
-            opts[:phlex][:layout_handler] = DEFAULT_LAYOUT_HANDLER
+            DEFAULT_LAYOUT_HANDLER
           else
-            opts[:phlex][:layout_handler] = handler
+            handler
           end
         end
 
+        # Retrieves the Phlex context.
+        # @return [Hash, nil] The current Phlex context.
+        def phlex_context
+          return @_phlex_context if defined?(@_phlex_context)
+          @phlex_context = opts.dig(:phlex, :context).dup
+        end
+
+        # Sets the Phlex context.
+        # @param context [Hash] The Phlex context to be set.
+        # @return [Hash] The Phlex context that was set.
+        def set_phlex_context(context)
+          @_phlex_context = context
+        end
+
         # Renders a Phlex object.
         # @param obj [Phlex::SGML] The Phlex object to be rendered.
+        # @param layout [Class, nil] The layout to be used for rendering. Defaults to the layout set by {#phlex_layout}.
+        #   - The layout class will be initialized with the object and layout options from #{phlex_layout_opts} via {#phlex_layout_handler}.
+        #   - +nil+ or +false+ will disable layout and render the +obj+ directly.
+        # @param context [Hash, nil] The Phlex context to be used for rendering. Defaults to the context set by {#phlex_context}.
         # @param content_type [String, nil] The content type of the response.
         # @param stream [Boolean] Whether to stream the response or not.
-        def phlex(obj, content_type: nil, stream: false)
+        def phlex(obj, layout: phlex_layout, context: phlex_context, content_type: nil, stream: false)
           raise TypeError.new(obj) unless obj.is_a?(::Phlex::SGML)
 
           content_type ||= "image/svg+xml" if obj.is_a?(::Phlex::SVG)
           response["Content-Type"] = content_type if content_type
 
-          phlex_opts = opts[:phlex]
-          renderer = if (layout = phlex_opts[:layout])
-            phlex_layout_handler.call(layout, phlex_opts[:layout_opts], obj)
+          renderer = if layout
+            phlex_layout_handler.call(layout, phlex_layout_opts, obj)
           else
             obj
           end
 
+          opts = {view_context: self}
+          if context
+            opts[:context] = if context.is_a?(::Phlex::Context)
+              context
+            else
+              ::Phlex::Context.new(context)
+            end
+          end
+
           if stream
             self.stream do |out|
-              renderer.call(out, view_context: self)
+              renderer.call(out, **opts)
             end
           else
-            renderer.call(view_context: self)
+            renderer.call(**opts)
           end
         end
       end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: roda-phlex
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Robert Schulze
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-12-13 00:00:00.000000000 Z
+date: 2025-01-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: phlex
@@ -17,6 +16,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.7.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -24,6 +26,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.7.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
 - !ruby/object:Gem::Dependency
   name: roda
   requirement: !ruby/object:Gem::Requirement
@@ -65,7 +70,6 @@ metadata:
   homepage_uri: https://github.com/fnordfish/roda-phlex
   source_code_uri: https://github.com/fnordfish/roda-phlex
   changelog_uri: https://github.com/fnordfish/roda-phlex/blob/main/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -80,8 +84,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.23
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: A Phlex adapter for Roda
 test_files: []