DEV Community: Turcu Laurentiu

Why you should choose HTMX for your next project

Turcu Laurentiu — Thu, 19 Oct 2023 05:21:36 +0000

In this article, we will aim to understand why you should consider HTMX as a replacement for React next time you choose a tech stack for a web app. We will look at the complexity and the challenges that a traditional HTTP JSON API + React brings and how easily you can avoid them by using HTMX.

NOTE: In this article I will address to React but it can be replaced with any other Front-end framework like Angular or Vue or Svelte or Solid, but I talk about React because it's the default technology that most of the web developers default to.

What even is HTMX

If you don't know already, HTMX is a small browser (JS) library that extends HTML with a few attributes that allows you to update parts of a web page with some response from the server. It also enables HTML to make HTTP requests on all the verbs not only GET and POST.

What problem does React solve

React is a JavaScript library that helps you write highly interactive applications by keeping the user interface in sync with the state. You tell it how to render a given state, and every time the state is updated, it will re-render ( as efficiently as they can ) the UI to reflect the state changes.

Every time the state has changed, you notify the library that it changed and you provide the new state and it will deal with the UI updates.

Examples of high interactive apps that needs local in memory state can be one of the various text editors that you can find on the web (VSCode), a drag and drop kanban board as Trello or JIRA, a video player or a chat room.

What is not an example of such an app? The to-do list you are building, the news website you are reading, the blog you are posting on and most of the websites around. If we were to look at the 80/20 rule

80% of effects come from 20% of causes and 80% of results come from 20% of effort.

You can argue that 80% of the web apps that uses React don't have the need of a local state. And from those 20% that needs it, you can argue that it's only a small portion of the app (about 20%) and the rest can be expressed only in HTML.

The numbers are made up, I don't have any research to back this up

What react also solves that made it widely adopted for modern websites

HTML is old and outdated. The old ways of making applications with HTML involved a collection of pages, links and forms that describes to the user the current state of a given resource and what they can do to change it.

Every time the user interacted with a resource, the application could only reload the whole page to display the new state of the resource.

A couple of years later FaceBook introduced React, a JS library that allowed developers to create single page applications (SPA). No more full page reloads when navigating and cool transitions for state updates, interesting feedback to the user and other niceties that made the web developers adopt SPA Frameworks for their websites.

The Complexity Issue

If you don't understand the above schema, don't worry, there is nothing to understand. I asked ChantGPT to generate it for me, and since it's over-complicated and it doesn't make any sense, it perfectly reflects the current default infrastructure for a modern web app.

One cool programming principle is KISS which stands for Keep it Stupid Simple, or how some might like to joke, Keep it Simple, Stupid!

Current infrastructure and tech stack that modern developers defaults to create web apps is extremely complicated, doing a lot of things that it doesn't have to, just because it's cool!

And works fine, when you are building the first POC by yourself, but the next moment you add more team members, and an agile way of working with multiple iteration and "embracing" the changes, it kind of breaks, for the reasons we will take a look down the line.

The State Management Problem with traditional HTTP JSON API + React

What you often have to do in a web app is to get the state of a resource from the database and present it to the user. Let's take the example of a task management application. The user has a list of tasks, each task has as a state:

The title of the task
A description
A flag if the task was completed
A due date (optional)

We usually store this state in a database and to present this information to the user you have to:

Get all the tasks from the database where the user has access to.
Optionally transform the data (maybe you store the date it was completed and you compute the is_completed flag from that).
Serialize the data into JSON.
Fetch the data via an HTTP request.
(optionally but usually) validate the data against a schema, probably with YUP or ZOD.
transform the JSON into state and store it in a cache using Redux, Zustand, react-query or another state management library.
Transform that state in HTML usually figuring out what the user can do with the data.

In a nutshell, we are describing how to render all the possible states of all the resources in JavaScript, download the said JavaScript in the browser, then the JavaScript downloads a bunch of data in JSON format and render it (if it knows how) on the browser as HTML!

This is a lot of work to show a list of tasks to the user, especially when the tasks only changes when the user changes it and to do so, the app has to put the app in a loading state, make another HTTP request (to PUT or PATCH or DELETE) invalidate the cached value (the state) and re-fetch it to display the changed task.

Or even worse, when the user changes some task, optimistically update the local state and show the change right away and perform the request to update behind the scenes only to notify the user that the update failed after they sow it successfully updating.

This is extremely error prone. It might work well for this to-do app where you are the only developer and the app is mall enough that you can keep a mental map of everything that is happening. But when you have a larger team, especially when you split the team between front-end and back-end, a lot of issues can arise from miscommunication.

The back-end might use the is_completed flag while the front-end might expect an is_active flag. The back-end might send the description processed from markdown to HTML while the front-end might expect it to be unprocessed. The back-end might make the description optional to allow the users to save drafts while the front-end is not in sync and you see a lot of Uncaught TypeError: Cannot read properties of undefined (reading 'toLowerCase')

On the other hand, on HTMX, you render the HTML directly on the template, as typesafe as your backend language allows it. You send only the relevant information to the browser, you present the user with the appropriate controls on the resource and you instruct the browser or HTMX how to interpret the user actions and the backend response to those actions. All the application state is the HTML, a concept known as HATEOAS

The need for documentation for traditional HTTP JSON API + React

In order to have two teams (back-end and front-end) work independently and communicate via HTTP JSON API, you need to have proper documentation of the API. You also need to document how to calculate what actions a user can take on a given resource in order to display the controls.

Most of this kind of documentation is a pain to write, especially because usually it's required to write before it's implemented, when the developer doesn't yet fully understand the scope of the problem so the front-end can be developed in parallel. This usually ends up with many updates while in development to adjust for the problems that arises during the development and can lead to miss-aligned versions between the teams.

You also need to version the API and be careful to not introduce breaking changes on a non major version changes. You can no longer change the name of a field without bumping the major version. You also need to ether keep multiple versions of the API running or force the front-end team to adapt.

And most of the time, the documentation get's outdated. Some must be urgently fixed, some new requirements come the day before release and now your documentation is out of date, even for a short period of time. And you have to remember to update it, or even worse, you create a ticket to remember it, and somebody else picks it up that doesn't have the whole picture and documents it wrong!

The duplicated logic issue

For each resource, you have to implement authorization policies. You must determine if the current user can mark the task 46234 as completed. Somewhere in the back-end code you must write this check. Otherwise you leave your app open to insecure direct object reference, or anyone with Postman can mark your task done.

