DEV Community: Marcus

How to Load Content into a Bootstrap Offcanvas Component with HTMX and Save State as a Hash in the URL

Marcus — Sat, 25 Mar 2023 22:18:33 +0000

To open a Bootstrap Offcanvas Component and load some HTML fragment with HTMX, the first thing I tried was the following:

Equip the canvas (or modal) opener with the HTMX attributes
call it a day

<a class="btn btn-light" 
    href="/sidebar"
    hx-get="/sidebar" 
    hx-select=".bookmark-list" 
    hx-target=".offcanvas-body"
    data-bs-toggle="offcanvas"
    data-bs-target="#offcanvas">
    Open Sidebar
</a>

<div 
     id="offcanvas" 
     class="offcanvas offcanvas-start">
    <div class="offcanvas-body">
        Loading...
    </div>
</div>

This approach is completely decoupled; the click event triggers both the Bootstrap behavior and the HTMX ajax call. Both are unaware of one another.

If the canvas fails to open, the Ajax request may succeed, but the result cannot be viewed.

Back to the drawing board!

Connecting the behavior of HTMX and Bootstrap JS

The first thought is to use HTMX and listen for the 'htmx:load' event, then call .show() to open the Offcanvas component. That would necessitate some UI to indicate that the loading is complete before the canvas appears.

Or the other way around, listen to show.bs.offcanvas and then trigger htmx.ajax() to pull in the server-rendered HTML. This is better because it shows, something is happening right away.

Saving open state in the URL

That previous approach makes the button or link responsible for opening the canvas (or modal)?

If I navigate to /sidebar#offcanvas I want the sidebar to be open on page load with the HTMX ajax request triggered. The problem with this approach is, the button is the single source of truth that holds the URL that's getting loaded by HTMX via hx-get (or href).

I could go and htmx.find('a[href="/sidebar"]').href and then use that in the Ajax request. Or I trigger a click on the button, that triggers the behavior. But that seems weird and too tightly coupled.

document.addEventListener('DOMContentLoaded', function () {

    const el = '#offcanvas';
    let bookmarksOffcanvasInstance = bootstrap.Offcanvas.getOrCreateInstance(el);

    if(location.hash === '#offcanvas'){
        // open the sidebar
        bookmarksOffcanvasInstance.show();
        // find the button and make an
        // ajax call via 
        htmx.ajax('GET', htmx.find('a[href="/sidebar"]').href, {/* target etc */})

        // -- OR --

        htmx.trigger('a[href="/sidebar"]', "click");
    }
});

Make the Offcanvas component the single source of truth

There is another way I found by watching a video¹ about doing something similar with AlpineJS and an open issue with HTMX² that brought me to the following solution:

1. The button or link to open the sidebar is only responsible for that

<a class="btn btn-light" 
    href="/sidebar"
    data-bs-toggle="offcanvas"
    data-bs-target="#offcanvas">
    Open Sidebar
</a>

2. Tie the HTMX logic to the canvas itself and trigger a HTMX custom event

<div 
     id="offcanvas" 
     class="offcanvas offcanvas-start"
     hx-get="/sidebar" 
     hx-select=".sidebar" 
     hx-target=".offcanvas-body"
     hx-trigger="filter-event">
    <div class="offcanvas-body">
        Loading...
    </div>
</div>
</div>

<script>
const el = document.getElementById("offcanvas");

// after the canvas was opened, trigger the hx-get with
// the custom event and add the url with the state of the canvas
// into the history
el.addEventListener('shown.bs.offcanvas', event => {
    htmx.trigger(event.target, "filter-event");
    history.pushState(null, null, '#' + event.target.id);
})

// on hiding the sidebar, remove the hash
el.addEventListener('hide.bs.offcanvas', event => {
    history.pushState("", document.title, window.location.pathname);
})
</script>

See the Pen
Untitled by Marcus at Localhost (@localhorst)
on CodePen.

Now, all the information for the Ajax request is associated with the offcanvas component, and it does not matter what triggers the opening of the sidebar; everything is contained in a single location.

