crossingtheruby.com

HTML Parsley with Herb

2025-04-20T00:00:00+00:00

Herb, the new HTML-aware ERB parser library by Marco Roth, parses ERB templates into an abstract syntax tree. The tree has two main branches:

HTML
Embedded Ruby

In the real world these are extricably (thanks Herb!) intertwined but for now I’d like to concentrate on the HTML tree structure that the Herb AST uses.

Herb AST Node Types

The docs on Herb’s Parser are quite, ahem, sparse, so I had to do some introspection to arrive at a list of nodes in the tree:

require "herb"

Herb.version
#=> "herb gem v0.1.0, libprism v1.4.0, libherb v0.1.0 (Ruby C native extension)"

constants = Herb::AST.constants.map do |const|
  klass = Herb::AST.const_get(const)
  next unless klass.is_a?(Class)
  klass.name
end.compact.each do |klass|
  puts klass
end; constants.count

This produces a list of Herb::AST::Nodes, which after a touch of light editing to order and group the twenty-eight nodes, looks like this:

Herb::AST::Node
Herb::AST::DocumentNode

Herb::AST::HTMLDoctypeNode
Herb::AST::HTMLCommentNode
Herb::AST::HTMLElementNode
Herb::AST::HTMLOpenTagNode
Herb::AST::HTMLAttributeNode
Herb::AST::HTMLAttributeNameNode
Herb::AST::HTMLAttributeValueNode
Herb::AST::LiteralNode
Herb::AST::HTMLTextNode
Herb::AST::HTMLCloseTagNode
Herb::AST::HTMLSelfCloseTagNode

Herb::AST::WhitespaceNode

Herb::AST::ERBContentNode
Herb::AST::ERBIfNode
Herb::AST::ERBUnlessNode
Herb::AST::ERBElseNode
Herb::AST::ERBBlockNode
Herb::AST::ERBCaseNode
Herb::AST::ERBWhenNode
Herb::AST::ERBForNode
Herb::AST::ERBWhileNode
Herb::AST::ERBUntilNode
Herb::AST::ERBBeginNode
Herb::AST::ERBRescueNode
Herb::AST::ERBEnsureNode
Herb::AST::ERBEndNode

The two groups are distinguished here, with the exception of the mutual parents (DocumentNode—parent (or root) of the syntax tree, Node—parent of the class hierarchy) and the shared WhitespaceNode rather appropriately surrounded by, em, whitespace.

Parsing HTML

`Herb::AST::DocumentNode`

The ever-present root.

Herb.parse("").value
=> 
@ DocumentNode (location: (1:0)-(1:0))
└── children: []

Contains an array of child nodes in DocumentNode#children.

`Herb::AST::HTMLDoctypeNode`

The singular doctype declaration. Also note the Herb::AST::LiteralNode, a node representing some literal text (as distinct from HTML text) usually inside an HTML doctype, HTML comment, or HTML attribute value.

Herb.parse("<!doctype html>").value
=> 
@ DocumentNode (location: (1:0)-(1:15))
└── children: (1 item)
    └── @ HTMLDoctypeNode (location: (1:0)-(1:15))
        ├── tag_opening: "<!doctype" (location: (1:0)-(1:9))
        ├── children: (1 item)
        │   └── @ LiteralNode (location: (1:9)-(1:14))
        │       └── content: " html"
        │
        └── tag_closing: ">" (location: (1:14)-(1:15))

`Herb::AST::HTMLCommentNode`

The humble HTML comment.

Herb.parse("<!-- comment -->").value
=> 
@ DocumentNode (location: (1:0)-(1:16))
└── children: (1 item)
    └── @ HTMLCommentNode (location: (1:0)-(1:16))
        ├── comment_start: "<!--" (location: (1:0)-(1:4))
        ├── children: (1 item)
        │   └── @ LiteralNode (location: (1:4)-(1:13))
        │       └── content: " comment "
        │
        └── comment_end: "-->" (location: (1:13)-(1:16))

`Herb::AST::HTMLElementNode`

The HTMLElementNode captures the full element from opening tag to closing tag, including the contents (body). Each of these are represented by a dedicated node:

HTMLElementNode#open_tag => HTMLOpenTagNode
HTMLElementNode#body => [HTMLTextNode, …] (array of child nodes)
HTMLElementNode#close_tag => HTMLCloseTagNode