You also have to implement the same logic in the front-end, to show the mark button only if the user has the rights to mark is as complete (let's pretend that you can share your tasks with other users, but only you can change them).

Now every time this logic changes, you must implement it in both applications, and release it at the same time or have multiple versions of the API.

The performance issue

In order to have a website rendered in the browser with React, you need to bundle together the react code that has a gigantic footprint on memory and parsing/processing impact, the state management library code, toe UI library code, the CSS-IN-JS library code, the application code and whatever js library we install and use with NPM (and we are not shy to install a new package, see the leftpad problem). This results in usually chunky JavaScript assets to be delivered via network. Sure, you can cache in the browser, but on modern agile development, you deploy at least once per sprint, so that solves nothing. This consumes network traffic and battery, a much ignored problem for mobile devices.

The above mentioned JavaScript needs to be interpreted by the browser, thus consuming processing power and battery.

The JavaScript, especially the ReactDOM, needs to keep track of a mirror of the DOM. Add the normal DOM on top of that and the local state cache, and all the render functions, and all the useMemo and useCallback and useState. Also add all the closures that needs to keep in memory all the context variables. And JavaScript engines are not known for their memory efficiency! You hear people lamenting about how much memory the browser consumes, but they underestimate how much that comes form the websites they visit.

All those adds up and you end up draining users batteries and memory. Sure, you can put the effort and optimize all that, or use another library like Svelte, but all that effort can be put into delivering more meaningful features for your users.

The need for server side rendering

In recent years, we sow the rise of the server side rendering specialized frameworks like Next.js. Their popularity highlights the needs for content to be delivered in HTML format, especially for accessibility optimization, performance and search engine optimization reasons.

You don't want to wait for the browser to download the JavaScript to render the page, then wait for the JavaScript to make HTTP requests to get the contents and then render it, you want it to be rendered right away, especially for the above the fold content.

This adds another layer of complexity, including:

The infrastructure, now you need another server for the front-end app too
The code is more complex, including the mental map of what code runs on the server and what on the browser
The deployment pipelines are now more complex
The testing infrastructure is now more complex
Troubleshooting an issue is now harder, you need to understand if the issue is on the browser, on the client app server or on the API server

Solving those problems

The web development community, each on their own language or technologies they develop on, tied to solve those problems in different ways:

Next.js (and Nuxt and alike)
- React server components
Laravel
- Inertia.JS
- Livewire
DotNet
- Blazor Pages
Elixir
- Phonix LiveView
Rust
- Leptos Server Functions

And many other solutions that I forgot about or never heard about!
Anyway, the existence and popularity of such solutions is the proof that those issues are valid and encountered in the daily life of a web developer. Otherwise they wouldn't go out of their way to solve them, especially in an open source manner!

There is also Turbo and the frameworks who adopt them, Ruby on Rails, PHP Symphony and possibly others that solves the same issue in the same manner as HTMX. And the choice for HTMX is only a personal taste in this, but you should definitely learn about this, this is as cool as HTMX!

Among all those, HTMX stands out, not only because it doesn't lock you in to a specific technology, you can switch from PHP to Rust with minor changes to the templates, but to the fact that it completely removes the need for stateful components, or the need to keep track of a certain state of the app that is not resource related.

For example, let's take a confirmation dialog modal. What you usually end up doing, is that you have a local in memory state if it's open, and display it to the user based on that state. In HTMX, the state IS THE HTML meaning that when you click on open modal, you GET the tasks/{taskId}/confirm-delete and embed the response HTML in the DOM. And when it's deleted, you delete the modal and the task altogether! This solves all the above mentioned problems in an unique and extremely simple manner, you don't need to:

keep track of the state
know how to render the dialog
document the API
check if the user can delete the task ( in the front-end)
your back-end app is always in charge
you get better security as you don't send irrelevant data to the browser and sneak sensitive info
you get better performance

And most importantly, you keep your app dead simple, and allow complexity only when it solves user problems!

You just instruct HTMX where to get the dialog from, and where to put it, and it's all handled!




<!-- the delete button -->
@if ($chirp->user->is(auth()->user()))
    <form>  
        @csrf  
        @method('delete')  
        <x-dropdown-link  
            :component="'button'"  
            type="submit"  
            hx-get="{{ route('chirps.confirm-destroy', $chirp) }}"  
            hx-swap="beforeend"  
            hx-target="closest .chirp"  
    >    
            {{ __('Delete') }}  
        </x-dropdown-link>  
    </form>
@endif


<!-- the dialog template -->
<div class="modal fixed z-10 inset-0 overflow-y-auto flex justify-center items-center bg-black bg-opacity-50" style="backdrop-filter: blur(14px);">  
    <div class="bg-white rounded p-6">  
        <h2 class="text-xl border-b pb-2 mb-2">Confirm Action</h2>  
        <p>Are you sure you want to delete this chirp?</p>  
        <div class="flex justify-end mt-4 gap-4">  
            <x-secondary-button _="on click remove closest .modal" >
                Cancel
            </x-secondary-button>  
            <form>                
                @csrf  
                <x-danger-button  
                    hx-delete="{{route('chirps.destroy', $chirp)}}"  
                    hx-target="closest .chirp"  
                    hx-swap="delete">  
                        Delete  
                </x-danger-button>  
            </form>
        </div>    
    </div>
</div>

this example is from my tutorial on [HTMX with Laravel](https://dev.to/turculaurentiu91/laravel-htmx--g0n, check it out!

And just like that, we instruct HTMX, when we click on the delete button, to do a GET request to the chirps/{chirp}/confirm-destroy and put the resulted HTML before the closest parent <div class="chirp"> ends (at the bottom). And in the delete dialog, when the user confirms, we instruct HTMX to do a DELETE request, to the chirps/{chirp} endpoint, and when successful, we delete the closest parent with the chirp class.

Conclusion

In the ever-evolving landscape of web development, it's refreshing to see tools like HTMX that advocate for simplicity and a return to the basics. By leveraging the power of HTML and HTTP, HTMX allows developers to create dynamic web applications without the complexities and overhead of traditional JavaScript frameworks.

So, next time you're starting a new project or considering refactoring an existing one, give HTMX a try. You might be surprised at how much you can achieve with so little.

Laravel + HTMX = ❤️ 3x

Turcu Laurentiu — Sat, 14 Oct 2023 09:51:52 +0000

Welcome to the final installment of our Chirper tutorial series. In this part, we will refine our platform by introducing a few advanced features: an active search mechanism, more robust form validation, and a user-friendly confirmation dialog for chirp deletion. These enhancements are aimed at not only improving the user experience but also showcasing the flexibility and power of combining Laravel with HTMX and Hyperscript. Let's delve in and give Chirper a polished edge!

Searching trough chirps

On a more complex app you might want a different search engine/database and you might want to integrate with Laravel Scout and Angolia. However, for the purpose of this tutorial, a simple LIKE query would have been fine, if I didn't generated a huge amount of chirps on my test server.

In order to gain some performance and keep my test server simple and cheap, I will go with MySQL FULLTEXT indexesand raw queries. It's a good enough search mechanism that you can follow if you have MySQL. If you are using anything else, replace the scope with a LIKE and it will work just fine.

The full text index

MySQL offers a full text index to be applied on VARCHARs and TEXT fields that you can later use to perform natural language search in your tables, let's create a migration to apply the index.

php artisan make:migration add_full_text_index_on_chirps_message --table chirps

<?php  

use Illuminate\Database\Migrations\Migration;  
use Illuminate\Database\Schema\Blueprint;  
use Illuminate\Support\Facades\Schema;  

return new class extends Migration  
{  
    /**  
     * Run the migrations.     
     **/    
     public function up(): void  
    {  
        Schema::table('chirps', function (Blueprint $table) {  
            \Illuminate\Support\Facades\DB::statement('ALTER TABLE chirps ADD FULLTEXT fulltext_index (message)');  
        });  
    }  

    /**  
     * Reverse the migrations.     
     **/    
     public function down(): void  
    {  
        Schema::table('chirps', function (Blueprint $table) {  
            \Illuminate\Support\Facades\DB::statement('ALTER TABLE chirps DROP INDEX fulltext_index');  
        });  
    }  
};

Cool, now apply it with php artisan migrate, this might take a couple of seconds, depending on how many chirps you have.

Legacy form submit search

Let's start by adding a normal HTML form that will perform the search action, and later we will enhance it with HTMX to search while you type. In the chirps.index template, we will add the form:

<!-- resources/views/chirps/index.blade.php -->

<x-app-layout>  
    <div class="max-w-2xl mx-auto p-4 sm:p-6 lg:p-8">  

        <form            
            method="GET"  
            action="{{ route('chirps.index') }}"  
            class="flex items-center space-x-2 mb-4 w-full bg-white border-1 border-gray-300 px-4 py-2 rounded-md shadow-sm focus-within:ring focus-within:border-indigo-200 focus-within:ring-indigo-200 focus-within:ring-opacity-50"  

        >  
            <input                
            type="text"  
                name="search"  
                aria-label="search"  
                class="w-full bg-white border-0 p-0 focus:ring-0 focus:border-0 focus:outline-none"  
                placeholder="Search for chirps"  
                value="{{ request('search') }}"  
            >  
            <button                
                type="submit"  
                class="bg-gray-100 p-1 rounded hover:bg-gray-400 transition"  
            >  
                <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" class="w-6 h-6">  
                    <path stroke-linecap="round" stroke-linejoin="round" d="M21 21l-5.197-5.197m0 0A7.5 7.5 0 105.196 5.196a7.5 7.5 0 0010.607 10.607z" />  
                </svg>            
            </button>        
        </form>
    <!-- rest of the template -->

    <!-- long pooling div -->
    @if($chirps->count() > 0)  
        <div hx-get="{{  
                route('chirps.pool', [  
                    'latest_from' => $chirps->first()->created_at->toISOString(),  
                    'search' => request('search')]) }}"  
             hx-trigger="every 2s"  
             hx-swap="outerHTML"></div>  
    @endif

This is a simple HTML form, that will make a GET request to the same index page with the ?search query param. We also modified the long pooling <div>, we firstly wrapped it in an @if to render it only if there are chirps (to avoid an error when there are no chirps) and we also added the search query param to the route function, to avoid loading chirps that don't satisfy the search query.

Now let's add a search scope in the chirps model:

// app/Models/Chirp.php

public function scopeSearch(Builder $query, mixed $search): Builder  
{  
    if(is_string($search)) {  
        $search = Str::of($search)->trim()  
            ->explode(' ')  
            ->map(fn($word) => '+' . $word . '*')  
            ->join(' ');  

        return $query->whereRaw('MATCH(message) AGAINST(? IN BOOLEAN MODE)', [$search])  
            ->orderByRaw('MATCH(message) AGAINST(? IN BOOLEAN MODE) DESC', [$search]);  
    }  

    return $query;  
}

What this scope is doing, if the $search param is a string, it will explode it into words, prepend a + and append an * to each word. The + means that the message must include the word and the * means that the matched word must start with.

The order by will order by relevance.

And we can use the scope in the index and pool controller methods:

// app/Http/Controllers/ChirpController.php

