Hanami and HTMX - progress bar
Tags: hanami, htmx, ruby
Published: 2024-05-07 09:03:15

---
title: Hanami and HTMX - progress bar
published: true
description: A write-up/tutorial of using hanami.rb and htmx to create an updating progress bar that monitors a long running process
tags: hanami, htmx, ruby
canonical_url: https://2n.pl/blog/hanami-progress-bar-with-htmx
cover_image: https://dev-to-uploads.s3.amazonaws.com/uploads/articles/0863rcs6k1k32lm0pgw7.jpg

# cover_image: https://direct_url_to_image.jpg
# Use a ratio of 100:42 for best results.
# published_at: 2024-05-07 08:58 +0000
---


Hi there! I want to show off a little feature I made using hanami, [htmx](https://htmx.org/) and a little bit of [redis](https://redis.io/) + [sidekiq](https://sidekiq.org/).

It is a popular pattern to show a progress bar when you're doing some longer-running task, like uploading a file, or processing some data. I wanted to show you how to do it in hanami, while making the progress bar fill smoothly, and not just jump from 0 to 100% when the task is done.


### The app and the task

I have an app running Hanami 2.1, it [has persistence setup with ROM](https://hanamimastery.com/episodes/28-configure-rom-from-scratch) and is using hanami-views for rendering, hanami-assets for providing CSS. Pretty much everything that we need for our task is in a slice called `main`.

[Sidekiq is already configured](https://hanamimastery.com/episodes/27-integrate-sidekiq-with-hanami) along with assets, [tailwindsCSS](https://tailwindcss.com/).

Our app is going to be a personal library management system, where users can track their books, their placement on a shelf, racks, status of borrowing etc. 

The main page has an input for ISBN number. That input sends a GET request to the server, which then fetches the book data from [google books API](https://developers.google.com/books), parses the data to fit our own books relation in ROM, checks if we have it saved in our DB, saves it if not, or just returns the finished status if we already have it.
In the meantime, users sees a progress bar that fills up smoothly, and when the task is done, the progress bar disappears and the book data is shown.

The resulting code will have to use some sleep statements to show the "animation" on the progress bar since normally it is too fast to notice.

### Redis

Redis setup is super easy thanks to [providers](https://guides.hanamirb.org/v2.1/app/providers/)

```ruby
#config/providers/redis.rb
Hanami.app.register_provider(:redis) do
  prepare do
    require "redis"
  end

  start do
    client ||= ConnectionPool::Wrapper.new do
      Redis.new(url: target["settings"].redis_url)
    end

    register "redis", client
  end
end
```

```ruby
#config/settings.rb
setting :redis_url, default: "redis://localhost:6379", constructor: Types::String
```

Now when we do `include Deps['redis]` we get a redis client that we can use to store/read our progress data.

### HTMX

HTMX has a [couple of ways to install](https://htmx.org/docs/#installing). I chose `npm` because I already used it in the project for tailwindCSS and I have hanami-assets configured for assets.

```javascript
//slices/main/assets/js/app.js
import "../css/app.css";
import 'htmx.org';
import './htmx.js'
```

```javascript
//slices/main/assets/js/htmx.js
window.htmx = require('htmx.org');
```

And this is all it takes to have HTMX working on your hanami project. If you want to see a quick test example to make sure it works, check out [this commit on the demo repo](https://github.com/krzykamil/libus/commit/5e7b1d176563aac52cc7a7e3b759d5b3d3bda06a).

### Actions and Views

We need few blocks in place: downloading the data, parsing it, saving it to DB, and checking if we already have it. All of this needs to be tracked by the backend and monitored by frontend to show the progress.

So lets start with displaying everything, since we can use placeholders for that. 

Our slice will have 3 relevant actions: `IsbnSearch`, `SearchProgress` and `SearchResult`.

```ruby
    scope 'search' do
      get '/isbn', to: 'isbn_search.show'
      get '/progress', to: 'search_progress.show'
      get '/result', to: 'search_result.show'
    end
```

First step will be the search:

```ruby
module Main
  module Actions
    module IsbnSearch
      class Show < Main::Action
        params do
          required(:isbn).filled(:string)
        end

        def handle(request, response)
          halt 422, {errors: request.params.errors}.to_json unless request.params.valid?
          Main::Workers::IsbnSearch.perform_async(request.params[:isbn])
          response.render(view, isbn: request.params[:isbn])
        end
      end
    end
  end
end

# Spec, only showing the basic happy path example, for breviety
context "with good params"  do
  let(:params) { Hash[isbn: "978-0-306-40615-7"] }
  let(:worker) { double(Main::Workers::IsbnSearch) }
  it "works" do
    Sidekiq::Testing.fake! do
      response = subject.call(params)
      allow(Main::Workers::IsbnSearch).to receive(:perform_async)
       .with("978-0-306-40615-7")
       .and_return(worker)
      expect(response.status).to eq 200
    end
  end
end
```
Then we have the view object

```ruby
module Main
  module Views
    module IsbnSearch
      class Show < Main::View
        config.layout = nil

        expose :isbn do |isbn:|
          { type: isbn.size, identifier: isbn }
        end
      end
    end
  end
end
```

With the template:

```rhtml
<input hidden id="isbn-type" name="isbn[type]" value="<%= isbn[:type] %>">
<input hidden id="isbn-identifier" 
                       name="isbn[identifier]" 
                       value="<%= isbn[:identifier] %>">

<div
    hx-trigger="done"
    hx-get="/search/result"
    hx-include="#isbn-type, #isbn-identifier"
    hx-swap="outerHTML"
    hx-target="this">
  <h3 role="status" id="pblabel" tabindex="-1" autofocus>Searching</h3>

  <div
    hx-get="/search/progress"
    hx-include="#isbn-type, #isbn-identifier"
    hx-trigger="every 2000ms"
    hx-target="this"
    hx-swap="innerHTML">

    <div class="w-64 h-5 mb-5 overflow-hidden bg-base-100 rounded-md shadow-inner" 
            role="progressbar"
             aria-valuemin="0" 
            aria-valuemax="100"
            aria-valuenow="122"
            aria-labelledby="pblabel">
      <div id="pb" class="float-left h-full text-white text-center bg-accent transition-width duration-2000" 
              style="width:0%"></div>
    </div>
  </div>
</div>
```

This is where the majority of HTMX magic comes in. We have 3 important div's:
1. The outer **div**, that will be replaced with the result of the search, and along with him, all divs inside (that are described below)
2. The progress **div**, that every 2 seconds checks the progress of the search, and updates the progress bar -> **div** below
3. The initial progress bar **div**, that is replaced with the progress bar **div** from the `SearchProgress` action, the **div** from point 2 makes the request.

All this happens based on the `hx-target`, `hx-get` and `hx-swap` attributes, `hx-trigger` is used to repeat the request every 2 seconds on the **div** that checks the progress, and for completing the process in case of the outer **div**.
- `target` tells HTMX where to put the response
- `get` is simply the request identifier, the `get` is the type and the value given is the URL
- `swap` is a method of replacement, so how to replace the target with the response

This is all rather basic stuff from HTMX, pretty much the [introduction part of their docs](https://htmx.org/docs/#introduction). So if you think it is somewhat impressive, keep it mind this is just what is possible with the very basics. Although I do think that hanami routing and actions and view systems make it much easier to use (than for example rails would). In Hanami it is simply very easy to make the code very modular, composable and repeatable. I think HTMX and Hanami are a great fit together and I hope this whole example does show it.

So lets take a look at the `SearchProgress` action:

```ruby
module SearchProgress
  class Show < Main::Action
    include Deps["redis"]
    def handle(request, response)
      if redis.hget("isbn_search", request.params[:isbn][:identifier]).to_i == 3
        response.headers["HX-Trigger"] = "done" 
      end
      response.render(view, isbn: request.params[:isbn])
    end
  end
end
```

`HX-Trigger` is a header that will tell the HTMX to trigger the `done` action, which will fire up the `SearchResult` action, and that will render the result of the search.
The header is based on the redis value, which is set by the worker (we will get there soon).

```ruby
module SearchResult
  class Show < Main::Action
    include Deps["repositories.books"]

    def handle(request, response)
      response.render(
        view,
        book_found: books.by_isbn(type: request.params[:isbn][:type].to_i,
        identifier: request.params[:isbn][:identifier])
      )
    end
  end
end
```

Result is simple, we use the books repo to make a simple request, som rom and sequel are used here, but it is not really relevant to the topic at hand, so the repo implementation is omitted.

You probably noticed the inputs in the view, they just hold the values we need to keep finding the correct book based on the initial isbn (which later got an identifier on the back, that tells us if it is ISBN-10 or 13 to make some queries easier).

The templates are also important, here is the template for progress along with its view object:

```rhtml
<div class="w-64 h-5 mb-5 overflow-hidden bg-gray-300 rounded-md shadow-inner" 
        role="progressbar" 
        aria-valuemin="0" 
        aria-valuemax="100" 
        aria-valuenow="<%= search_progress %>" 
        aria-labelledby="pblabel">
  <div id="pb" class="float-left h-full text-white text-center bg-accent transition-width duration-2000" 
         style="width: <%= search_progress %>%">
  </div>
</div>
```

```ruby
module Main
  module Views
    module SearchProgress
      class Show < Main::View
        config.layout = nil
        include Deps["redis"]
        expose :search_progress, decorate: false do |isbn:|
          search_progress(isbn: isbn)
        end

        private

        def search_progress(isbn:)
          progress = redis.hget("isbn_search", isbn[:identifier])
          case progress.to_i
          when 1
            40
          when 2
            80
          when 3
            100
          else
            10
          end
        end
      end
    end
  end
end
```
Just a simple check of the redis value, and returning the correct value for the progress bar. Then the rest is taken care by CSS and tailwind styling. Thanks to sharing the `id` between the HTML elements that are "replaced", the transition is smooth, rather than the filler color of the bar just appearing. It flows.

Then we have the result that replaces the progress bar, it is a simple card with the book data, taken from the struct we got from the repository.

```rhtml
<div class="card lg:card-side bg-base-100 shadow-xl">
  <figure class="w-1/2 h-1/2 max-w-96 max-h-96">
    <img src="<%= book.image_url.gsub("http", "https") %>" alt="Cover" />
  </figure>
  <div class="card-body">
    <h2 class="card-title">
      <%= book.title %>
    </h2>
    <p>
      <%= book.description[0..500] %>
    </p>
    <div class="card-actions justify-end">
      <button class="btn btn-primary">See more</button>
    </div>
  </div>
</div>
```

```ruby
module SearchResult
  class Show < Main::View
    config.layout = nil

    expose :book, decorate: false do |book_found:|
      book_found
    end
  end
end
```

Those are all the blocks we need in place to have a fully functional frontend. We just need the backend to implement all the logic that does the actual work, and monitors the progress.


### Worker that works hard

For brevity's sake I will only show the basic spec, with the conditions we wanna meet.

We wanna take an ISBN, and delegate work to other objects, checking if the book was saved (this is a scenario where the ISBN is for a new book), and that redis status was updated correctly at the end.

```ruby
  context 'when called' do
    let(:google_isbn_service) { double(Main::Services::GetGoogleIsbn) }
    let(:parser) { double(Main::Services::GetGoogleIsbn) }
    let(:parse_output) {
      { title: "Dune",
        description: "A nice SF book",
        image_url: "https://www.some.site",
        published_date: "1965",
        category: "SF",
        language: "en",
        authors: ["Frank Herbert"],
        isbn_numbers: [
          { type: 10, identifier: "0441172717" },
          { type: 13, identifier: "9780441172719" }
        ]
      }

    }

    it 'processes the job' do
      expect(Main::Services::GetGoogleIsbn).to receive(:new).and_return(google_isbn_service)
      expect(Main::Parsers::Google::Isbn).to receive(:new).and_return(parser)
      expect(google_isbn_service).to receive(:call).with(isbn: "9780441172719").and_return({ body: "some body" })
      expect(parser).to receive(:parse).with(json: { body: "some body" }).and_return(parse_output)
      expect{Main::Workers::IsbnSearch.perform_async("9780441172719")}.to change{db[:books].count}.by(1)
      expect(Hanami.app["redis"].hget("isbn_search", "9780441172719")).to eq("3")
    end
  end
```

In general sidekiq workers should only take **the most basic input** (strings etc.) and **delegate** most of the work to other objects, so that we can test them in isolation, handle errors better etc. This is the way I always preferred the workers/jobs to be coded, and it works great here too, cause we just list all the dependencies, use them one by one and monitor the process easily and clearly thanks to that.

For brevity's sake I've put everything in the perform method, but it in real life it could be a good idea to split it out more into methods, for readability and clearer error outputs.

```ruby
module Main
  module Workers
    class IsbnSearch
      include Sidekiq::Job
      include Deps[
                "services.get_google_isbn",
                "redis",
                "persistence.rom",
                "repositories.books",
                parser: "parsers.google.isbn"]

      def perform(isbn)
        redis.hset("isbn_search", { isbn => 1 })

        output = parser.parse(json: get_google_isbn.call(isbn:))

        redis.hset("isbn_search", { isbn => 2 })

        if books.by_isbn(type: 10, identifier: isbn) || books.by_isbn(type: 13, identifier: isbn)
          redis.hset("isbn_search", { isbn => 3 })
        else
          rom.relations[:books].transaction do
            author = rom.relations[:authors].changeset(
              :create, { name: output[:authors].join(', ') }
            ).commit
            new_book = rom.relations[:books].changeset(
              :create, output[:data]
            ).commit
            redis.hset("isbn_search", { isbn => 3 })
          end
        end
      end
    end
  end
end

```

Now this is a fully functional progress bar (the implementations of parser and get_google_isbn objects are not really relevant, those are implementation details not connected to progress bar directly).

This could be further improved and made into a far more reusable code, with redis communication being delegated to **pub/sub** system, that could be better coupled with places that do actually push the progress forward, rather than putting everything into a worker, that should be more of a simple delegator.

But maybe **pub/sub** system in hanami is a topic for a different episode?

This gives us a reactive progress bar, that updates every second and in the end, switches place with the ready content.

You can see a gif of it working on the original article page, if you do not believe me.



### Summary

So this is a neat feature using Hanami and HTMX, backed by redis and sidekiq. I hope this was a nice mix of familiar and unfamiliar technologies, to get you interested in something new, like Hanami or HTMX.