Herb.parse("<em>emphasis</em>").value
=>
@ DocumentNode (location: (1:0)-(1:17))
└── children: (1 item)
    └── @ HTMLElementNode (location: (1:0)-(1:17))
        ├── open_tag:
        │   └── @ HTMLOpenTagNode (location: (1:0)-(1:4))
        │       ├── tag_opening: "<" (location: (1:0)-(1:1))
        │       ├── tag_name: "em" (location: (1:1)-(1:3))
        │       ├── tag_closing: ">" (location: (1:3)-(1:4))
        │       ├── children: []
        │       └── is_void: false
        │
        ├── tag_name: "em" (location: (1:1)-(1:3))
        ├── body: (1 item)
        │   └── @ HTMLTextNode (location: (1:4)-(1:12))
        │       └── content: "emphasis"
        │
        ├── close_tag:
        │   └── @ HTMLCloseTagNode (location: (1:12)-(1:17))
        │       ├── tag_opening: "</" (location: (1:12)-(1:14))
        │       ├── tag_name: "em" (location: (1:14)-(1:16))
        │       └── tag_closing: ">" (location: (1:16)-(1:17))
        │
        └── is_void: false

`Herb::AST::HTMLAttributeNode`, `Herb::AST::HTMLAttributeNameNode`, `Herb::AST::HTMLAttributeValueNode`

The HTMLOpenTagNode#children can also contain an array of HTML attributes, represented by the HTMLAttributeNode. The HTMLAttributeNode has a #name pointing to an HTMLAttributeNameNode and a #value pointing to the HTMLAttributeValueNode. The HTMLAttributeValueNode#children points to an array of LiteralNodes.

Herb.parse('<span class="alert">Watch out!</span>').value
=>
@ DocumentNode (location: (1:0)-(1:37))
└── children: (1 item)
    └── @ HTMLElementNode (location: (1:0)-(1:37))
        ├── open_tag:
        │   └── @ HTMLOpenTagNode (location: (1:0)-(1:20))
        │       ├── tag_opening: "<" (location: (1:0)-(1:1))
        │       ├── tag_name: "span" (location: (1:1)-(1:5))
        │       ├── tag_closing: ">" (location: (1:19)-(1:20))
        │       ├── children: (1 item)
        │       │   └── @ HTMLAttributeNode (location: (1:6)-(1:19))
        │       │       ├── name:
        │       │       │   └── @ HTMLAttributeNameNode (location: (1:6)-(1:11))
        │       │       │       └── name: "class" (location: (1:6)-(1:11))
        │       │       │
        │       │       ├── equals: "=" (location: (1:11)-(1:12))
        │       │       └── value:
        │       │           └── @ HTMLAttributeValueNode (location: (1:12)-(1:19))
        │       │               ├── open_quote: """ (location: (1:12)-(1:13))
        │       │               ├── children: (1 item)
        │       │               │   └── @ LiteralNode (location: (1:13)-(1:18))
        │       │               │       └── content: "alert"
        │       │               │
        │       │               ├── close_quote: """ (location: (1:18)-(1:19))
        │       │               └── quoted: true
        │       │
        │       │
        │       └── is_void: false
        │
        ├── tag_name: "span" (location: (1:1)-(1:5))
        ├── body: (1 item)
        │   └── @ HTMLTextNode (location: (1:20)-(1:30))
        │       └── content: "Watch out!"
        │
        ├── close_tag:
        │   └── @ HTMLCloseTagNode (location: (1:30)-(1:37))
        │       ├── tag_opening: "</" (location: (1:30)-(1:32))
        │       ├── tag_name: "span" (location: (1:32)-(1:36))
        │       └── tag_closing: ">" (location: (1:36)-(1:37))
        │
        └── is_void: false

`Herb::AST::HTMLSelfCloseTagNode`

I would expect a void HTML node to result in an HTMLSelfCloseTagNode, however it seems this is instead handled by a HTMLOpenTagNode#void == true.

Herb.parse('<br />').value
@ DocumentNode (location: (1:0)-(1:6))
└── children: (1 item)
    └── @ HTMLElementNode (location: (1:0)-(1:6))
        ├── open_tag:
        │   └── @ HTMLOpenTagNode (location: (1:0)-(1:6))
        │       ├── tag_opening: "<" (location: (1:0)-(1:1))
        │       ├── tag_name: "br" (location: (1:1)-(1:3))
        │       ├── tag_closing: "/>" (location: (1:4)-(1:6))
        │       ├── children: []
        │       └── is_void: true
        │
        ├── tag_name: "br" (location: (1:1)-(1:3))
        ├── body: []
        ├── close_tag: ∅
        └── is_void: true

