roda-phlex 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 697b0c167a1b8e7c0a878d07a7b45c69e8ce1ea4ec7d04a8a2a1743df8856d63
-  data.tar.gz: 0ef55428df093f8e8d61106b7819bf822fea490228e58c7c921ecf8e4d54aed6
+  metadata.gz: d4325bf47a07f07abf3c30722c16bcd2422559e3ae8ef3af32803efe081d640c
+  data.tar.gz: fe31c12b510c61204b61996b6f22a696a8e82ba1f6a491ffe399c71e30bae365
 SHA512:
-  metadata.gz: 6789258cef5d8ed114bc9cf5322b3440eb5b01122a8d046f09f30fe0382ee3b2eb7a2f055089c25cbce2d351d4b7da1041691e5c03a272c439b4fd41ad8440c7
-  data.tar.gz: c98632f1b504f435755b410dfcf0a5c7cc61b2f8fd9e59048bcde01966b01749b04a8aef1c4557a3f50e38911580e014a3869fe2a41408b2516e76ac55007ccf
+  metadata.gz: 3174f3c8d94c44d3876a51fe5f5d531f3feee7e5143d0b98a43e6978537f1b4e070c260f73421fb5bd04e9d8619e83067ab34eef073c7f91836d3c9a2e94df32
+  data.tar.gz: c6eb86db087726ee22f7cf2d0df7c140c34433606279675bd56c26158b361c9b0b34f8369eb9a390c04193b5b5c8e17e6591bb599553a1ffef06499be901baf3

data/.markdownlint.yml

@@ -0,0 +1,10 @@
+MD004: # Unordered list style
+  style: sublist
+MD007: # Unordered list indentation
+  indent: 4 # For Yard
+MD013: # Line length
+  line_length: 120
+  code_blocks: false
+  tables: false
+MD024: # Multiple headers with the same content
+  siblings_only: true

data/.yardopts

@@ -0,0 +1,2 @@
+-m markdown
+--files LICENSE.txt,CHANGELOG.md

data/CHANGELOG.md

@@ -1,5 +1,62 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+
 ## [Unreleased]
 
+### Added
+
+### Changed
+
+### Deprecated
+
+### Removed
+
+### Fixed
+
+### Security
+
+## [0.2.0] - 2024-12-13
+
+### Added
+
+- Allow `phlex_layout(false)` to be used to reset disable layout.
+- Allow `phlex_layout_handler(:default)` to be used to reset to the default layout handler.
+
+### Removed
+
+- Don't delete layout options when deleting layout (eg via `phlex_layout(false)`)
+
+### Fixed
+
+- `phlex_layout` should accept a `Phlex::SGML` class, not instance.
+- `phlex_layout_handler` called with `nil` resets it to the default handler.
+
 ## [0.1.0] - 2024-08-28
 