/**  
 * Display a listing of the resource. 
 **/
 public function index(Request $request): Response  
{  

    $chirps = Chirp::with('user')  
        ->latest()  
        ->when($request->has('search'), fn($query) => $query->search($request->query('search')))  
        ->paginate(25);  

    return \response()->view('chirps.index', [  
        'chirps' => $chirps  
    ]);  
}  

public function pool(Request $request): Response  
{  
    $validated = $request->validate([  
        'latest_from' => 'required|date',  
    ]);  

    $chirps = Chirp::with('user')  
        ->where('created_at', '>', $validated['latest_from'])  
        ->where('user_id', '!=', $request->user()->id)  
        ->when($request->has('search'), fn($query) => $query->search($request->query('search')))  
        ->latest()  
        ->get();  

    if($chirps->count() === 0) {  
        return \response()->noContent();  
    }  

    return \response()->view('chirps.pool', [  
        'chirps' => $chirps,  
    ]);  
}

We only added the when statements, to use the search query scope only when the search query param is present on the request.

Active search

This is cool and all and it works just fine, but there is no HTMX magic here excluding the boosting. So let's add some HTMX properties on the search input to search when the user finished typing.

<!-- resources/views/chirps/index.blade.php -->

<input  
    type="text"  
    name="search"  
    aria-label="search"  
    class="w-full bg-white border-0 p-0 focus:ring-0 focus:border-0 focus:outline-none"  
    placeholder="Search for chirps"  
    value="{{ request('search') }}"  
    hx-trigger="keyup changed delay:500ms"  
    hx-get="{{ route('chirps.index') }}"  
    hx-target="#chirps"  
    hx-swap="outerHTML"  
    hx-select="#chirps"  
>

That's all we need to add for the active search. What we instruct HTMX is:

hx-trigger: when the keyup event fires on this input, if the value changed we delay for 500ms and if no new event happens we do the request
hx-get: perform a get request to the index, it will add the search query param using the name of the field to decide how to name it.
hx-target hx-swap and hx-select: it will select the <div id="#chirps" from the response and it will replace the whole div for the target with the same ID.

Form Validation

So far, across our app, we just ignored form validation, in this section we will take a look at how to display back-end validation messages using HTMX.

Edit Chirp Form

When editing the chirp in the ChirpController::update, if the validation fails, the response throws an ValidationError and Laravel's default behavior in a multi page app is to redirect back with 302 and make the validation $errors available for the template.

We like that for the cases when JS is disabled, however, when making requests with HTMX we want to modify this.

// app/Http/Controllers/ChirpController.php