Tree Nest

The following tree is nested according to the levels above for an quick overview. The only thing to note is that where the HTMLElementNode#body in this case contains an “only-child” of HTMLTextNode for simplicity, it could of course contain many children, of different types, and be nested several layers deep depending on the structure of the HTML.

Herb::AST::DocumentNode
  :children #=> Herb::AST::HTMLElementNode

    Herb::AST::HTMLElementNode
      :open_tag  #=> Herb::AST::HTMLOpenTagNode
      :tag_name
      :body      #=> [Herb::AST::HTMLTextNode, …]
      :close_tag #=> Herb::AST::HTMLCloseTagNode
      :is_void

        Herb::AST::HTMLOpenTagNode
          :tag_opening
          :tag_name
          :tag_closing
          :children #=> Herb::AST::HTMLAttributeNode
          :is_void

            Herb::AST::HTMLAttributeNode
              :name   #=> Herb::AST::HTMLAttributeNameNode
              :equals
              :value  #=> Herb::AST::HTMLAttributeValueNode

                Herb::AST::HTMLAttributeNameNode
                  :name

                Herb::AST::HTMLAttributeValueNode
                  :open_quote
                  :children #=> Herb::AST::LiteralNode
                  :close_quote
                  :quoted

                    Herb::AST::LiteralNode
                      :content

        Herb::AST::HTMLTextNode
          :content

        Herb::AST::HTMLCloseTagNode
          :tag_opening
          :tag_name
          :tag_closing

There are a few more observations to make. The HTMLElementNode consists of three parts, the #open_tag (<span class="alert">, #body (Watch out!) and #close_tag (</span>). It speaks of a #body rather than #children (in other node types) but these seem for all intents and purposes identical in function. The tag nodes (HTMLOpenTagNode and HTMLCloseTagNode) have #tag_opening (<, and </ respectively), #tag_name (span) and #tag_closing (>) methods. The HTMLOpenTagNode has support for HTML attributes via #children and supports void elements (i.e., self-closing tags like <input />) with is_void. HTMLAttributeNodes are themselves a compound of #name and #value where the HTMLAttributeValueNode has itself a #children collection of Herb::AST::LiteralNodes. The LiteralNode and the HTMLTextNode have #content.

—1819, Sunday 20th April 2025.

HTML Gardening with Herb

2025-04-19T00:00:00+00:00

Marco Roth released a new HTML-aware ERB parser library called Herb at the Ruby Kaigi conference a few days ago. Given I’ve been playing around with Phlex over the last week and toying around with the idea of automating templating concerns in a conventional “views and partials” Rails application, it’s perfect timing.

My preference for eschewing a templating language in favour of using the host language natively, inspired by Elm, led to explorations a few years ago which resulted in Michel Martens’ Hypertext library. In the intervening years Joel Drapper has seen some traction with Phlex, conceived with the same ideals, but offering a much more robust and fully-featured solution which plays nicely with Rails.

A key practical benefit of Phlex (widely misunderstood) is that it is a faithful abstraction of HTML (i.e., it doesn’t leak), offering a degree of correctness that a string based templating language like ERB can never provide. If the Ruby can’t interpret a Phlex “template” file (remember, it’s just Ruby) then there is a problem with your “HTML”. If Ruby interprets it, then it is valid HTML. In ERB, you can type anything you want, and you give yourself over to the grace and leniency of browser error recovery when it is presented with malformed HTML. Strings are a leaky abstraction for HTML

In one sense Herb closes this loop. Given it parses ERB files it is able to highlight malformed ERB. So adding it as a linter might give you a certain level of safety. I ran the parser on ClubCollect’s ERB files and in just under twelve-hundred files it found seventy-five parse errors. That’s a defect rate of six percent. Granted, it’s not the end of the world—they are probably all missing tags or malformed HTML, quirks that a browser will forgive—but I’d feel much more comfortable knowing that I couldn’t make those mistakes in the first place.

Herb parses ERB files into an abstract syntax tree which models both the HTML and Ruby parts of an ERB template. The primary purpose of the library is to improve language and editor tooling when working with ERB. What I find more interesting is: firstly, being able to more accurately query the ERB than a simple text-based search; and secondly, being able to modify and/or transform template files programatically.