-- Initial release based on <https://github.com/benpickles/phlex-sinatra/commit/2e3c9a612cbf6f4b4bf5db880f164b66f008baf8> and <https://gist.github.com/RomanTurner/0ce0b8792e4149d152d2af2224cb6407>
+- Initial release based on <https://github.com/benpickles/phlex-sinatra/commit/2e3c9a612cbf6f4b4bf5db880f164b66f008baf8>
+  and <https://gist.github.com/RomanTurner/0ce0b8792e4149d152d2af2224cb6407>
+
+________________________________________________________________________________
+
+[Unreleased]: https://github.com/fnordfish/roda-phlex/compare/v0.2.0...main
+[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
+
+<!-- template for new release:
+### Added
+
+### Changed
+
+### Deprecated
+
+### Removed
+
+### Fixed
+
+### Security
+
+## [X.Y.Z] - YYYY-MM-DD
+-->

data/README.md

@@ -1,8 +1,11 @@
 # roda-phlex
 
-A [Roda](https://github.com/jeremyevans/roda) plugin that adds some convenience rendering [Phlex](https://github.com/phlex-ruby/phlex) views.  
+A [Roda](https://github.com/jeremyevans/roda) plugin that adds some convenience rendering
+[Phlex](https://github.com/phlex-ruby/phlex) views.  
 Especially accessing application methods from the view.
 
+* API documentation is available at [https://www.rubydoc.info/gems/roda-phlex](https://www.rubydoc.info/gems/roda-phlex/Roda/RodaPlugins/Phlex/InstanceMethods)
+
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:
@@ -21,23 +24,23 @@ gem install roda-phlex
 
 `plugin :phlex` takes the following options:
 
-- `:layout` (`Phlex::SGML`): Specifies the layout class to be used for rendering
+* `:layout` (`Phlex::SGML`): Specifies the layout class to be used for rendering
   views. This class should be a Phlex layout class that defines how the
   views are structured and rendered.
-- `:layout_opts` (`Object`): Options that are passed to the layout
+* `: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`.
-- `:layout_handler` (`#call`): A custom handler for creating layout
+* `: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 uses 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.
-- `: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`: Delegate only the specified methods to the Roda app.
+* `: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.
 
 ## Usage
 
@@ -86,7 +89,8 @@ end
 
 ## Streaming
 
-Streaming a Phlex view can be enabled by passing `stream: true` which will cause Phlex to automatically write to the response after the closing `</head>` and buffer the remaining content.  
+Streaming a Phlex view can be enabled by passing `stream: true` which will cause Phlex to automatically write
+to the response after the closing `</head>` and buffer the remaining content.  
 The Roda `:stream` plugin must be enabled for this to work.
 
 ```ruby
@@ -101,7 +105,7 @@ You can also manually flush the contents of the buffer at any point using Phlex'
 
 ```ruby
 class Layout < Phlex::HTML
-  def template(&block)
+  def view_template(&block)
     doctype
     html {
       head {
@@ -120,7 +124,7 @@ class Layout < Phlex::HTML
 end
 
 class MyView < Phlex::HTML
-  def template
+  def view_template
     render Layout.new {
       # Knowing that this page can take a while to generate we can choose to
       # flush here so the browser can render the site header while downloading
@@ -156,7 +160,9 @@ end
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at <https://github.com/fnordfish/roda-phlex>. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/fnordfish/roda-phlex/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at <https://github.com/fnordfish/roda-phlex>.
+This project is intended to be a safe, welcoming space for collaboration, and contributors are expected
+to adhere to the [code of conduct](https://github.com/fnordfish/roda-phlex/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -164,8 +170,10 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Roda::Phlex project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/fnordfish/roda-phlex/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the Roda::Phlex project's codebases, issue trackers, chat rooms and mailing lists is expected
+to follow the [code of conduct](https://github.com/fnordfish/roda-phlex/blob/main/CODE_OF_CONDUCT.md).
 
 ## Acknowledgements
 
-This gem is based on [phlex-sinatra](https://github.com/benpickles/phlex-sinatra), and extended by the layout handling features in [RomanTurner's gist](https://gist.github.com/RomanTurner/0ce0b8792e4149d152d2af2224cb6407)
+This gem is based on [phlex-sinatra](https://github.com/benpickles/phlex-sinatra), and extended by the layout handling
+features in [RomanTurner's gist](https://gist.github.com/RomanTurner/0ce0b8792e4149d152d2af2224cb6407)

data/lib/roda/phlex.rb

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

data/lib/roda/plugins/phlex.rb

@@ -18,11 +18,11 @@ class Roda
     #   `DEFAULT_LAYOUT_HANDLER`, which instantiates the layout class with the
     #   provided object and options as keyword arguments.
     # - `: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`: Delegate only the specified methods 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.
     module Phlex
       Undefined = Object.new
       private_constant :Undefined
@@ -44,6 +44,11 @@ class Roda
 
       # The default layout handler for creating layout instances.
       # Expects layout options to be a +Hash+ when provided.
+      # Layout options are passed as keyword arguments to the layout class.
+      #
+      # @param layout [Class] The layout class to be instantiated.
+      # @param layout_opts [Hash, nil] The layout options to be passed to the layout class.
+      # @param obj [Phlex::SGML] The object to be rendered.
       DEFAULT_LAYOUT_HANDLER = proc do |layout, layout_opts, obj|
         layout_opts ? layout.new(obj, **layout_opts) : layout.new(obj)
       end
@@ -93,24 +98,32 @@ class Roda
 
       module InstanceMethods
         # Retrieves or sets the layout.
-        # @param layout [Phlex::SGML, Undefined, nil] The layout to be set.
-        # @return [Phlex::SGML, nil] The current layout or nil if not set.
+        # 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.
+        # @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
+          when nil, false
             opts[:phlex].delete(:layout)
-            opts[:phlex].delete(:layout_opts)
-          when ::Phlex::SGML
-            opts[:phlex][:layout] = layout
           else
-            raise TypeError.new(layout)
+            if layout <= ::Phlex::SGML
+              opts[:phlex][:layout] = layout
+            else
+              raise TypeError.new(layout)
+            end
           end
         end
 
         # Retrieves or sets the layout options.
-        # @param layout_opts [Undefined, nil] The layout options to be set.
+        # When no argument is provided, it returns the current layout options.
+        # Use +nil+ to delete layout options.
+        #
+        # @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
@@ -124,14 +137,17 @@ class Roda
         end
 
         # Retrieves or sets the layout handler.
-        # @param handler [#call, Undefined, nil] The layout handler to be set.
-        # @return [#call, nil] The current layout handler or nil if not set.
+        # 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.
+        # @return [#call] The current layout handler.
         def phlex_layout_handler(handler = Undefined)
           case handler
           when Undefined
             opts.dig(:phlex, :layout_handler)
-          when nil
-            opts[:phlex].delete(:layout_handler)
+          when nil, :default
+            opts[:phlex][:layout_handler] = DEFAULT_LAYOUT_HANDLER
           else
             opts[:phlex][:layout_handler] = handler
           end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: roda-phlex
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Robert Schulze
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-08-28 00:00:00.000000000 Z
+date: 2024-12-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: phlex
@@ -47,8 +47,10 @@ extra_rdoc_files: []
 files:
 - ".devcontainer/Gemfile"
 - ".devcontainer/devcontainer.json"
+- ".markdownlint.yml"
 - ".rspec"
 - ".standard.yml"
+- ".yardopts"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
@@ -78,7 +80,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.17
+rubygems_version: 3.5.23
 signing_key:
 specification_version: 4
 summary: A Phlex adapter for Roda