brut 0.0.20 → 0.0.22

data/lib/brut/front_end/components/inputs/select_tag_with_options.rb

@@ -0,0 +1,187 @@
+# Renders an HTML `<select>`.
+class Brut::FrontEnd::Components::Inputs::SelectTagWithOptions < Brut::FrontEnd::Components::Input
+  # Creates the appropriate select input for the given {Brut::FrontEnd::Form} and input name.
+  # Generally, you want to use this method over the initializer.
+  #
+  # @param [Brut::FrontEnd::Form} form The form that is being rendered.
+  #        This method will consult this class to understand the requirements
+  #        on this select so its HTML is generated correctly.
+  # @param [String] input_name the name of the input, which should be a member of `form`
+  # @param [Array<Object>] options An array of objects represented what is being selected.
+  #        These can be any object and are ideally whatever domain object or
+  #        data type you want on the backend to represent this selection.
+  # @param [Symbol|String] value_attribute the name of an attribute to determine an option's value.
+  #        This will be called on each element of `options` to get the value used for the `<option>`'s
+  #        `value` attribute.  The value returned by `value_attribute` should be unique amongst the
+  #        `options` provided *and* be distinct from whatever `value` is used for `include_blank`.
+  # @param [Symbol|String] option_text_attribute the name of an attribute to determine the text for an option.
+  #        This will be called on each element of `options` to get the value used for the `<option>`'s
+  #        text content.  The value returned by `option_text_attribute` need not be unique, though if it
+  #        is not unique, it will certainly be confusing.
+  # @param [Integer] index if this input is part of an array, this is the index into that array.
+  #        This is used to get the input's value.
+  # @param [Hash] html_attributes any additional HTML attributes to include on the `<select>` element.
+  # @param [false|true|Hash] include_blank configure how and if to include a blank element in the select.
+  #        If this is false, there will be no blank element. If it's `true`, there will be one with
+  #        no value or text.  If this is a `Hash` it must contain a `value:` key and a `text_content:` key
+  #        to be used as the `value` attribute and option text content, respectively.
+  #
+  # @return [Brut::FrontEnd::Components::Inputs::SelectTagWithOptions] the select input ready to be placed into a view.
+  def self.for_form_input(form:,
+                          input_name:,
+                          options:,
+                          include_blank: false,
+                          value_attribute:,
+                          option_text_attribute:,
+                          index: nil,
+                          html_attributes: {})
+    html_attributes = html_attributes.map { |key,value| [ key.to_sym, value ] }.to_h
+    default_html_attributes = {}
+    index ||= 0
+    input = form.input(input_name, index:)
+    default_html_attributes[:required] = input.required
+    if !form.new? && !input.valid?
+      default_html_attributes["data-invalid"] = true
+      input.validity_state.each do |constraint,violated|
+        if violated
+          default_html_attributes["data-#{constraint}"] = true
+        end
+      end
+    end
+    name = if input.array?
+             "#{input.name}[]"
+           else
+             input.name
+           end
+
+    Brut::FrontEnd::Components::Inputs::SelectTagWithOptions.new(
+      name: name,
+      options:,
+      selected_value: input.value,
+      value_attribute:,
+      option_text_attribute:,
+      include_blank:,
+      html_attributes: default_html_attributes.merge(html_attributes)
+    )
+  end
+
+  # Create the element.
+  #
+  # @param [String] name the name of the input
+  # @param [Array<Object>] options An array of objects represented what is being selected.
+  #        These can be any object and are ideally whatever domain object or
+  #        data type you want on the backend to represent this selection.
+  # @param [Symbol|String] value_attribute the name of an attribute to determine an option's value.
+  #        This will be called on each element of `options` to get the value used for the `<option>`'s
+  #        `value` attribute.  The value returned by `value_attribute` should be unique amongst the
+  #        `options` provided *and* be distinct from whatever `value` is used for `include_blank`.
+  # @param [String] selected_value the value of the selected option. Note that this is the *value*
+  #        of the selected option, not the selected option itself. To set the selected value
+  #        based on a selected option, omit this and use `selected_option`
+  # @param [String] selected_option the selected option. Note that `value_attribute` will be called
+  #        on this to determine the selected value to use when generating HTML. Also note that
+  #        this object must be in `options` or an exeception is raised.
+  # @param [Symbol|String] option_text_attribute the name of an attribute to determine the text for an option.
+  #        This will be called on each element of `options` to get the value used for the `<option>`'s
+  #        text content.  The value returned by `option_text_attribute` need not be unique, though if it
+  #        is not unique, it will certainly be confusing.
+  # @param [Hash] html_attributes any additional HTML attributes to include on the `<select>` element.
+  # @param [false|true|Hash] include_blank configure how and if to include a blank element in the select.
+  #        If this is false, there will be no blank element. If it's `true`, there will be one with
+  #        no value or text.  If this is a `Hash` it must contain a `value:` key and a `text_content:` key
+  #        to be used as the `value` attribute and option text content, respectively.
+  #
+  # @raise ArgumentError if `selected_option` is present, but not in `options` or if `selected_value` is
+  #        present, but no option's value for `value_attribute` is that value.
+  #
+  # XXX: Why does this not ask the form for the selected_value?
+  # XXX: This doesn't do well when values are strings
+  def initialize(name:,
+                 options:,
+                 value_attribute:,
+                 selected_value: nil,
+                 selected_option: nil,
+                 option_text_attribute:,
+                 include_blank: false,
+                 html_attributes:)
+    @options                = options
+    @include_blank          = IncludeBlank.from_param(include_blank)
+    @value_attribute        = value_attribute
+    @option_text_attribute  = option_text_attribute
+    @html_attributes        = html_attributes
+    @html_attributes[:name] = name
+
+    if selected_value.nil?
+      if selected_option.nil?
+        @selected_value = nil # explicitly nothing is selected
+      else
+        option = options.detect { |option|
+          option.send(@value_attribute) == selected_option.send(@value_attribute)
+        }
+        if option.nil?
+          raise ArgumentError, "selected_option #{selected_option} (with #{value_attribute} '#{selected_option.send(value_attribute)}') was not found in options"
+        end
+        @selected_value = option.send(@value_attribute)
+      end
+    else
+      if selected_value.kind_of?(Array)
+        raise "WTF: #{name}"
+      end
+      option = options.detect { |option|
+        selected_value == option.send(@value_attribute)
+      }
+      if option.nil?
+        raise ArgumentError, "selected_value #{selected_value} was not the value for #{value_attribute} on any of the options: #{options.map { |option| option.send(value_attribute) }.join(', ')}"
+      end
+      @selected_value = option.send(@value_attribute)
+    end
+  end
+
+  def view_template
+    select(**@html_attributes) {
+      if @include_blank
+        option(**@include_blank.option_attributes) {
+          @include_blank.text_content
+        }
+      end
+      options = @options.each do |option|
+        value = option.send(@value_attribute)
+        option_attributes = { value: value }
+        if value == @selected_value
+          option_attributes[:selected] = true
+        end
+        option(**option_attributes) {
+          option.send(@option_text_attribute)
+        }
+      end
+    }
+  end
+private
+
+  # @!visibility private
+  class IncludeBlank
+    attr_reader :text_content, :option_attributes
+    def self.from_param(include_blank)
+      if !include_blank
+        return nil
+      else
+        self.new(include_blank)
+      end
+    end
+    def initialize(include_blank)
+      if include_blank == true
+        @text_content = ""
+        @option_attributes = {}
+      elsif include_blank.kind_of?(Hash)
+        if include_blank.key?(:value) && include_blank.key?(:text_content)
+          @text_content = include_blank[:text_content]
+          @option_attributes = { value: include_blank[:value] }
+        else
+          raise ArgumentError, "when include_blank: is a Hash, it must include both :value and :text_content as keys. Got: #{include_blank.keys.join(", ")}"
+        end
+      else
+        raise ArgumentError,"include_blank: was a #{include_blank.class}. It should be true, false, nil, or a Hash"
+      end
+    end
+  end
+end