Querying ERB Semantically

ClubCollect’s codebase is over eleven years old which in modern terms is like ancient history. The accretion of different layers of symbolic sediment, templates subjected to the whimiscal vagaries of different styles and preferences, is something crying out for careful archeological excavation followed by judicious rehabilitation. To give a small, but practical example of stemming the ruinous tide of divergent directives, consider all of the ways that one might have declared a simple Bootstrap Alert component: plain HTML; interpolated Ruby in the HTML class attribute; via a partial; via a helper method. In the first case, simply searching for the string "alert" might yield what I’m looking for, but might also return a number of false positives.

<div class="alert alert-primary" role="alert">
  A simple primary alert—check it out!
</div>

(Bootstrap 4.5.6, this is archeology after all)

With Herb, it is possible to parse the ERB, and because it models the HTML in an AST, it is possible to search for the value "alert" present specifically inside an HTML class attribute. This may not return all the cases, but it reduces the set of false positives.

Modifying ERB Programatically

Let’s say that we want to coalesce our different compositions of Bootstrap Alert into some form of component. Maybe history hindered a former colleagues adherence to accessibility (maybe that former colleague was me!) and left out the role attribute. Having located instances of the Bootstrap Alert it should be possible, with the Herb AST, to ensure conformance to the proper HTML definition, and if it falls short, supplement the existing definition with the missing piece(s).

Looking further, but remaining in ERB, we could write a helper method and ensure that all instances of the Bootstrap Alert use the helper method, rewriting the AST, or simply re-rendering the ERB to file with this modification.

And should one wish to make the switch to a more component-based view layer with GitHub’s ViewComponent or (should I win my colleagues over) Phlex, it should also be possible to automate the transition from ERB.

These two Herb use-cases are things I would very much like to explore.

—1819, Saturday 19th April 2025.

[TIL] PostgreSQL Custom Sort Order

2023-10-12T00:00:00+00:00

Sometimes I want to compare a large enough portion of data from a spreadsheet against data in a PostgreSQL database. The spreadsheet contains a number of rows with an identifier but the records are in a random order and I want to preserve that ordering for the comparison. I therefore want to be able to order the result set from a PostgreSQL database query in a predetermined, custom sort order.

Of course the straightforward workaround is to order the initial spreadsheet’s data by a column that is also natively sortable in the database and the need for a custom sort order vanishes, but trust me on this one, I want the original, random order.

I have an array of identifiers, plucked from the spreadsheet, to use as my query criteria:

membership_no,name
1325,Joe
1123,Ben
1548,Cat

I can transform the membership_no column into an array of values for populating the WHERE clause:

SELECT
  membership_no,
  name
FROM
  members
WHERE
  membership_no IN ('1325','1123','1548');

The results come back in as random an order as they went in. So how to order it according to the original order?

The answer is to use the array_position() function in an ORDER BY clause, using the initial, randomly ordered array. It works as follows:

SELECT
  membership_no,
  name
FROM
  members
WHERE
  membership_no IN ('1325','1123','1548');
ORDER BY
  array_position(ARRAY['1325','1123','1548'], membership_no::text)

This returns the result set in the desired order:

 membership_no | name
--------------------------
 1325          | Joseph
 1123          | Benjamin
 1548          | Catriona
(3 rows)

The first argument to array_position is an array of values representing the desired order, and the second is the database column that will be used for sorting. The value of the column will be positioned according to the order of the values provided.

If you look carefully, you’ll notice that the column value is typecast with ::text. This is necessary as the comparison requires the datatype of the column value and the values in the array to be the same. In this case I am providing the values as text, therefore the column value needs to be cast to a text value. Failure to do this will cause PostgreSQL to complain with an error similar to the following:

ERROR:  function array_position(text[], character varying) does not exist

HINT:  No function matches the given name and argument types. You might need to add explicit type casts.

Well, good thing I added an explicit type cast.

—2127, Thursday 12th October 2023.

References

Setting and Clearing Intervals in the browser

2022-06-20T00:00:00+00:00

When setting up two-way communication over websockets with Phoenix Channels recently I wanted to poll the server until a given event (on the server) had occurred, and then stop. I’ll understand if you start scratching your head and asking why on earth I’d want to poll when a websocket allows me to send notification of said event from the server directly. In this case the polling (via the websocket/channel) is a safety net for instances where the server-side event has happened before, or during, the page request meaning that the server-side event would have been broadcast to no-one. In other cases an exception might prevent the broadcast from being called.