My initial thought probably stems from my synchronous consideration of requests. A click alters the appearance of another element after a page reload.

With JavaScript's asynchronous nature, this behavior is out the window.

Bonus: Offcanvas activated by AlpineJS that triggers HTMX custom event

I adopted the whole script for the AlpineJS inline JavaScript style and here it is:

<a class="btn btn-light" href="#offcanvas">
    Open Sidebar
</a>
<div 
    id="offcanvas" 
    class="offcanvas offcanvas-start"

    x-data
    x-init="()=>{
        const oc = new bootstrap.Offcanvas('#offcanvas');
        if(location.hash === '#offcanvas') oc.show();
    }"
    @hashchange.window="if(location.hash === '#offcanvas') { bootstrap.Offcanvas.getOrCreateInstance(location.hash).show() }"
    @shown-bs-offcanvas.dot="
        htmx.trigger($event.target, 'filter-event');
        history.pushState(null, null, '#' + $event.target.id);"
    @hide-bs-offcanvas.dot="history.pushState('', document.title, window.location.pathname);"

    hx-get="/sidebar" 
    hx-select=".sidebar" 
    hx-target=".offcanvas-body"
    hx-trigger="filter-event">

        <div class="offcanvas-body">
            Loading...
        </div>
</div>

<template url="/sidebar" delay="1500">
    <h2>Sidebar Headline only visible when /sidebar is directly requested</h2>
  <div class="sidebar">
        Sidebar
    </div>
</template>

A working Codepen can be found under https://codepen.io/localhorst/pen/RwYvWyE (log in, switch to debug mode to see that URL hash change).

What I like about this approach is, it's very compact. Everything is in one place. No snippets here and bits there. You look at the markup of that component and that's all there is. At least for this demo. At the same time, it's ugly, hard to format and as complexity grows you'll end up putting stuff in a dedicated script block or so.

I don't know if there is any need to add AlpineJS in the mix as a third abstraction of code.

It's a matter of style and maintenance I guess. But now I know how to listen for events from Bootstrap components (see the .dot modifier) in AlpineJS.

If you have correction or thoughts about it, please let me know. I don't claim, that's the way to do it. I just made it work that way.

Article How to Load Content into a Bootstrap Offcanvas Component with HTMX and Save State as a Hash in the URL on my blog.

Tailwind is a Leaky Abstraction by Jake Lazaroff

Marcus — Wed, 30 Nov 2022 15:48:34 +0000

Jake Lazaroff makes convincing arguments against using Tailwind CSS..

My main concern was always how unreadable the HTML became, regardless of whether I added line breaks between the class names or not.

https://jakelazaroff.com/words/tailwind-is-a-leaky-abstraction/

JSONPath with Alpine.js CSP build in Postman Visualizer

Marcus — Sat, 30 Apr 2022 20:47:42 +0000

Query JSON Response with JSON Path

To work more easily with Postman JSON results, I implemented JSONPath in a Postman Visualizer, to query the results.

JSONPath is to JSON what XPath is to XML, and it helps to get into large nested objects and find what you're looking for faster.

First I was using just a jQuery version that can be found in the examples and that worked just fine. (JSONpath Visualizer | Postman Team Collections | Postman API Network)

Then I thought this is a good opportunity of being a smart ass and implement it with Alpine.js, and it was just a mess—but I found out a few things.

The biggest roadblock was finding out about Postman's Content-Security-Policy that can't be changed, and it doesn't allow JavaScript in HTML attributes, something that happens in Alpine, behind the scenes.

alpinejs:5 Uncaught EvalError: Refused to evaluate a string as JavaScript because 'unsafe-eval' is not an allowed source of script in the following Content Security Policy directive: "script-src http: https: 'unsafe-inline'".

There is more insight on how Postman deals with CSP here: https://community.postman.com/t/render-pdf-in-visualizer/9193/4 and in this video: https://youtu.be/6ajkO9JETDs?t=275 - the short version is, Postman creates a html file in the temp directory and this files comes with CSP meta tags, that can't be overwritten, so one is stuck with it.