/**
     * Update the specified resource in storage.
     */
    public function update(Request $request, Chirp $chirp): RedirectResponse|Response
    {
        $this->authorize('update', $chirp);

        try {
            $validated = $request->validate([
                'message' => 'required|string|max:255',
            ]);

            $chirp->update($validated);

            if($request->header('HX-Request')) {
                return response()->view('components.chirps.single', [
                    'chirp' => $chirp,
                ]);
            }

            return redirect(route('chirps.index'));
        } catch (ValidationException $e) {
            if(!$request->header('HX-Request')) {
                throw $e;
            }

            return response()->view('components.chirps.edit', [
                'chirp' => $chirp,
                'errors' => collect($e->errors()),
            ]);
        }

What we did here is we wrapped everything in a try/catch statement and caught the ValidationException. Then, if this is not an HTMX request, we throw it back and leave Laravel to handle it (no JS case).

If it's an HTMX request, we return the edit form, and we make the $e->errors() available to the template in a collection. The HTMX behavior if this form is to replace itself with the HTML from the response.

Give it a try!

The Create Chirp Form

The create chirp form is a bit more complicated because we target the #chirps div with the response instead of itself. For this, we will take advantage of the out of band swaps (OOB) in HTMX.

This means that those elements marked with hx-swap-oob="true" won't follow the normal hx-swap but it will match the elements by ID and swap them. There is one rule, the OOB elements in the response must be at the root level, but this works just fine for our case.

Let's start by extracting the create chirp form into a component and add and ID and the OOB property.

<!-- resources/views/components/chirps/create.blade.php -->

@props(['oob' => true])

<form
    id="chirps-create"
    @if($oob)
        hx-swap-oob="true"
    @endif
    method="POST"
    action="{{ route('chirps.store') }}"
    hx-post="{{ route('chirps.store') }}"
    hx-target="#chirps"
    hx-swap="afterbegin"
    hx-on="htmx:afterRequest: if(event.detail.successful) this.reset();"
>
    @csrf
    <textarea
        name="message"
        placeholder="{{ __('What\'s on your mind?') }}"
        class="block w-full border-gray-300 focus:border-indigo-300 focus:ring focus:ring-indigo-200 focus:ring-opacity-50 rounded-md shadow-sm"
    >{{ old('message') }}</textarea>
    <x-input-error :messages="$errors->get('message')" class="mt-2" />
    <x-primary-button class="mt-4">{{ __('Chirp') }}</x-primary-button>
</form>

Replace the old form in the index template with this new component

<!-- resources/views/chirps/index.blade.php -->

<!-- Just below the search form, replace the old create form with the new component -->

<x-chirps.create :oob="false"></x-chirps.create>

Now let's do the same with the store method on the chirps controller, let's wrap it with a try/catch and if we have HTMX request and we have errors, we render the form component only.


/**  
 * Store a newly created resource in storage. 
 **/
 public function store(Request $request): RedirectResponse|Response  
{  
    try {  
        $validated = $request->validate([  
            'message' => 'required|string|max:255',  
        ]);  

        $chirp = $request->user()->chirps()->create($validated);  

        if ($request->header('HX-Request')) {  
            return response()->view('components.chirps.single', [  
                'chirp' => $chirp,  
            ]);  
        }  

        return redirect()->route('chirps.index');  
    } catch (ValidationException $e) {  
        if (!$request->header('HX-Request')) {  
            throw $e;  
        }  

        return response()->view('components.chirps.create', [  
            'errors' => collect($e->errors()),  
        ]);  
    }  
}

And that's all, now if you try to create a new chirp without a message, you will see the validation error.

However, there is a problem. If you successfully create a new chirp while having a validation error, the validation error persists, let's fix that!

We can add the form in the single chirp template, but we don't need to add it always, but only when we want.

<!-- resources/views/components/chirps/single.blade.php -->

<!-- At the top of the template -->

@props(['chirp', 'withCreateForm' => false])

@if($withCreateForm)
    <x-chirps.create></x-chirps.create>
@endif

The $withCreateForm prop, we can control if we want to also render the create form, usually we don't so we set false as a default.

In the store method on the chirp controller, if we are successful, we return the single chirp template with the create form:

// app/Http/Controllers/ChirpController.php

if ($request->header('HX-Request')) {
    return response()->view('components.chirps.single', [
        'chirp' => $chirp,
        'withCreateForm' => true,
    ]);
}

And on the create form, we can drop the hx-on script, because now we reset it by replacing the whole <div>

Confirmation Dialog

On our current implementation, when you want to delete a chirp, you just delete it. To make it safer for the users, we can add a confirmation dialog. HTMX comes with a hx-confirm attribute that takes advantage of the browser confirmation dialogs.

<!-- resources/views/components/chirps/single.blade.php -->

 <form method="POST"
      action="{{ route('chirps.destroy', $chirp) }}"
      hx-delete="{{route('chirps.destroy', $chirp)}}"
      hx-target="closest .chirp"
      hx-swap="delete"
      hx-confirm="Are you sure you want to delete this chirp?"
>

Now when you delete a chirp the browser asks you if you are sure about this before deleting. However, this is not the best user experience possible, we want to render HTML modals.

To do so, we will need to first create a new component:

<!-- resources/views/components/chirps/confirm-destroy.blade.php -->

@props(['chirp'])  

<div class="modal fixed z-10 inset-0 overflow-y-auto flex justify-center items-center bg-black bg-opacity-50" style="backdrop-filter: blur(14px);">  
    <div class="bg-white rounded p-6">  
        <h2 class="text-xl border-b pb-2 mb-2">Confirm Action</h2>  
        <p>Are you sure you want to delete this chirp?</p>  
        <div class="flex justify-end mt-4 gap-4">  
            <x-secondary-button _="on click remove closest .modal" >
                Cancel
            </x-secondary-button>  
            <form>                
                @csrf  
                <x-danger-button  
                    hx-delete="{{route('chirps.destroy', $chirp)}}"  
                    hx-target="closest .chirp"  
                    hx-swap="delete">  
                        Delete  
                </x-danger-button>  
            </form>
        </div>    
    </div>
</div>

This will render a dialog modal with a title and some content and two buttons.

The cancel button will just delete the closest .dialog from the DOM using Hyperscript
The second will make a delete request, and it will delete the closest .chirp from the DOM on success. Note that we had to wrap it in a <form> to include the @csrf blade attribute to render the CSRF hidden input.

Now we need a new method on the chirps controller to render this dialog

// app/Http/Controllers/ChirpController.php

public function confirmDestroy(Chirp $chirp): Response
{
    return response()->view('components.chirps.confirm-destroy', [
        'chirp' => $chirp,
    ]);
}

And we need to add it on the routes

// routes/web.php

Route::get('chirps/pool', [ChirpController::class, 'pool'])->name('chirps.pool');
Route::get('chirps/{chirp}/confirm-destroy', [ChirpController::class, 'confirmDestroy'])
    ->name('chirps.confirm-destroy');
Route::resource('chirps', ChirpController::class)
    ->only(['index', 'show', 'store', 'edit', 'update', 'destroy'])
    ->middleware(['auth', 'verified']);

And we need to modify the single chirp template, that when we click on the delete button, it will get the dialog and insert it in the DOM rather than deleting the chirp.


<!-- resources/views/components/chirps/single.blade.php -->

<form method="POST"  
      action="{{ route('chirps.destroy', $chirp) }}"  
      hx-delete="{{route('chirps.destroy', $chirp)}}"  
      hx-target="closest .chirp"  
      hx-swap="delete"  
>  
    @csrf  
    @method('delete')  
    <x-dropdown-link  
        :component="'button'"  
        type="submit"  
        hx-get="{{ route('chirps.confirm-destroy', $chirp) }}"  
        hx-swap="beforeend"  
        hx-target="closest .chirp"  
    >  
        {{ __('Delete') }}  
    </x-dropdown-link>  
</form>

We also deleted the hx-confirm attribute on the form. We kept the old delete form here to remain usable when the JS is disabled.

The only missing piece is some animations to make the user experience better, so let's define two custom animations in tailwind:

// tailwind.config.js

extend: {  
    fontFamily: {  
        sans: ['Figtree', ...defaultTheme.fontFamily.sans],  
    },  
    animation: {  
        'fade-in': 'fade-in 0.2s ease-out',  
        'fade-out': 'fade-out 0.2s ease-out',  
    },  
    keyframes: {  
        'fade-in': {  
            '0%': { opacity: '0' },  
            '100%': { opacity: '1' },  
        },  
        'fade-out': {  
            '0%': { opacity: '1' },  
            '100%': { opacity: '0' },  
        },  
    }  
},

And modify the confirm-destroy template to make use of Hyperscript to animate the modal:


<!-- resources/views/components/chirps/confirm-destroy.blade.php -->

@props(['chirp'])

@props(['chirp'])  

<div  
    _="on closeModal(destroy)  
            add .animate-fade-out            
            then wait for animationend            
            then if destroy remove closest .chirp else remove me        
        end        
            on click if (event.target == event.currentTarget) trigger closeModal"    
        class="modal fixed z-10 inset-0 overflow-y-auto flex justify-center items-center bg-black bg-opacity-50 animate-fade-in"  
        style="backdrop-filter: blur(14px);">  
    <div class="bg-white rounded p-6">  
        <h2 class="text-xl border-b pb-2 mb-2">Confirm Action</h2>  
        <p>Are you sure you want to delete this chirp?</p>  
        <div class="flex justify-end mt-4 gap-4">  
            <x-secondary-button _="on click trigger closeModal" >Cancel</x-secondary-button>  
            <form>                @csrf  
                <x-danger-button  
                    hx-delete="{{route('chirps.destroy', $chirp)}}"  
                    hx-target="closest .chirp"  
                    hx-swap="none"  
                    _="on htmx:afterRequest trigger closeModal(destroy:true)"  
                    >  
                        Delete  
                </x-danger-button>  
            </form>        
        </div>    
    </div>
</div>

First of all, on the parent div, we added the .animate-fade-in class that will animate when inserted into dom.

Clicking on the buttons, when we click on cancel button a custom closeModal event is dispatched. Also, we changed the hx-swap to none when deleting, and translated the htmx:afterRequest into a closeModal with destroy set to true.

We also added quite some chunk of Hyperscript on the parent div:

on closeModal(destroy)  
    add .animate-fade-out            
    then wait for animationend            
    then if destroy remove closest .chirp else remove me        
end        
    on click if (event.target == event.currentTarget) trigger closeModal

This instructs Hyperscript to listen for closeModal events and:

Add the animate-fade-out class to animate it out
wait for the animationend event, or in English, wait for animation to end
if destroy is truthful, then we delete the parent chirp, otherwise we delete only the dialog

The second part of the script instructs Hyperscript to trigger a closeModal on itself if the target is the currentTarget, thus closing the modal when clicking on the background.

Thus adding some nice fade in and out animations for the dialog.

The conclusion

Over the course of these tutorials, we've journeyed through the process of creating a dynamic, real-time application using a blend of Laravel, HTMX, and Hyperscript, culminating in a functional Chirper platform. These technologies have facilitated a modern, interactive user experience without the overhead typically associated with heavy front-end frameworks.

In part one, we laid the groundwork by setting up the Laravel application, defining the necessary routes, controllers, and views. The Chirper platform began to take shape as we created a simple interface for users to post chirps.

Part two saw the introduction of real-time functionality through HTMX, allowing users to see new chirps as they are posted by others, without needing to refresh the page. This was a key step in enhancing the user interaction and making the platform more engaging.

In the final part, we delved deeper into enhancing user experience by implementing a full-text search functionality, refining form validation, and introducing a user-friendly confirmation dialog for chirp deletion. These enhancements were aimed at making the platform more robust, user-friendly, and ready for real-world use.

The live version of the Chirper project can be explored at https://chirper.tlaurentiu.net. For those interested in the code behind the platform, the entire project is available on GitHub: https://github.com/turculaurentiu91/chirper-htmx. This project serves as a practical example of how modern web technologies can be leveraged to build interactive, real-time applications with a minimal front-end footprint.

This tutorial series demonstrates not only the technical steps required to build such a platform but also the thought process and decision-making involved in choosing technologies and implementing features. It's a glimpse into the possibilities that open up when blending server-side frameworks like Laravel with client-side libraries like HTMX and Hyperscript.

We hope this series has been informative and inspiring, encouraging you to explore these technologies and perhaps integrate them into your future projects.

Laravel + HTMX = ❤️ 2x

Turcu Laurentiu — Sat, 07 Oct 2023 08:41:33 +0000

In this exciting second installment of our tutorial series, we will venture further into the realm of modern web application development with Laravel and HTMX. Our main focus will be on enriching the user experience on the index page by introducing real-time updates for new chirps. Initially, we'll employ a polling strategy to fetch fresh chirps at regular intervals. As we progress, we'll transition from polling to a more dynamic and efficient approach using Web-Sockets, ensuring that new chirps are displayed to users as they are posted, in real time.

If you didn't already, checkout the first part of this tutorial. You can also checkout the full implementation on this GitHub repository.

Real-Time Updates: The Polling Edition

So far, our simple HTMX implementation has been working smoothly, and users are chirping away happily. However, the product owner has pointed out a less than ideal user experience: to view new chirps, users need to manually refresh the page. In response to this feedback, we'll be implementing a polling mechanism using HTMX to fetch new chirps from the server periodically.

Let's begin by creating a new controller action to handle the polling request:


// app/Http/Controllers/ChirpController.php

public function pool(Request $request): Response  
{  
    $validated = $request->validate([  
        'latest_from' => 'required|date',  
    ]);  

    $chirps = Chirp::with('user')  
        ->where('created_at', '>', $validated['latest_from'])  
        ->where('user_id', '!=', $request->user()->id)  
        ->latest()  
        ->get();  

    if($chirps->count() === 0) {  
        return \response()->noContent();  
    }  

    return \response()->view('chirps.pool', [  
        'chirps' => $chirps,  
    ]);  
}

In this action:

We validate the input to ensure latest_from is a properly formatted date.
We query the database for chirps that are newer than the latest_from date, excluding chirps from the current user.
If no new chirps are found, we return a 204 No Content response. Otherwise, we render the chirps.pool template.

Now, let's adjust the chirps.index template to include a new div responsible for polling new chirps from the server:


<!-- resources/views/chirps/index.blade.php -->

<div x-data="{noscriptFix: true}" id="chirps" class="mt-6 bg-white shadow-sm rounded-lg divide-y">  
    <div hx-get="{{ route('chirps.pool', ['latest_from' => $chirps->first()->created_at->toISOString()]) }}"  
         hx-trigger="every 2s"  
         hx-swap="outerHTML"></div>

    @foreach ($chirps as $chirp)  
        <x-chirps.single :chirp="$chirp" />  
    @endforeach  

    @if($chirps->nextPageUrl())  
        <div  
            hx-get="{{ $chirps->nextPageUrl() }}"  
            hx-select="#chirps>div.chirp,#chirps>div.chirps-paginator"  
            hx-swap="outerHTML"  
            hx-trigger="intersect"  
            x-cloak  
            x-if="noscriptFix"  
            class="chirps-paginator"  
>  
            Loading more...  
        </div>  
    @endif

We also updated the way paginator work, to select only the chirps and the .chirps-paginator div so we don't include the pooling element twice. We only need one pooling div, at the top of the list.

Additionally, we'll need to create a new template, chirps.pool, which will return the new chirps along with a self-replacing div to continue the polling:


<!-- resources/views/chirps/pool.blade.php -->

<div hx-get="{{ route('chirps.pool', ['latest_from' => $chirps->first()->created_at->toISOString()]) }}"  
     hx-trigger="every 2s"  
     hx-swap="outerHTML"></div>  

@foreach($chirps as $chirp)  
    <x-chirps.single :chirp="$chirp" />  
@endforeach

Note the duplicated div that pools, you can abstract in a component if you wish to be DRY

In essence, we instruct HTMX to send a GET request every two seconds to the chirps.pool route. If new chirps are found, HTMX will replace the entire content of the polling div with the new chirps and a fresh polling div, ensuring that the polling continues with the updated latest_from date.

This mechanism efficiently delivers real-time updates to our users without requiring a page refresh, significantly enhancing the user experience on our platform.

Real-Time Updates: Introducing Web Sockets

For simple updates like this pooling might be just enough, and you can optimize a bit further by increasing the pool time to five seconds or more. But let's pretend that some users lamented that with the new update, the website it's consuming their data plan and it's draining their battery, so our PO comes around and asks us for a more optimal solution.

Broadcasting events with Laravel

Laravel has a nice an easy way to broadcast events via web-sockets. The only problem in using it with HTMX is that you communicate with JSON rather than with HTML, and thus we are stranding away from the concept of HATEOAS (Hypermedia as the Engine of Application State).

We can make it work with Laravel events and HTMX web-sockets extension by rendering the HTML string in some field in the event JSON on the back-end, and on the front-end we can register an event listener for htmx:wsBeforeMessage and transform the event in such a way that event.detail.message contains only the HTML string.

But this is complicated, and if I like something, I like simple and straightforward approaches. So what we are going to do is:

We are going to use Laravel ECHO to receive the web-socket broadcast events
When we receive the events, we translate in a custom browser event chirper:newChirp
We fetch new chirps via HTMX when the event fires, preferably debounced

I will use soketi for this, but you can use whatever you want. I will not include instructions on how to setup Laravel, you can follow the official documentation

We will reuse the chirps/pool endpoint and template, we will have to modify the template a little bit


<!-- resources/views/chirps/pool.blade.php -->

<div  
    hx-trigger="chirper:chirpCreated throttle:500 from:body"  
    hx-get="{{ route('chirps.pool', ['latest_from' => $chirps->first()->created_at->toISOString()]) }}"  
    hx-swap="outerHTML"  
    ></div>  

@foreach($chirps as $chirp)  
    <x-chirps.single :chirp="$chirp" />  
@endforeach

We basically changed the trigger from every 2s to chirper:chirpCreated throttle:500 from:body, meaning that every type there is an chirp-created event triggered on body, throttle for 500ms and then get the data.

Make sure you do the same change for chirps/index.blade.php

In the resources/js/app.js ( make sure you have Echo configured according to your setup)

    laravelEcho.channel('chirps')  
    .listen('ChirpCreated', (event) => {  
        document.body.dispatchEvent(new CustomEvent('chirper:chirpCreated'));  
    }  
);

This bit of JS will convert the ChirpCreated event from the chirps channel to a CustomEvent on the body of the document.

And in the PHP part of the app, we need to make the ChirpCreated event to implement ShouldBroadcast and specify the channel it should broadcast, namely chirps

<?php  

namespace App\Events;  

use App\Models\Chirp;  
use Illuminate\Broadcasting\Channel;  
use Illuminate\Broadcasting\InteractsWithSockets;  
use Illuminate\Broadcasting\PresenceChannel;  
use Illuminate\Broadcasting\PrivateChannel;  
use Illuminate\Contracts\Broadcasting\ShouldBroadcast;  
use Illuminate\Foundation\Events\Dispatchable;  
use Illuminate\Queue\SerializesModels;  

class ChirpCreated implements ShouldBroadcast  
{  
    use Dispatchable, InteractsWithSockets, SerializesModels;  

    /**  
     * Create a new event instance.     
     * */    
     public function __construct(public Chirp $chirp)  
    {  
    }  

    /**  
     * Get the channels the event should broadcast on.     
     *     
     * @return array<int, Channel>  
     */    
     public function broadcastOn(): array  
    {  
        return [  
            new Channel('chirps'),  
        ];  
    }  
}

And that should be it. Now we only fetch the chirps when a new chirp is created. You can have a more advanced solution where you broadcast to private channels and broadcast toOthers but it's just fine for the scope of this tutorial.

P.S. I will not deploy the web-sockets on my test server, it's a hustle to deploy soketi and to setup nginx and such, so it will just showcase the pooling version. No For the next sections, we will start from the end of the pooling section.

Scripting

Now, with real-time updates, the page refreshes itself with new chirps from the server. However, a challenge arises when a user scrolls down to read older chirps—they won't be aware of new chirps inserted at the top of the page.

A solution is to introduce a floating button whenever new chirps are inserted. This button, when clicked, will scroll the page to the top, making the user aware of the new chirps.

Scripting is essential for implementing this feature. While HTMX provides the hx-on attribute which could be sufficient for simpler tasks like resetting a form, our scenario requires an intersection observer to remove the button when the user scrolls to the top—either manually or by clicking the button.

Here's where Hyperscript comes into play. Hyperscript is designed to simplify event-based scripting in the browser, making it more human-readable. Although we won't delve deeply into its syntax, feel free to explore it on their website.

Next, we'll walk through the steps to integrate Hyperscript and implement the floating button feature to enhance user awareness of new chirps.

We need to install the script, so in the app layout, after the HTMX script, we add another script:

<!-- resources/views/layouts/app.blade.php -->

<script src="https://unpkg.com/htmx.org@1.9.6" integrity="sha384-FhXw7b6AlE/jyjlZH5iHa/tTe9EpJ1Y55RjcgPbjeWMskSxZt1v9qkxLJWNJaGni" crossorigin="anonymous"></script>  
<script src="https://unpkg.com/hyperscript.org@0.9.11"></script>

In the chirps pool template we add the following HTML, above the new chirps foreach

<!-- resources/views/chirps/pool.blade.php -->

<div 
     class="border-transparent opacity-0"   
    _="on intersection(intersecting) if intersecting remove me else remove .opacity-0" >
    <div class="fixed top-4 left-0 right-0 flex justify-center">  
        <button            
            _="on click window.scrollTo({ top: 0, behavior: 'smooth' })"  
            type="button"  
            class="py-2 px-4 bg-indigo-600 hover:bg-indigo-800 rounded-full text-white shadow-lg flex justify-center items-center gap-4"  
        >  
            <svg xmlns="http://www.w3.org/2000/svg" 
                fill="none" 
                viewBox="0 0 24 24" 
                stroke-width="1.5" 
                stroke="currentColor" 
                class="w-6 h-6">  
                <path 
                    stroke-linecap="round" 
                    stroke-linejoin="round" 
                    d="M12 19.5v-15m0 0l-6.75 6.75M12 4.5l6.75 6.75" />  
            </svg>  
            Bew Chirps  
        </button>  
    </div>
</div>

This peace of HTML consists in two wrapper <div> elements, one to position the element in the list and another one to fix the button position at the top of the page.

The parent <div> element has an interesting attribute, _="on intersection(intersecting) if intersecting remove me else remove .opacity-0". This will instruct Hyperscript to install an intersection observer for this div, that on intersection, if is intersecting, to remove the element otherwise remove the opacity-0 class. So when the user scrolls to the top ether naturally or by clicking on the button, it will disappear.

The opacity is to avoid the button flickering on the screen when the user is already at the top of the page.

On the <button> element, we also have an Hyperscript attribute _="on click window.scrollTo({ top: 0, behavior: 'smooth' })" that will scroll the page to the top. It's the same as onclick="window.scrollTo({ top: 0, behavior: 'smooth' })"

You can do more advanced scripting with Hyperscript, you can insert classes, you can wait for animations, etc. etc.

As a homework, I encourage you to look at the documentation, and insert a slide down animation when the button is inserted and add a slide-up animation before the button is removed.

And that's all, now when the pooling gets new chirps, it will also insert the button and inform the user about the button presence.

Conclusion

We've come a long way in transforming Chirper from a simple Blade project to a modern web app with real-time updates and a user-friendly notification system. Leveraging HTMX and Hyperscript, we were able to enhance our application with infinite scrolling and web sockets, all while keeping the implementation straightforward and readable. Our journey highlights the power and simplicity these libraries bring to the table, enabling us to build dynamic features with less complexity compared to heavier frameworks.

Our exploration doesn't end here. We've merely scratched the surface of what's possible with HTMX, Hyperscript, and Laravel. As we move forward, we'll continue to refine our application, ensuring it not only meets our users' needs but also provides a delightful user experience.

What's Next?

In the upcoming third part of this series, we'll dive into implementing an active search functionality to help users easily find specific chirps. We'll also focus on enhancing the robustness of our application by utilizing Laravel's validation features to display form errors, ensuring a smooth and informative user interaction. Furthermore, we'll add a layer of confirmation dialogs for deleting chirps, providing a safer user experience and minimizing accidental data loss.

Through these enhancements, we aim to make Chirper a more interactive, user-friendly, and robust platform. So, stay tuned for more insights and practical implementations in the next installment of our journey with Chirper!

In the meantime, feel free to explore and experiment with the code we've built so far. There's a lot to learn and a myriad of ways to further refine and expand upon what we've created. Until next time, happy coding!

Laravel + HTMX = ❤️

Turcu Laurentiu — Tue, 03 Oct 2023 16:10:53 +0000

Enhancing Chirper: A Journey from Blade to a Modern Web App

In this article, we are going to explore how we can utilize HTMX alongside Laravel to modernize the Laravel Bootcamp Chirper blade project. As a primer, feel free to explore the live implementation at chirper.tlaurentiu.net to get a hands-on feel of what we'll be delving into.
If you don't wish to register, you can access it with my credentials (turculaurentiu91@gmail.com | password )
Our aim is to convert this project into a modern web app by integrating HTMX

Along the way, we'll delve into advanced techniques to introduce features like active search, infinite scrolling, and real-time updates for the page when new elements are created by other users.

why HTMX?

Because I love it! Since I landed on their website and understood the simplicity it can bring on a web developer life I can't stop thinking how almost everything we do on the web with React (or other frameworks 🙂) can be ridiculously easy done with plain old HTML enhanced with HTMX.

Yes, you can achieve the same with HTTP API & React (or other frameworks 🙂).
Yes, you can achieve the same with Inertia.js
Yes, you can achieve the same with Livewire

But this tutorial is about HTMX and how easy it is to use. Think of it as just another tool in your toolbox that you can use to replace or use alongside of the above mentioned technologies.

This article is not about why you should use it, but how you can use it. But the gist of it is that is dead simple, and it keeps your apps simple. And simple is good!

If you want read more about the why, you can take a look at this other article.

Getting started

In order to follow along, you need to have completed the Laravel Bootcamp Chirper app using the blade templates. If you are familiar with Laravel and Blade and prefer not to go through that tutorial, you can clone my version of the solution (which replicates all the code from the bootcamp) from here: GitHub Repository. Be sure to check out the the-beginning branch, as the main branch contains the final solution.

The next step is to install HTMX. We can take two routes here:

Install it via npm, bundle it with Vite (a build tool that facilitates faster development).
Load the script via CDN in the header of your template.

Usually, the first option is preferable as it allows HTMX to be served by your infrastructure, enabling you to take advantage of HTTP/2 multiplexed streams. However, for the sake of simplicity in this tutorial, we will add it directly in the templates.

<!-- resources/views/layouts/app.blade.php -->

      <script src="https://unpkg.com/htmx.org@1.9.6" integrity="sha384-FhXw7b6AlE/jyjlZH5iHa/tTe9EpJ1Y55RjcgPbjeWMskSxZt1v9qkxLJWNJaGni" crossorigin="anonymous"></script>
</head>

So, we just added the script in the head from unpkg. That's all, we can now go and use it.

Boosting the navigation

If you open the application, login, and navigate between the Dashboard and the Chirps tab, you will notice that the whole page is reloaded with each navigation. This is where frameworks like React shine by enabling seamless navigation without page reloads. Now, let's see how we can achieve similar seamless navigation with HTMX, by taking advantage of the hx-boost attribute:

So let's see how we can achieve that with HTMX, by taking advantage of the hx-boost attribute:

<!-- resources/views/layouts/navigation.blade.php -->
<!-- Navigation Links -->  
<div class="hidden space-x-8 sm:-my-px sm:ml-10 sm:flex" hx-boost="true">  
    <x-nav-link :href="route('dashboard')" :active="request()->routeIs('dashboard')">  
        {{ __('Dashboard') }}  
    </x-nav-link>  
    <x-nav-link :href="route('chirps.index')" :active="request()->routeIs('chirps.index')">  
        {{ __('Chirps') }}  
    </x-nav-link>  
</div>

We added the hx-boost="true" to the parent div of the navigation links. What HTMX will do behind the scene is:

It will install an onClick event for the links.
It will prevent the default browser navigation.
It will do an AJAX request to the URL specified in the href attribute.
It will fetch the HTML document.
It will replace the <body> of the document with the content received in the request.
It will update the navigation URL to match the href attribute of the clicked anchior.

Now, when you click on the navigation links, the whole page will no longer reload, demonstrating the power and simplicity of HTMX.

HTMX attributes are inheritable, meaning that you can inherit attributes from ancestor elements. Note how we added the hx-boost attr. on the parent div of the navigation links. We can, in fact, we will move the attribute on the wrapper div of the whole page.

So we remove it from resources/views/layouts/navigation.blade.php and add it on the app layout

<!-- resources/views/layouts/app.blade.php -->
<body class="font-sans antialiased">  
    <div class="min-h-screen bg-gray-100" hx-boost="true">
    <!-- rest of the template -->

And so, we added the boost to all logged-in users. Now, whatever action the user takes—creating a chirp, editing, deleting, or interacting with any other forms—they will not trigger a whole page reload.

HOMEWORK: add the boost to the guest users, so the auth forms has the same boost.

Checkmate React, our job here is done. With one <script> tag and one HTML attribute we replaced react, react-router, redux, Axios and a couple of other js dependencies that you would install just because you can.

CSS Transitions

You might notice that the navigation links have a CSS transition property, but it only works when you hover to display the underline. When you click, the underline just pops into existence, which can be jarring. Let's smooth that out!

<!-- resources/views/layouts/navigation.blade.php -->  
<!-- Navigation Links -->  
<div class="hidden space-x-8 sm:-my-px sm:ml-10 sm:flex">  
    <x-nav-link id="dashboard-link" :href="route('dashboard')" :active="request()->routeIs('dashboard')">  
        {{ __('Dashboard') }}  
    </x-nav-link>  
    <x-nav-link id="chirps-link" :href="route('chirps.index')" :active="request()->routeIs('chirps.index')">  
        {{ __('Chirps') }}  
    </x-nav-link>  
</div>
    <!-- rest of the template -->

Yes, all we did was to add some ids on the links.

To apply a CSS transition to swapped content, it's essential to keep its IDs consistent across requests. Under the hood, HTMX will:

Swap the content,
Match the elements by ID,
Apply the existing properties (CSS classes in our case) to the new elements,
And after a brief pause of a few milliseconds (20), apply the new properties to these elements.

This sequence allows the CSS transitions to function smoothly, providing a visual cue to users as the active navigation link changes. Now, when you click on the navigation links, the underline will transition smoothly instead of just popping into existence, enhancing the user experience with a more polished, professional look.

By making this simple adjustment, we've improved the visual feedback to users as they navigate through the application, showcasing another aspect of the user-friendly enhancements HTMX can bring to a Laravel project.

For more detailed information on how CSS transitions are handled with HTMX, feel free to check out the HTMX documentation page on CSS transitions.

Enhancing the edit action

Imagine your Product Owner comes around and mentions disliking the redirection to another page when editing a chirp. He prefer that upon clicking the edit button, the chirp morphs into a form. On saving, it reverts back to a regular chirp displaying the updated content. Let’s delve into how we can achieve this.

The edit button

The goal is to convert the chirp into a form upon clicking the edit button. To do this, we'll create a Blade component that renders a chirp in edit mode.

<!-- resources/views/chirps/edit.blade.php -->

@props(['chirp'])  

<div hx-target="this" hx-swap="outerHTML">  
    <form 
        class="p-6 flex flex-col space-x-2" 
        hx-patch="{{ route('chirps.update', $chirp) }}"
     >  
        @csrf  
        <textarea  
            name="message"  
            class="block w-full border-gray-300 focus:border-indigo-300 focus:ring focus:ring-indigo-200 focus:ring-opacity-50 rounded-md shadow-sm"  
        >
            {{ old('message', $chirp->message) }}
        </textarea>  
        <x-input-error :messages="$errors->get('message')" class="mt-2" />  
        <div class="mt-4 space-x-2">  
            <x-primary-button>{{ __('Save') }}</x-primary-button>  
            <a class="cursor-pointer" 
            hx-get="{{ route('chirps.show', $chirp) }}"  
            >
                {{ __('Cancel') }}
            </a>  
        </div>    
    </form>
</div>

Here, we've created a new Blade component that renders the chirp form inline. The hx-target and hx-swap attributes on the wrapper div instruct HTMX to target this div (itself) and replace its outerHTML with the response contents for all requests within this div, thanks to HTMX's attribute inheritance.

On the <form> element and the cancel link, we've specified the request methods to be PATCH and GET respectively.

Updating the Controller

Now, let’s modify the update method in our controller to respond with the partial view if it's an HTMX request, maintaining the normal browser functionality when JavaScript is disabled for a progressively enhanced website.

// app/Http/Controllers/ChirpController.php

 public function update(Request $request, Chirp $chirp): RedirectResponse|Response  
{  
    $this->authorize('update', $chirp);  

    $validated = $request->validate([  
        'message' => 'required|string|max:255',  
    ]);  

    $chirp->update($validated);  

    if($request->header('HX-Request')) {  
        return response()->view('components.chirps.single', [  
            'chirp' => $chirp,  
        ]);  
    }  

    return redirect(route('chirps.index'));  
}

The Single Chirp Component

Now, let's discuss the single chirp component which we've extracted for reusability.

<!-- resources/views/components/chirps/single.blade.php -->

@props(['chirp'])  

<div class="p-6 flex space-x-2 chirp">  
    <svg 
        xmlns="http://www.w3.org/2000/svg" 
        class="h-6 w-6 text-gray-600 -scale-x-100" 
        fill="none" viewBox="0 0 24 24" 
        stroke="currentColor" 
        stroke-width="2">  
        <path 
            stroke-linecap="round" 
            stroke-linejoin="round" 
            d="M8 12h.01M12 12h.01M16 12h.01M21 12c0 4.418-4.03 8-9 8a9.863 9.863 0 01-4.255-.949L3 20l1.395-3.72C3.512 15.042 3 13.574 3 12c0-4.418 4.03-8 9-8s9 3.582 9 8z" />  
    </svg>    
    <div class="flex-1">  
        <div class="flex justify-between items-center">  
            <div>                
                <span class="text-gray-800">{{ $chirp->user->name }}</span>  
                <small class="ml-2 text-sm text-gray-600">
                    {{ $chirp->created_at->format('j M Y, g:i a') }}
                </small>  
                @unless ($chirp->created_at->eq($chirp->updated_at))  
                    <small class="text-sm text-gray-600"> 
                        &middot; {{ __('edited') }}
                    </small>  
                @endunless  
            </div>  
            @if ($chirp->user->is(auth()->user()))  
                <x-dropdown>  
                    <x-slot name="trigger">  
                        <button>                            
                            <svg 
                                xmlns="http://www.w3.org/2000/svg" 
                                class="h-4 w-4 text-gray-400" 
                                viewBox="0 0 20 20" 
                                fill="currentColor">  
                                <path d="M6 10a2 2 0 11-4 0 2 2 0 014 0zM12 10a2 2 0 11-4 0 2 2 0 014 0zM16 12a2 2 0 100-4 2 2 0 000 4z" />  
                            </svg>                        
                        </button>                   
                    </x-slot>                    
                    <x-slot name="content">  
                        <x-dropdown-link                          
                            :href="route('chirps.edit', $chirp)"  
                            hx-get="{{ route('chirps.edit', $chirp) }}"  
                            hx-target="closest .chirp"  
                            hx-swap="outerHTML"  
                        >  
                            {{ __('Edit') }}  
                        </x-dropdown-link>  
                        <form 
                            method="POST" 
                            action="{{ route('chirps.destroy', $chirp) }}">  
                            @csrf  
                            @method('delete')  
                            <x-dropdown-link 
                                :href="route('chirps.destroy', $chirp)" onclick="event.preventDefault(); this.closest('form').submit();">  
                                {{ __('Delete') }}  
                            </x-dropdown-link>  
                        </form>                    
                    </x-slot>                
                </x-dropdown>            
            @endif  
        </div>  
        <p class="mt-4 text-lg text-gray-900">{{ $chirp->message }}</p>  
    </div>
</div>

We've moved the chirp rendering code to a reusable Blade component. The HTMX attributes on the edit button ensure that a GET request is made to the edit endpoint, replacing the closest parent div with class chirp with the response markup.

Edit Chirp Partial/Component

Ensure that HTMX requests to the edit chirp endpoint receive only the edit chirp component, while other requests receive the whole page, aligning with the "progressive enhancement" pattern.

// app/Http/Controllers/ChirpController.php

public function edit(Request $request, Chirp $chirp): Response  
{  
    $this->authorize('update', $chirp);  

    if($request->header('HX-Request')) {  
        return response()->view('components.chirps.edit', [  
            'chirp' => $chirp,  
        ]);  
    }  

    return response()->view('chirps.edit', [  
        'chirp' => $chirp,  
    ]);  
}

Now, update the index layout to utilize the single chirp component and implement the view endpoint of the single chirp.

<!-- resources/views/chirps/index.blade.php -->

<div class="mt-6 bg-white shadow-sm rounded-lg divide-y">  
    @foreach ($chirps as $chirp)  
        <x-chirps.single :chirp="$chirp" />  
    @endforeach  
</div>

public function show(Chirp $chirp): Response  
{  
    return response()->view('components.chirps.single', [  
        'chirp' => $chirp,  
    ]);  
}

Don't forget to add the new endpoint to routes.php.

Review

Let's review the flow:

Clicking the edit button triggers a GET request to chirps/{chirp}/edit, replacing the parent div with class chirp with the response markup from the components/chirps/edit partial template.
Clicking the cancel link on the form triggers a GET request to chirps/{chirp}, replacing the wrapper div element with the content of the response, i.e., the partial markup of the single chirp element.
Submitting the edit form triggers a PATCH request to chirps/{chirp} endpoint, updating the chirp and replacing the wrapper div element with the markup of the single chirp, the edited one.

With the HX-Request header, we've maintained normal browser functionality in case JavaScript is disabled, embodying the principle of progressive enhancement. Our application remains server-side rendered, fast, and simple, with a significantly enhanced user experience.

PS: Note that the validation isn't working currently; we'll address this later in the tutorial.

Through these steps, we've seamlessly integrated HTMX to enhance the edit action in our Laravel application, providing a more intuitive and interactive user experience without the need for complex front-end frameworks.

Enhancing the create action.

The create action can be enhanced by making two key changes:

Modifying the store action to return the single chirp during an HTMX request.
Injecting the single chirp markup at the beginning of the chirps list.

Let’s delve into these steps:

Updating the Store Action

Update the store method in ChirpController to return the partial view of a single chirp when an HTMX request is detected:

// app/Http/Controllers/ChirpController.php

public function store(Request $request): RedirectResponse|Response  
{  
    $validated = $request->validate([  
        'message' => 'required|string|max:255',  
    ]);  

    $chirp = $request->user()->chirps()->create($validated);  

    if($request->header('HX-Request')) {  
        return response()->view('components.chirps.single', [  
            'chirp' => $chirp,  
        ]);  
    }  

    return redirect()->route('chirps.index');  
}

Modifying the Index Template

In the chirps.index template, update the form element by adding HTMX attributes, instructing it to insert the response at the top of the chirps list (afterbegin). Also, add an ID to the chirps list div for targeting:

<form  
    method="POST"  
    action="{{ route('chirps.store') }}"  
    hx-post="{{ route('chirps.store') }}"  
    hx-target="#chirps"  
    hx-swap="afterbegin"  >

<!-- rest of the template -->

<div id="chirps" class="mt-6 bg-white shadow-sm rounded-lg divide-y">

Handling Form Reset

You may notice that the textarea content remains unchanged even after a successful request. To enhance user experience, let's reset the form upon a successful submission using the hx-on attribute:

<form  
    method="POST"  
    action="{{ route('chirps.store') }}"  
    hx-post="{{ route('chirps.store') }}"  
    hx-target="#chirps"  
    hx-swap="afterbegin"  
    hx-on="htmx:afterRequest: if(event.detail.successful) this.reset();"  
>

Here, we've used the hx-on attribute to bind a script to the htmx:afterRequest event, which HTMX triggers after each request. We check whether the request was successful using event.detail.successful, and if so, we reset the form using this.reset().

And there you have it! We’ve significantly enhanced the create method.

Note: The validation is not yet functioning correctly, but we'll address this issue later in the tutorial.

These steps demonstrate how we've seamlessly integrated HTMX to improve the create action in our Laravel application, providing a better user experience without adding complexity to the Front-end.

Handling Delete Action

The delete action is relatively straightforward. We can respond with an empty string for a successful delete HTMX request, instructing HTMX to remove the item from the DOM. For non-HTMX requests, the behavior remains unchanged.

Updating the Destroy Method

Modify the destroy method in ChirpController to return an empty string during an HTMX request, and to redirect to the chirps.index route otherwise.

public function destroy(Request $request, Chirp $chirp): RedirectResponse|string  
{  
    $this->authorize('delete', $chirp);  

    $chirp->delete();  

    if($request->header('HX-Request')) {  
        return '';  
    }  

    return redirect(route('chirps.index'));  
}

Modifying the Dropdown-Link Component

The current implementation in Laravel Bootcamp Chirper has a <x-dropdown-link> component that always renders a link. To ensure it works even with JavaScript disabled, modify it to render a button instead, like so:

<!-- resources/views/components/dropdown-link.blade.php -->

@props(['component' => 'link'])  

@if ($component === 'link')  
    <a {{ $attributes->merge(['class' => 'block w-full px-4 py-2 text-left text-sm leading-5 text-gray-700 hover:bg-gray-100 focus:outline-none focus:bg-gray-100 transition duration-150 ease-in-out']) }}>{{ $slot }}</a>  
@else  
    <button {{ $attributes->merge(['class' => 'block w-full px-4 py-2 text-left text-sm leading-5 text-gray-700 hover:bg-gray-100 focus:outline-none focus:bg-gray-100 transition duration-150 ease-in-out']) }}>{{ $slot }}</button>  
@endif

here I shamelessly copied the classes around and not used a variable to be more DRY

Adjusting the Single Chirp Component

Now, update the single chirp component to utilize the modified <x-dropdown-link> and adjust the form to execute a delete request, removing the chirp from the DOM upon request completion.


<!-- resources/views/components/chirps/single.blade.php -->

<form method="POST"  
      action="{{ route('chirps.destroy', $chirp) }}"  
      hx-delete="{{route('chirps.destroy', $chirp)}}"  
      hx-target="closest .chirp"  
      hx-swap="delete"  
>  
    @csrf  
    @method('delete')  
    <x-dropdown-link  
        :component="'button'"  
        type="submit">  
        {{ __('Delete') }}  
    </x-dropdown-link>  
</form>

Now, a submit button is rendered as a dropdown-link, and the form is adjusted to make a delete request, removing the chirp from the DOM upon request completion.

While it's noted that the dropdown link now leverages Alpine.js and may not function without JavaScript, addressing this falls outside the scope of this tutorial. The focus here is on showcasing the HTMX integration to handle delete actions seamlessly.

Implementing Infinite Scrolling

Let's first generate additional chirps using Laravel's factory and seeder functionality:

php artisan make:factory ChirpFactory --model Chirp

<?php  

namespace Database\Factories;  

use App\Models\Chirp;  
use Illuminate\Database\Eloquent\Factories\Factory;  

/**  
 * @extends Factory<Chirp>  
 */  
class ChirpFactory extends Factory  
{  
    /**  
     * Define the model's default state.     
     *     
     * @return array<string, mixed>  
     */    
     public function definition(): array  
    {  
        $created_at = $this->faker->dateTimeBetween('-2 months');  

        return [  
            'message' => $this->faker->sentence,  
            'created_at' => /* somewhere in the past two months */ $created_at,  
            'updated_at' => $this->faker->boolean() ? $this->faker->dateTimeBetween($created_at) : null,  
        ];  
    }  
}


// DatabaseSeeder.php

public function run(): void  
{  
    User::factory(20)->hasChirps(2000)->create();  
}

Now, run the seed command and go and grab a cup of coffee, this will take a while, we are generating 20 users with 2000 chirps each, so it will take a while.

php aritsan db:seed

Implementing Basic Pagination

To prevent page overload, implement basic pagination in the ChirpController:

// app/Http/Controllers/ChirpController.php

public function index(): Response  
{  
    $chirps = Chirp::with('user')->latest()->paginate(25);  

    return \response()->view('chirps.index', [  
        'chirps' => $chirps  
    ]);  
}

Display pagination links in chirps.index:

<!-- resources/views/chirps/index.blade.php -->

<noscript>  
    <div class="max-w-5xl mx-auto p-4 sm:p-6 lg:p-8">  
        {{ $chirps->links() }}  
    </div>  
</noscript>

Adding Infinite Scrolling

Utilize HTMX to implement infinite scrolling while retaining the pagination links as a fallback:

<!-- resources/views/chirps/index.blade.php -->

<div class="max-w-2xl mx-auto p-4 sm:p-6 lg:p-8">  
        <!-- rest of the template -->

        @foreach ($chirps as $chirp)  
            <x-chirps.single :chirp="$chirp" />  
        @endforeach  

        @if($chirps->nextPageUrl())  
            <div  
                hx-get="{{ $chirps->nextPageUrl() }}"  
                hx-select="#chirps>div"  
                hx-swap="outerHTML"  
                hx-trigger="intersect"  
            >  
                Loading more...  
            </div>  
        @endif  
    </div>  
</div>  

<noscript>  
    <div class="max-w-5xl mx-auto p-4 sm:p-6 lg:p-8">  
        {{ $chirps->links() }}  
    </div>  
</noscript>

Ensure x-cloak elements are hidden initially:

<!-- resources/views/layouts/app.blade.php -->

<style>  
    [x-cloak] { display: none !important; }  
</style>

It's called critical because it's loaded before the CSS file is downloaded, that's why you put it in the header and not in the CSS file

The HTMX attributes used in the infinite scrolling code snippet provide the necessary instructions to the browser on how to handle the loading of additional chirps as the user scrolls down the page. Let's break down these attributes:

hx-get="{{ $chirps->nextPageUrl() }}": This attribute instructs HTMX to issue a GET request to the URL specified, which in this case is the URL for the next page of chirps. This action is triggered when the user scrolls down and reaches the "Loading more..." div.
hx-select="#chirps>div": This attribute specifies what part of the returned content from the GET request should be used in the current page. In this case, it's selecting all direct div children of the element with the id #chirps. This will essentially select all the chirps returned in the next page of results.
hx-swap="outerHTML": This attribute specifies how to update the DOM with the selected elements from the GET request. The value outerHTML instructs HTMX to replace the "Loading more..." div entirely with the new content fetched from the server. This way, the newly loaded chirps get appended to the list, and the "Loading more..." div gets replaced by these new chirps.
hx-trigger="intersect": This attribute specifies when to trigger the GET request. The value intersect tells HTMX to trigger the request when the "Loading more..." div comes into view (i.e., when it intersects with the viewport). This is essentially what enables the infinite scrolling behavior, as new chirps are loaded each time the user scrolls down and reaches the end of the current list.
x-cloak: This is an Alpine.js directive, not an HTMX attribute. It's used to hide certain elements initially. When JavaScript is enabled, Alpine.js will remove the x-cloak attribute, making the element visible.

By utilizing these HTMX attributes and the Alpine.js directive, the code is set up to provide a seamless infinite scrolling experience while also having a fallback pagination system for users with JavaScript disabled. This way, the application maintains a good level of accessibility and usability across different user scenarios. How cool is that ?!?!?!

Conclusion

Throughout this tutorial, we've journeyed through enhancing a basic Laravel chirps application with progressively enhanced features utilizing HTMX. We started with simple refinements to form submissions, worked through editing and deleting chirps inline, and finally, implemented infinite scrolling to efficiently load and display a large number of chirps. Each enhancement aimed to provide a more interactive and user-friendly experience while retaining functionality without JavaScript, adhering to the principles of Progressive Enhancement.

The simplicity and power of HTMX shone through, allowing us to keep our code largely server-side, clean, and maintainable, while still offering a dynamic user experience. The transition from traditional server-rendered interactions to a more dynamic interface didn't require a complete rewrite or the introduction of complex client-side frameworks. This stands as a testament to how modern technologies can simplify the development process while adhering to good practices.

Up Next: Dive Deeper into Interactive Features

In the upcoming second part of this tutorial, we'll take our application to the next level by introducing more interactive and real-time features:

Spinners: Enhance the user experience by adding the loading indicator
Active Search: We'll explore how to implement an active search feature using MySQL full-text indexes to help users find chirps that interest them quickly.
Server-Side Validation: Addressing a loose end, we'll work on fixing the server-side validation to ensure data integrity and provide user feedback.
Real-Time Updates: Using the pooling method, we'll update our index page with new chirps in real-time, keeping the content fresh and engaging for our users.
Experiment with Server-Side Events: We'll take a shot at implementing server-side events to further enhance the real-time interactivity of our application.

The adventure continues as we delve deeper into creating a more interactive and real-time experience without sacrificing the simplicity and maintainability of our Laravel application. Stay tuned, and get ready to explore more ways to bring your Laravel applications to life!