The options for doing this from the Web API off the top of my head were setTimeout and setInterval. The latter seemed the best option for this case, however there were two constraints which eventually expanded my knowledge.

The first constraint was that I wanted to ensure the polling would stop once the event had been received. I was always working in the ignorance that a setInterval would continue until the browser browsed to another page or the tab/window was closed. It turns out that you can store a reference to the interval by assigning the result of the call to a variable:

var intervalId = setInterval(messageServerFn, 5000)

And I learned that that interval reference comes in handy when you want to stop it. There is a related function in the Web API named clearInterval. This function takes an interval reference as a parameter:

clearInterval(intervalId)

And voilà, the function passed to setInterval will no longer be called. Neat.

The trouble with setInterval is that it first runs only after the interval length. In our case above, with a value of five thousand milliseconds, the function will be called for the first time only after five seconds. I wanted the function to be called immediately. This was my second constraint.

It turns out there a few ways of doing this. The most straightforward was not immediately obvious to me given it was so simple, but just calling the function independently of the call to setInterval does the trick.

messageServerFn()
var intervalId = setInterval(messageServerFn, 5000)

No point in making it more complicated than it is.

—Monday, 20th June 2022.

References

Massaging git diff

2022-06-19T00:00:00+00:00

Recently I’ve been working in an Elixir Phoenix application. It’s a legacy application (first commit: December 2015) which has seen it move through both Elixir and Phoenix versions since Elixir 1.1.0 and Phoenix 1.0.4 all the way to Elixir 1.13.4 and Phoenix 1.6.10.

One of the features that was introduced around the half-way point was mix format. This Mix task makes use of a code formatter to automate code style into a consistent format. Runnig this in one go was seen as a violation of the Git history and so much of the formatting has been happening incrementally since that point onwards. There is now a mix format --check-formatted task in CI which doesn’t reformat the code, but reports on only on violations. This means there is a divergence between a freshly minted file that is formatted with mix format and a file that has been manually massaged into a format that doesn’t report any violations. (This is arguably a failing of the formatter in dictating one unambigous style—the conversation has just been moved from one bike-shed to another, rather than shedding it altogether.)

This potential mismatch, paired with the desire to constrain commits and pull requests to only the changes related to the goal of the pull request itself, means that I only want to run mix format on the files that I have changed. And just to be difficult, technically only on the changes that I have made, rather than the whole file. I also want to see the diff between my changes and my changes formatted by mix format.

I was looking for an easy way to do this on the command line (bash). The first challenge was returning only the file names of files I had changed. And to ensure a diff between the mix format result and my edits, my edits are added to the Git staging area. The status therefore looks something like this:

$ git status
On branch demonstrate-diff
Your branch is up to date with 'origin/demonstrate-diff'.

Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
	modified:    lib/demo/helpers.ex
        modified:    lib/demo/schemas/book.ex
        deleted:     lib/demo/schemas/codex.ex

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	modified:   lib/demo/workers/export.ex

The idea is to pick out the necessary file names and then apply mix format to each file. We can use the --name-only option on git diff to return the names:

$ git diff --name-only

This however returns all the names:

lib/demo/helpers.ex
lib/demo/schemas/book.ex
lib/demo/schemas/codex.ex
lib/demo/workers/export.ex

and we only want those from the staging area, the first three. To do that we can use the option --cached:

$ git diff --name-only --cached
lib/demo/helpers.ex
lib/demo/schemas/book.ex
lib/demo/schemas/codex.ex

The problem with returning everything from the staging area is that it will include all operations, including deleted files, which won’t succeed if passed to mix format. We need to turn to the --diff-filter option. I’m really only looking for new files that have added (A) or files that have been modified (M):

$ git diff --name-only --cached --diff-filter=AM
lib/demo/helpers.ex
lib/demo/schemas/book.ex

Now that we have the file names we need to pass those to mix format. This would normally be done with xargs or with a bash for-loop, but I have recently been enjoying the simplicity of map. Using map:

$ git diff --name-only --cached --diff-filter=AM | map f 'mix format "$f"'

And there we have it. mix format being only run for files that have been added or modified. Now I can compare the changes mix format has made with git diff and then selectively add those that are relevant to my own edits, ignoring those that aren’t, using git add --interactive --patch.

—Sunday, 19th June 2022.