Fortunately, Alpine.js offers a version that works in a more restrictive environment. That version is not on a CDN and I had to build it myself. This forced me to update all the Node and NPM stuff, which was a total mess, but at the end, I got a working CSP version.

Of course, it's nicer to just link files from a CDN, so I created a gist and use https://raw.githack.com/ to serve the file from there.

The whole gist

How To:

Paste the following code into the "Test" area of Postman and fire up a call.

JSON Path with Alpine.js CSP build in Postman Visualizer by Marcus Obst

Handle JSON API Results in Htmx

Marcus — Tue, 02 Jun 2020 07:38:42 +0000

Htmx is a javascript library that "allows you to access AJAX, WebSockets and Server Sent Events directly in HTML, using attributes, so you can build modern user interfaces with the simplicity and power of hypertext."

In a former post I thought it was fun to compare Alpine.js to Vue.js and showed how similar their approaches are.

The promise of these libraries is: you keep writing HTML and just add javascript behaviors directly in the DOM where you need them. This is great to enhance existing projects or hook into CMS generated output. (And you don't want to build a React app or move an existing website to one.)

With the release of htmx, the slimmer and jquery-free sibling of intercooler.js, I thought it would be interesting to see how htmx compares to Alpine.js or Vue.js.

In short, it hardly compares - the approach is different, even if Alpine.js claims to enhance HTML by sprinkling in javascript.

Htmx simplifies dealing with ajax and updating HTML fragments in the source document. You keep writing HTML and leave the ajax operations to htmx.

<div 
  hx-post="/clicked"
  hx-trigger="click"
  hx-target="#parent-div"
  hx-swap="outerHTML">
  Click Me!
</div>

It comes with a whole set of HTTP headers so you can react on the requests on the server-side and generally, it wants you to serve rendered html back to the client and do the heavy work on the server and not in the client.

I really like this approach, but there are times where you have to deal with data on the client-side, like requesting an API directly and render the results in HTML.

Htmx lets you do that in a basic way, but not as elegant as Alpine.js or Vue.js. It's possible by extending htmx and use a third party template library like mustache, handlebar, or nunjucks to accomplish the goal.

There is a client-side-templates Extension ready, but it's very basic and it didn't work for my special case, where I had to transform the JSON before using it.¹

Fortunately, it's easy enough to customize the extension for my needs.

Writing the HTML

The cool thing about htmx is how you can read the attributes and understand what's going to happen:


<div hx-ext="client-side-templates">
  <!-- hx-trigger="load, click" makes sure that api gets called on page load AND on click  !-->
  <button
     type="button"
     hx-trigger="load, click"
     hx-get="https://api.github.com/users/marcus-at-localhost/gists" 
     nunjucks-template="gistlist"
     hx-target="#list"
     hx-swap="innerHTML"
  >Reload</button>

  <script id="gistlist" type="nunjucks">
    {% for gist in gists %}
      <li>
        <a href="{{gist.html_url}}">{{gist.parsed.title}}</a><br>
        <small>{{gist.parsed.description}}</small>
      </li>
    {% endfor %}
  </script>

  <ul id="list"></ul>
</div>

Wrapped in hx-ext="client-side-templates" we know this block is taken care of by an extension.

The button tells us an action is triggered (hx-trigger="load, click") when we click on it, or when it appears in the DOM (on load).

The action is a GET request hx-get="https://api.github.com/users/marcus-at-localhost/gists" to the api.

Then look for a template in nunjucks syntax nunjucks-template="gistlist" and find the target HTML element in the DOM where the rendered template is going to be placed in (hx-target="#list")²

Finally hx-swap="innerHTML" tells us the method htmx inserts the rendered template into the DOM³.

After we added the attributes to the HTML markup we have to define an extension to deal with all the JSON related stuff, like finding the client-side template fragment, manipulating the data object, and render the template.

As I said, the original extension assumed the JSON comes in a format you can work with right away, but this might not be the case.

So this is a minimal working case of my extension:

htmx.defineExtension('client-side-templates', {
  transformResponse : function(text, xhr, elt) {
    var nunjucksTemplate = htmx.closest(elt, "[nunjucks-template]");
    if (nunjucksTemplate) {
      // manipulate the json and create my final data object.
      var data = {
        gists: JSON.parse(text).map((item) => {
          // parser : https://codepen.io/localhorst/pen/ZEbqVZd
          item.parsed = new leptonParser().parse(item.description);
          return item;
        })
      };

      var templateName = nunjucksTemplate.getAttribute('nunjucks-template');
      var template = htmx.find('#' + templateName);
      return nunjucks.renderString(template.innerHTML, data);
    }
    return text;
  }
});

One limitation I've found is the restrictive access to the ajax object and results. I couldn't find a way to cache a request as it was possible in Alpine.js and Vue.js.

In case you need full control, I guess you are better off dealing with it completely in javascript using the fetch API, render the HTML and swap it in.

Another roadblock was the additional HTTP header, htmx adds for its requests. The Github API didn't like them and returned with CORS errors.

In order to remove all htmx headers (since we can't use them anywhere else than the server you have control over) we need to hook into the configRequest.htmx event.

document.body.addEventListener('configRequest.htmx', function(evt) {
    // try to remove x-hx-* headers because gist api complains about CORS
    Object.keys(evt.detail.headers).forEach(function(key) {
      delete evt.detail.headers[key];
    });
  });

And that's basically it.

💡 Please note, the list won't show in the codepens embedded below, because I'm using session storage and that's restricted in an iframe

Alpine.js

Vue.js

Published also here: Handle Json API Results in htmx

the best cut point is probably where the template plugin is doing the manipulation. Maybe just copy the plugin and just the nunjucks part (since that's what you are using) and do the JSON transformation there? -- https://gitter.im/intercooler-js/Lobby?at=5ed2addef0b8a2053ac37859 ↩
How and where you write templates depends on the template engine you are using. Nunjucks allows you to use template fragments from files. Here I just inlined the template. ↩
https://htmx.org/attributes/hx-swap/ ↩

AlpineJS compared to VueJS

Marcus — Sun, 17 May 2020 19:53:40 +0000

AlpineJS calls itself A rugged, minimal framework for composing JavaScript behavior in your markup and asks you to think of it like Tailwind for JavaScript.

While I have little to no idea what the first phrase means I know what to think of the second, even if I've never used Tailwind CSS so far: stuff a lot of data into HTML attributes.

I'm fan of that! I'm fan of Unpoly and intercooler.js/htmx, and I love the approach of writing HTML and add some javascript behavior. Heck, I'm still a fan of jquery! There is nothing wrong with that.

So I set out to give AlpineJS a try and while I expected to work with server-side rendered HTML fragments, I ended up consuming JSON. In this regard, AlpineJS is closer to VueJS (and it's not hiding the fact that some of the syntax is heavily borrowed from Vue) and therefore I just wrote a little thing one in AlpineJS and one in VueJS, to compare them.

It has been a little bit of a challenge to understand the variable scope, since all the AlpineJS examples work with fixed JSON values and not dynamic data, fetched from an external data source. The one example that showcases fetch shows it directly used in an attribute, which w a little bit too much simplified.

<div
    x-data="alpineInstance()"
    x-init="fetch('https://jsonplaceholder.typicode.com/users')
        .then(response => response.json())
        .then(data => users = data)">
        <!-- -->
</div>

TL;DR

So how would I fetch() data on x-init and transform it?

For my experiment I decided to

pull a list of Github Gists,
parse the description Lepton - GitHub Gist Client style
save them into sessionStorage to get around the API rate limit while testing (60 calls per hour)
and just show them.

Bonus: use TailwindCSS.

The barebone HTML looks like this:

<div x-data="gistsData()" x-init="init()">
  <ul>
    <template x-for="gist in gists" :key="gist.id">
      <li>
        <a x-bind:href="gist.html_url" x-text="gist.parsed.title"></a>
      </li>
    </template>
  </ul>
</div>

x-data declares the scope of the component, means all the data and methods you want to use in this component. In Vue, this is the data, methods and maybe computed fields.

x-init is a method that run on initialization or just some JSON. In this case it's a method, that fetches the data and saves the response in the gists key so it's accessible in the HTML.

function gistsData() {
  return {
    title: 'Latest Gists',
    gists: [],
    init() {
      // Testdata
      /*
        this.gists = [
          {
          "id": "8f6af49ffe693c15faca67a7f3bf1a31",
          "html_url": "https://gist.github.com/8f6af49ffe693c15faca67a7f3bf1a31",
          "description": "[Lepton Title Style] Some description and #hash #tags"
          }
        ];
        return;
      */

      // get gists
      fetch('https://api.github.com/users/marcus-at-localhost/gists')
        .then(response => response.json())
        .then(response => {
          this.gists = gists;
      });
    }
  };
}

So this is the most basic example how to structure your code.

Check out the two codepens and compare them.

AlpineJS

💡 If you want to debug console.log(this.gists) it's pretty noisy. Checkout the AlpineJS Devtools extension, that is similar to the Vue Devtools.

VueJS

And Tailwind? In its most basic form, it's the Atomic CSS approach, similar to Bootstrap, down to some of the same class names, like mt-5 for margin-top: x;. Just add classes as if you would write inline css.

You can also "compose" custom classes from those micro classes, almost as if you were writing CSS. :-o

I can see that this is fun to use, but it's not superior to other frameworks. Use whatever works for you.

Also on my blog

Request Google Sheets JSON API v4 with PHP

Marcus — Mon, 11 May 2020 20:01:04 +0000

Via the Google API, it's really easy to GET your spreadsheet as JSON and then work with it in whichever way you like.

Since the API v3 is going to go away in September 2020 it renders many tutorials useless, so here is how you do it with API v4¹.

Set up a Google Form, a spreadsheet will be created automatically or you can point to an existing spreadsheet. (Help)

Add entries and check if they appear in your spreadsheet
Acquire an API key to authorize the access to the API.
Share the spreadsheet and save the spreadsheetId and the sheetName

https://sheets.googleapis.com/v4/spreadsheets/{spreadsheetId}/values/{sheetName}

For more in-depth information about how to query the spreadsheet, check out the docs.

defined('API_KEY','XXX');

$url = sprintf('https://sheets.googleapis.com/v4/spreadsheets/1TlhxvW4GxayktKdjoWKt620qTzysEquC4UPGmOlGxb0/values/Formularantworten%203?key=%s', API_KEY);
$json = json_decode(file_get_contents($url));
$rows = $json->values;

foreach($rows as $row) {
    var_dump($row);
}

Result

// https://sheets.googleapis.com/v4/spreadsheets/1TlhxvW4GxayktKdjoWKt620qTzysEquC4UPGmOlGxb0/values/Formularantworten%201?key=xxxx

{
  "range": "'Formularantworten 1'!A1:M104",
  "majorDimension": "ROWS",
  "values": [
    [
      "Zeitstempel",
      "What's up",
      "Short Text",
      "Long Text",
      "Matrix [Row 1]",
      "Matrix [Row 2]",
      "Matrix [Row 3]"
    ],
    [
      "01.05.2020 18:06:54",
      "Nothing",
      "Diana",
      "My Answer",
      "Col 1",
      "Col 2",
      "Col 3"
    ],
    [
      "01.05.2020 18:07:17",
      "A Lot",
      "Marc",
      "It's raining",
      "Col 2",
      "Col 1",
      "Col 3"
    ],
    [
      "01.05.2020 18:07:39",
      "Nothing",
      "Maria",
      "Still raining",
      "Col 2, Col 3",
      "",
      "Col 1"
    ]
  ]
}

For more complex tasks, you might want to check out google's api wrapper libraries.

This appeared first on my blog: Request Google Sheets JSON API v4 with PHP

It's much easier to work with v4! JSON result of v3 was a mess. Migrate to v4 ↩