data/lib/brut/front_end/components/inputs/{textarea.rb → textarea_tag.rb}

@@ -1,5 +1,5 @@
 # Generates an HTML `<textarea>` field.
-class Brut::FrontEnd::Components::Inputs::Textarea < Brut::FrontEnd::Components::Input
+class Brut::FrontEnd::Components::Inputs::TextareaTag < Brut::FrontEnd::Components::Input
   # Creates the appropriate textarea for the given {Brut::FrontEnd::Form} and input name.
   # Generally, you want to use this method over the initializer.
   #
@@ -35,7 +35,7 @@ class Brut::FrontEnd::Components::Inputs::Textarea < Brut::FrontEnd::Components:
       end
     end
     value = input.value
-    Brut::FrontEnd::Components::Inputs::Textarea.new(default_html_attributes.merge(html_attributes), value)
+    Brut::FrontEnd::Components::Inputs::TextareaTag.new(default_html_attributes.merge(html_attributes), value)
   end
   # Create an instance
   #

data/lib/brut/front_end/components/time_tag.rb

@@ -1,4 +1,5 @@
-# Renders a date or timestamp accessibly, using the `<time>` element. Likely you will use this via the {Brut::FrontEnd::Component::Helpers#time_tag} method. This will account for the current request's time zone. See {Clock}.
+# Renders a date or timestamp accessibly, using the `<time>` element.
+# This will account for the current request's time zone. See {Clock}.
 class Brut::FrontEnd::Components::TimeTag < Brut::FrontEnd::Component
   include Brut::I18n::ForHTML
   # Creates the component