References

Basic Form: Field Presentation

2021-07-04T00:00:00+00:00

After decorating our Field class we now have everything we need to render our field to HTML.

We can start for simplicity’s sake with one method, and if necessary split it out into smaller pieces.

We have any number of method names to choose: to_s, to_html, and render. I’m going to go with the first as a Ruby convention.

In terms of building up our HTML I’ll use simple string interpolation for now.

class Field
  …
  def to_s
    %Q(
      <div class="form-group">
        <label for="#{input_id}">
          #{label}
        </label>
        <input 
            type="#{type}" 
            name="#{input_name}"
            value="#{value}"
            class="form-control" 
            id="#{input_id}" 
            aria-describedby="#{help_id}">
        <small 
            id="#{help_id}" 
            class="form-text text-muted">
          #{help}
        </small>
      </div>
    )
  end
end

The only thing that hasn’t been included is the error HTML. That’s a little trickier when doing it this route.

Let’s add a couple of methods to round out this example with the knowledge in the back of our head that a more gracious templating approach would invalidate the need for these methods.

class Field
  …
  def error_class
    errors.any? ? "is-invalid" : ""
  end
  
  def error_text
    errors.join(", ")
  end
  
  def error_html
    %Q(
      <div class="invalid-feedback">
        #{error_text}
      </div>
    )
  end
end

These additions allow us to modify the to_s method as follows:

  class Field
    …
    def to_s
      %Q(
        <div class="form-group">
          <label for="#{input_id}">
            #{label}
          </label>
          <input 
              type="#{type}" 
              name="#{input_name}"
              value="#{value}"
-             class="form-control"
+             class="form-control #{error_class}"
              id="#{input_id}" 
              aria-describedby="#{help_id}">
+         #{error_html}
          <small 
              id="#{help_id}" 
              class="form-text text-muted">
            #{help}
          </small>
        </div>
      )
    end
  end

And that completes the field experiment in our basic form.

The process of pulling everything apart and putting it back together again has been helpful in concretely visualising the more abstract distinctions we had made in the concepts with code.

It also makes very clear just how many subtle layers there are in arriving at the final HTML, and also how much the form/model object and the choice of templating approach influence the final solution.

—Sunday 4th July 2021.

Basic Form: Field Decoration

2021-07-03T00:00:00+00:00

Yesterday we created a Field class that contained all of the source data necessary for building out a field in HTML.

Today we can look at how to decorate this data with some helper methods to calculate the necessary derivatives.

Our categorised and sorted list of data defines the following derived elements coexisting alongside the original data:

input[id] and label[for]
input[name]
help[id] and input[aria-describedby]

Let’s add some methods to our field class:

class Field
  …
  def input_id
    [object_name, name].join("_")
  end
  
  def input_name
    "#{object_name}[#{name}]"
  end
  
  def help_id
    [input_id, "help"].join("_")
  end
end

This is all we need. We could memoize the input_id to ensure it isn’t being calculated from scratch each time. This way we ensure that it remains identical (an edge-case but it feels safer given the values need to be identical for the label and input to correspond properly in the HTML).

class Field
  …
  def input_id
    @input_id ||= [object_name, name].join("_")
  end
  …
end

I believe this is everything we would need for our basic field before rendering it to HTML.

—Saturday 3rd July 2021.

Basic Form: Field

2021-07-02T00:00:00+00:00

Although I started with a rough design for a widget let’s define a field to act as a foundation. We listed and categorised the necessary attributes in variable categories and the relevant list is the last one that categorises by data source.

That means we need the object name, the attribute name, the attribute value and type, and all of the user-facing text comprising of label, help and errors.

There is a choice here to also pass in a more global form object like Rails does by default, or only pass in the necessary information that the field needs. We’ll go with the latter for now.

A rough sketch:

class Field
  ATTRS = %i(
    errors
    help
    label
    name
    object_name
    type
    value
  )
  attr_accessor *ATTRS
  
  def initialize(attrs)
    ATTRS.each do |attr|
      instance_variable_set("@#{attr}", attrs.dig(attr))
    end
  end
end

This would be called in the following way, assuming our ActiveModel EmailSubscription object instantiated as @form:

Field.new({
  errors: @form.errors[:email],
  help: "We'll never share your email with anyone else.",
  label: "Email address",
  name: :email,
  object_name: :subscription,
  type: :email,
  value: @form.email
})

We could of course later figure out a way to make the passing of these details a little less repetitive.

Given this field object we can extend the class with a few methods to generate the necessary elements before rendering it.

—Friday 2nd July 2021.

Basic Form: Widget

2021-07-01T00:00:00+00:00

I’m going to front up and admit that I got lost among the Bureaucrat widgets. The key challenge is that a widget does not have the field object exposed to it, but only a small subset of the field attributes. A field has a widget, but a widget does not have access to a field.

To be as comprehensive as I would like to be, and to broaden the responsibility of a widget to the whole field HTML, including a label, errors, and a hint in addition to the form control then a widget would need access to the field object itself.

My imagined API goes something like this:

field = Field.new
widget = Widget.new(field)
widget.render

To give control back to the field itself and make it responsible for rendering itself then you could do the following:

class Field
  def to_s
    Widget.new(field).render
  end
end

This is obviously a little simplistic—there are no avenues for configuration, nor means for deciding which widget should be used—but let’s run with this for now.

A widget is then responsible for querying the field to get the necessary information:

class Widget
  attr_accessor :field
  
  def initialize(field)
    @field = field
  end
  
  def render
    # HTML
  end
end

The class could be filled out with methods that query the field object to generate the appropriate matching id/for attribute pairs, the name and so on. These methods could then be called from the render method to put everything in place in the HTML.

I think that’s how I would design it. Whether you then need a widget to separate this from the field is another matter (versus keeping it all in the Field class) but the principle is the same.

—Thursday 1st July 2021.

Basic Form: Bureaucrat (3)

2021-06-30T00:00:00+00:00

The widget associated with a Bureaucrat field is limited to the form control itself. The label, help text and errors are not included in a widget out of the box.

Reviewing the field class revealed a label_tag method which produces a label tag with the correct value for the for attribute, associating it with the input’s id element.

I must admit I didn’t quite understand why presentation concerns like this were mixed up with the field class while the widget, which I assumed would deal with all of the presentation logic, only produced the form control itself.

In a template the following code would be necessary to display all of the different facets of a field:

<div class="form-group">
  <%= field.label_tag %>
  <%= field %>
  <% unless field.errors.empty? %>
    <div class="invalid-feedback">
      <%= field.errors %>
    </div>
  <% end %>
  <% unless field.help_text.empty? %>
    <small class="form-text text-muted">
      <%= field.help_text %>
    </small>
  <% end %>
</div>

I feel like this defeats the purpose of abstracting away the form control into a widget. Either the widget should deal with everything, or there should be no widget.

To compare it with Rails, the widget is the raw input_tag helper, whereas my sensibilities would want a widget to be more like an all-inclusive Formtastic or Simple Form helper.

So while Bureaucrat starts down a declarative path, for me it doesn’t go far enough. The inclusion of a label_tag in the field, but nothing for errors or help text is a little short-sighted. The argument might be that you can easily extend Bureaucrat to add them, and that’s a fair point. But to arrive at a solution that caters to all of the elements of a form control then also needs the introduction of a custom widget. Perhaps we can take advantage of the inheritance hierarchy to make this a reality.

—Wednesday 30th June 2021.

crossingtheruby.com

HTML Parsley with Herb

Herb AST Node Types

Parsing HTML

Herb::AST::DocumentNode

Herb::AST::HTMLDoctypeNode

Herb::AST::HTMLCommentNode

Herb::AST::HTMLElementNode

Herb::AST::HTMLAttributeNode, Herb::AST::HTMLAttributeNameNode, Herb::AST::HTMLAttributeValueNode

Herb::AST::HTMLSelfCloseTagNode

Tree Nest

HTML Gardening with Herb

Querying ERB Semantically

Modifying ERB Programatically

[TIL] PostgreSQL Custom Sort Order

References

Setting and Clearing Intervals in the browser

References

Massaging git diff

References

Basic Form: Field Presentation

Basic Form: Field Decoration

Basic Form: Field

Basic Form: Widget

Basic Form: Bureaucrat (3)

`Herb::AST::DocumentNode`

`Herb::AST::HTMLDoctypeNode`

`Herb::AST::HTMLCommentNode`

`Herb::AST::HTMLElementNode`

`Herb::AST::HTMLAttributeNode`, `Herb::AST::HTMLAttributeNameNode`, `Herb::AST::HTMLAttributeValueNode`

`Herb::AST::HTMLSelfCloseTagNode`