data/lib/brut/front_end/form.rb

@@ -68,12 +68,12 @@ class Brut::FrontEnd::Form
     @inputs = self.class.input_definitions.map { |name,input_definition|
       value = @params[name] || @params[name.to_sym]
       inputs = if value.kind_of?(Array)
-                 value.map { |one_value|
-                   input_definition.make_input(value: one_value)
+                 value.map.with_index { |one_value, index|
+                   input_definition.make_input(value: one_value, index:)
                  }
                else
                  [
-                   input_definition.make_input(value:)
+                   input_definition.make_input(value:, index: nil)
                  ]
                end
 
@@ -98,7 +98,7 @@ class Brut::FrontEnd::Form
     input = inputs[index]
     if input.nil?
       input_definition = self.class.input_definitions.fetch(input_name.to_s)
-      input = input_definition.make_input(value:"")
+      input = input_definition.make_input(value:"", index:)
       inputs[index] = input
     end
     input

data/lib/brut/front_end/forms/input.rb

@@ -13,9 +13,10 @@ class Brut::FrontEnd::Forms::Input
   # Create the input with the given definition and value
   # @param [Brut::FrontEnd::Forms::InputDefinition] input_definition
   # @param [String] value
-  def initialize(input_definition:, value:)
+  def initialize(input_definition:, value:, index:)
     @input_definition = input_definition
     @validity_state = Brut::FrontEnd::Forms::ValidityState.new
+    @index = index
     self.value=(value)
   end
 

data/lib/brut/front_end/forms/input_definition.rb

@@ -109,7 +109,10 @@ class Brut::FrontEnd::Forms::InputDefinition
 
 
   # Create an Input based on this definition, initializing it with the given value.
-  def make_input(value:)
-    Brut::FrontEnd::Forms::Input.new(input_definition: self, value: value)
+  # @param [String] value the value to give this input initially.
+  # @param [Integer] index the index of this input, if it is part of an array of
+  # inputs. `nil` is allowed only if the input definition is not for an array.
+  def make_input(value:, index:)
+    Brut::FrontEnd::Forms::Input.new(input_definition: self, value:, index:)
   end
 end

data/lib/brut/front_end/forms/radio_button_group_input.rb

@@ -8,9 +8,10 @@ class Brut::FrontEnd::Forms::RadioButtonGroupInput
   attr_reader :validity_state
 
   # (see Brut::FrontEnd::Forms::Input#initialize)
-  def initialize(input_definition:, value:)
+  def initialize(input_definition:, value:, index:)
     @input_definition = input_definition
     @validity_state = Brut::FrontEnd::Forms::ValidityState.new
+    @index = index
     if input_definition.array?
       value ||= []
     end

data/lib/brut/front_end/forms/radio_button_group_input_definition.rb

@@ -23,7 +23,7 @@ class Brut::FrontEnd::Forms::RadioButtonGroupInputDefinition
   def array? = @array
 
   # Create an Input based on this defitition, initializing it with the given value.
-  def make_input(value:)
-    Brut::FrontEnd::Forms::RadioButtonGroupInput.new(input_definition: self, value: value)
+  def make_input(value:, index:)
+    Brut::FrontEnd::Forms::RadioButtonGroupInput.new(input_definition: self, value:, index:)
   end
 end

data/lib/brut/front_end/forms/select_input.rb

@@ -9,12 +9,10 @@ class Brut::FrontEnd::Forms::SelectInput
   attr_reader :validity_state
 
   # (see Brut::FrontEnd::Forms::Input#initialize)
-  def initialize(input_definition:, value:)
+  def initialize(input_definition:, value:, index:)
     @input_definition = input_definition
     @validity_state = Brut::FrontEnd::Forms::ValidityState.new
-    if input_definition.array?
-      value ||= []
-    end
+    @index = index
     self.value=(value)
   end
 

data/lib/brut/front_end/forms/select_input_definition.rb

@@ -21,7 +21,7 @@ class Brut::FrontEnd::Forms::SelectInputDefinition
   def array? = @array
 
   # Create an Input based on this defitition, initializing it with the given value.
-  def make_input(value:)
-    Brut::FrontEnd::Forms::SelectInput.new(input_definition: self, value: value)
+  def make_input(value:, index:)
+    Brut::FrontEnd::Forms::SelectInput.new(input_definition: self, value:, index:)
   end
 end

data/lib/brut/front_end/handler.rb

@@ -1,12 +1,24 @@
 module Brut::FrontEnd
-  # A handler responds to all HTTP requests other than those that render a page. It will be given any data it needs
-  # to handle the request to its {#handle} method, which you must implement. 
-  # You define this method to accept the parameters you expect. See {Brut::FrontEnd::RequestContext} for how that works.
+  # A handler responds to all HTTP requests other than those that render a page.
+  # Like a page, the handler is initialized with any of the data it needs.  The {#handle} method will
+  # be called to perform whatever action is needed, and its return value will determine what
+  # ther esponse will be.
   #
-  # You may also define `before_handle` which will be given any subset of those parameters and can perform logic before
-  # handle is called.  This is most useful in a base class to check for permissions or other cross-cutting concerns.
+  # To create a handler, after defining a route or form,
+  # subclass this class (or, more likely, your app's `AppHandler`) and
+  # provide an initializer that accepts keyword arguments.  The names of these arguments will be used
+  # to locate the values that Brut will pass in when creating your page object. If your handler
+  # is for a form, be sure to include the `form:` keyword argument.
   #
-  # The primary method of this class is {#handle!} which you should not override, but *should* call in a test.
+  # Consult Brut's documentation on keyword injection to know what values you may use and how values are located.
+  #
+  # Then, implement {#handle} to perform whatever logic is needed to handle the request.
+  #
+  # You may also define `before_handle` which will be called before {#handle} to potentially abort
+  # the request.  This is mostly useful if you have a base class for some of your handlers and want to
+  # share cross-cutting logic.
+  #
+  # Note that the public API for handlers is {#handle!}, which is what you should call in a test.
   class Handler
     include Brut::FrontEnd::HandlingResults
     include Brut::Framework::Errors
@@ -27,32 +39,22 @@ module Brut::FrontEnd
       abstract_method!
     end
 
+    # Override this to performa any checks before {#handle} is called.  This should
+    # return `nil` if {#handle} should proceed to be called. Generally, you don't need to override
+    # this as {#handle} can include the logic.  Where this is useful is to share cross-cutting logic
+    # across other handlers.
+    #
+    # @return [URI|Brut::FrontEnd::Component,Array,Brut::FrontEnd::HttpStatus,Brut::FrontEnd::Download] See
+    #         {#handle} for what each return value means.
+    def before_handle = nil
+
     # Called by Brut to handle the request. Do not override this. If your handler responds to `before_handle` that is called with the
     # same args as you have defined for {#handle}. If `before_handle` returns anything other than `nil`, that value is returned and
     # should be one of the values documented in {#handle}.  If `before_handle` returns `nil`, {#handle} is called and whatever it
     # returns is returned here.
     def handle!(**args)
       result = nil
-      if self.respond_to?(:before_handle)
-        before_handle_args = self.method(:before_handle).parameters.map { |(type,name)|
-          if type == :keyreq
-            if args.key?(name)
-              [ name, args[name] ]
-            else
-              raise ArgumentError,"before_handle requires keyword arg '#{name}' but `handle` did not receive it. It must"
-            end
-          elsif type == :key
-            if args.key?(name)
-              [ name, args[name] ]
-            else
-              nil
-            end
-          else
-            raise ArgumentError,"before_handle must only have keyword args. Got '#{name}' of type '#{type}'"
-          end
-        }.compact.to_h
-        result = self.before_handle(**before_handle_args)
-      end
+      result = self.before_handle
       if result.nil?
         result = self.handle(**args)
       end

data/lib/brut/front_end/handlers/csp_reporting_handler.rb

@@ -1,9 +1,12 @@
 # Receives content security policy violations and logs them. This is set up in {Brut::Framework::MCP}, however CSP reporting is
 # configured in {Brut::FrontEnd::RouteHooks::CSPNoInlineStylesOrScripts::ReportOnly}.
 class Brut::FrontEnd::Handlers::CspReportingHandler < Brut::FrontEnd::Handler
-  def handle(body:)
+  def initialize(body:)
+    @body = body
+  end
+  def handle
     begin
-      parsed = JSON.parse(body.read)
+      parsed = JSON.parse(@body.read)
       Brut.container.instrumentation.add_attributes(parsed.merge(prefix: "brut.csp-reporting"))
     rescue => ex
       Brut.container.instrumentation.record_exception(ex)

data/lib/brut/front_end/handlers/instrumentation_handler.rb

@@ -65,12 +65,16 @@ class Brut::FrontEnd::Handlers::InstrumentationHandler < Brut::FrontEnd::Handler
     def as_carrier = { "traceparent" => @value }
   end
 
-  def handle(http_tracestate:, http_traceparent:)
-    traceparent = TraceParent.from_header(http_traceparent)
-    span        = Span.from_header(http_tracestate)
+  def initialize(http_tracestate:, http_traceparent:)
+    @http_tracestate  = http_tracestate
+    @http_traceparent = http_traceparent
+  end
+  def handle
+    traceparent = TraceParent.from_header(@http_traceparent)
+    span        = Span.from_header(@http_tracestate)
 
     if span.nil? || traceparent.nil?
-      SemanticLogger[self.class].info "Missing traceparent or span: #{http_tracestate}, #{http_traceparent}"
+      SemanticLogger[self.class].info "Missing traceparent or span: #{@http_tracestate}, #{@http_traceparent}"
       return http_status(400)
     end
 

data/lib/brut/front_end/handlers/locale_detection_handler.rb

@@ -5,9 +5,13 @@
 # {Brut::FrontEnd::Session#http_accept_language=} *only* if the `Accept-Language` header did not provide a value that is supported by
 # the app.
 class Brut::FrontEnd::Handlers::LocaleDetectionHandler < Brut::FrontEnd::Handler
-  def handle(body:,session:)
+  def initialize(body:,session:)
+    @body    = body
+    @session = session
+  end
+  def handle
     begin
-      parsed = JSON.parse(body.read)
+      parsed = JSON.parse(@body.read)
 
       Brut.container.instrumentation.add_attributes(
         prefix: "brut.locale-detection",
@@ -19,9 +23,9 @@ class Brut::FrontEnd::Handlers::LocaleDetectionHandler < Brut::FrontEnd::Handler
         locale   = parsed["locale"]
         timezone = parsed["timeZone"]
 
-        session.timezone_from_browser = timezone
-        if !session.http_accept_language.known?
-          session.http_accept_language = Brut::I18n::HTTPAcceptLanguage.from_browser(locale)
+        @session.timezone_from_browser = timezone
+        if !@session.http_accept_language.known?
+          @session.http_accept_language = Brut::I18n::HTTPAcceptLanguage.from_browser(locale)
         end
       end
     rescue => ex

data/lib/brut/front_end/handlers/missing_handler.rb

@@ -1,7 +1,10 @@
 # Used in development to handle a defined route but a missing page. This arranges to render a nicer error page than the default.
 class Brut::FrontEnd::Handlers::MissingHandler < Brut::FrontEnd::Handler
-  def handle(route:)
-    Brut::FrontEnd::Pages::MissingPage.new(route:)
+  def initialize(route:)
+    @route = route
+  end
+  def handle
+    Brut::FrontEnd::Pages::MissingPage.new(route: @route)
   end
 
   class Form < Brut::FrontEnd::Form

data/lib/brut/front_end/layout.rb

@@ -1,3 +1,19 @@
+# A layout is common HTML that surrounds different pages. For example, it would hold your 
+# DOCTYPE, `<head>`, and possibly any common `<body>` elements that every page needs. 
+#
+# A layout is a Phlex component but it must contain a call to `yield` somewhere in the 
+# implementation of `view_template`.
+#
+# This base class contains helper methods needed for implementing a layout.
 class Brut::FrontEnd::Layout < Brut::FrontEnd::Component
+  # Get the actual path of an asset managed by Brut. This handles
+  # locating the asset's URL as well as ensuring the hash is properly
+  # inserted into the filename.
+  #
+  # @param [String] path the path to an asset, such as `/css/styles.css`.
+  #
+  # @return [String] the actual path to the current version of that asset.
+  #
+  # @see Brut::FrontEnd::AssetPathResolver
   def asset_path(path) = Brut.container.asset_path_resolver.resolve(path)
 end

data/lib/brut/front_end/page.rb

@@ -1,48 +1,46 @@
-# A page backs a web page.  A page renders everything in the browser window.  Technically, it is exactly like a component except that
-# it can have a layout.
+# A Page backs a web page, which handles rendering everything in a browser window when a URL is requested.
+# Technically, a page is identical to a {Brut::FrontEnd::Component}, except that a page has a layout.
+# A {Brut::FrontEnd::Layout} is common HTML that surrounds your page's HTML.
+# Your page is a Phlex component, but instead of implementing `view_template`, you
+# implement {#page_template} to ensure the layout is used.
 #
-# When subclassing this to create a page, your initializer's signature will determine what data
-# is required for your page to work.  It can be anything, just keep in mind that any component your page uses may
-# require additional data.
+# To create a page, after defining a route, subclass this class (or, more likely, your app's `AppPage`) and
+# provide an initializer that accepts keyword arguments.  The names of these arguments will be used to locate the
+# values that Brut will pass in when creating your page object.
 #
-# If your page does not override {#render} (which, generally, it won't), an ERB file is expected to exist alongside it in the
-# app.  For example, if you have a page named `Auth::LoginPage`, it would expected to be in
-# `app/src/front_end/pages/auth/login_page.rb`.  Thus, Brut will also expect
-# `app/src/front_end/pages/auth/login_page.html.erb` to exist as well. That ERB file is used with an instance of your
-# pages's class to render the page's HTML.
+# Consult Brut's documentation on keyword injection to know what values you may use and how values are located.
 #
 # @see Brut::FrontEnd::Component
+# @see Brut::FrontEnd::Layout
 class Brut::FrontEnd::Page < Brut::FrontEnd::Component
   include Brut::FrontEnd::HandlingResults
 
-  # Returns the name of the layout for this page.  This string is used to find an ERB file in `app/src/front_end/layouts`. Every page
-  # must have a layout. If you wish to render a page with no layout, create an empty layout in your app and use that.
+  # Returns the name of the layout for this page.  This string is used to find a class named
+  # `«camelized-layout»Layout` in your app.  The default value is "default", meaning that the class
+  # `DefaultLayout` will be used.
   #
-  # Note that the layout can be dynamic. It is requested when {#render} is called, so you can override this
+  # Note that the layout can be dynamic. It is requested when {#page_template} is called, so you can override this
   # method and use any ivar set in your constructor to change what layout is used.
   #
+  # If your page does not need a layout, you have two options:
+  #
+  # * Create your own blank layout named, e.g. `BlankLayout` and have this method return `"blank"`.
+  # * Implement `view_template` instead of `page_template`, thus overriding this class' implementation that uses
+  #   layouts.
+  #
   # @return [String] The name of the layout. May not be `nil`.
   def layout = "default"
 
-  # Called after the page is created, but before {#render} is called.  This allows you to do any pre-flight checks and potentially
+  # Called after the page is created, but before {#page_template} is called.  This allows you to do any pre-flight checks and potentially
   # redirect the user or produce an error.
   #
-  # @return [URI|Brut::FrontEnd::HttpStatus|Object] If you return a `URI` (mostly likely by returning the result of calling {Brut::FrontEnd::HandlingResults#redirect_to}), the user is redirected and {#render} is never called. If you return a {Brut::FrontEnd::HttpStatus} (mostly likely by returning the result of calling {Brut::FrontEnd::HandlingResults#http_status}), {#render} is skipped and that status is returned with no content.  If anything else is returned, {#render} is called as normal.
-  def before_render = nil
-
-  def with_layout(&block)
-    layout_class = Module.const_get(
-      layout_class = RichString.new([
-        self.layout,
-        "layout"
-      ].join("_")).camelize
-    )
-    render layout_class.new(page_name:,&block)
-  end
-
+  # @return [URI|Brut::FrontEnd::HttpStatus|Object] If you return a `URI` (mostly likely by returning the result of calling {Brut::FrontEnd::HandlingResults#redirect_to}), the user is redirected and no HTML is generated. If you return a {Brut::FrontEnd::HttpStatus} (mostly likely by returning the result of calling {Brut::FrontEnd::HandlingResults#http_status}), HTML generation is skipped and that status is returned with no content.  If anything else is returned, HTML is generated normal.
+  def before_generate = nil
 
+  # Core method of this class. Do not override. This handles the use of {#before_generate} and is what Brut
+  # calls to possibly render the page.
   def handle!
-    case before_render
+    case before_generate
     in URI => uri
       uri
     in Brut::FrontEnd::HttpStatus => http_status
@@ -52,6 +50,15 @@ class Brut::FrontEnd::Page < Brut::FrontEnd::Component
     end
   end
 
+  # Override this method to produce your page's HTML. You are intended to call Phlex
+  # methods here. Anything you can do inside the Phlex-standard `view_template` method, you can 
+  # do here. The only difference is that this will all be rendered in the context of your configured
+  # {#layout}.
+  def page_template = abstract_method!
+
+  # Phlex's API to produce markup. Do not override this or you will lose your layout.
+  # This implementation locates the configured layout, renders it, and renders {#page_template}
+  # inside.
   def view_template
     with_layout do
       page_template
@@ -65,8 +72,24 @@ class Brut::FrontEnd::Page < Brut::FrontEnd::Component
   # Convienience method for {.page_name}.
   def page_name = self.class.page_name
 
+private
+
+  # Locates the layout class and uses it to render itself, along
+  # with the block given.
+  #
   # @!visibility private
-  def component_name = raise Brut::Framework::Errors::Bug,"#{self.class} is not a component"
+  def with_layout(&block)
+    layout_class = Module.const_get(
+      layout_class = RichString.new([
+        self.layout,
+        "layout"
+      ].join("_")).camelize
+    )
+    Brut.container.instrumentation.add_prefixed_attributes("brut", layout_class: layout_class)
+    render layout_class.new(page_name:,&block)
+  end
+
+
 
 end
 

data/lib/brut/front_end/request_context.rb

@@ -112,12 +112,13 @@ class Brut::FrontEnd::RequestContext
   # @param [Class] klass a class that is to be instantiated entirely by the contents of this `RequestContext`.
   # @param [Hash] request_params Query string parameters provided by Rack.
   # @param [Brut::FrontEnd::Routing::Route] route the route that triggered the request.
+  # @param [Brut::FrontEnd::Form] form the form, if available
   # @return [Hash] can be splatted to keyword arguments and passed to the constructor of `klass`
   #
   # @raise [ArgumentError] if the constructor has any non-keyword arguments, or if any required keyword argument is
   #                        not present in this `RequestContext`.
-  def as_constructor_args(klass, request_params:, route:nil)
-    args_for_method(method: klass.instance_method(:initialize), request_params:, form: nil, route:)
+  def as_constructor_args(klass, request_params:, route:nil, form: nil)
+    args_for_method(method: klass.instance_method(:initialize), request_params:, form: , route:)
   end
 
   # Based on `object`' method, returns a Hash that maps all keywords it requires to the values stored in this

data/lib/brut/front_end/routing.rb

@@ -218,7 +218,11 @@ private
         joined_path = joined_path + "#" + URI.encode_uri_component(anchor)
       end
       uri = URI(joined_path)
-      uri.query = URI.encode_www_form(query_string_params)
+      query_string = URI.encode_www_form(query_string_params)
+      if query_string.to_s.strip != ""
+        uri.query = query_string
+      end
+
       uri.extend(Phlex::SGML::SafeObject)
     end