Forem: Hasan Ali

Web Fundamentals: Web Components Part 2

Hasan Ali — Thu, 08 Feb 2024 19:22:30 +0000

Recap
More with Custom Elements
React, not overreact
Summary

1. Recap

So far, we’ve defined what web components are and caught a glimpse into what they can do. We've looked at how to define custom elements, how the browser sees them, and looked at what component lifecycle methods are. Well, some of them. What we're working towards in this series on web components is building up our understanding of what the web platform has to offer, so we can start to build a muscle for when it makes sense to reach for web components and what problems they're really well suited to solve. To get there, let's first dive back into where we left off in Part 1.

2. More with Custom Elements

Our x-timer component so far was capable of connecting to the document and cleaning up any resources when it disconnected. However, we have no way of customizing it without delving into source markup. This was fine for that example, but this would be very limiting if this was a component you created to be downloaded and used somewhere else. We've already seen how other HTML elements like div and button take on additional data in the form of attributes, and we can do the same thing with custom elements. What we want to achieve is let the consumer of x-timer set any interval for their timer:

<x-timer x-interval="3"></x-timer>

This doesn't do anything yet but this will be the API we expose. Let's start wiring it up:

// timer.js
class Timer extends HTMLElement {
  static attrs = {
    interval: "x-interval", 
  }
  // --snip--
}

This doesn't do anything yet either, but I've found this to be a simple but useful approach to define element attributes in one place [1]. The attrs object acts as a map that holds the key we'd like to reference the HTML attribute by. I found this pattern useful because conventionally HTML attributes are hyphenated if more than one word (also known as kebab-case), and I found it easier to work with camelcase object properties because you can rely on tooling like autocomplete in your editor. To actually wire it up:

class Timer extends HTMLElement {
  static attrs = {
    interval: "x-interval",
  };

  /**
    * @type { number }
    */
  #count;
  /**
    * @type { HTMLElement }
    */
  #countSpan;
  /**
    * @type { number }
    */
  #timerId;

  constructor() {
    super();
  }

  connectedCallback() {
    console.log("x-timer connected");

    this.#count = 0;
    this.#countSpan = document.createElement("span");

    const interval = parseInt(this.getAttribute(Timer.attrs.interval) ?? "1");

    this.#timerId = setInterval(() => {
      console.log("Timer called");

      this.#count++; 
      this.#countSpan.textContent = this.#count.toString();
    }, interval * 1000);

    const countParagraph = document.createElement("p");
    countParagraph.textContent = "Count: ";
    this.#countSpan.textContent = this.#count.toString();

    countParagraph.appendChild(this.#countSpan);
    this.appendChild(countParagraph);
  }

  disconnectedCallback() {
    console.log("x-timer disconnected");

    clearInterval(this.#timerId);
  } 
}

Aside: the code is no longer in TypeScript, but typed with JSDoc. I've done this refactor so you can actually copy and paste the code, and run it directly without a build step. As an aside, I've been enjoying this approach to both authoring web components and JavaScript in general.

A few things to note here with the base code. The timer declaration has moved from the constructor to the connectedCallback. This was both a correction and a way to prevent awkward side effects from occurring, like if the component was disconnected and connected back into the document the timer wouldn't restart because the constructor wouldn't be called.

const timer = document.querySelector("x-timer"); // constructor called
document.body.appendChild(timer); // connectedCallback called

timer.remove() //disconnectedCallback called
document.body.appendChild(timer); // connectedCallback called

Most of that should look identical to Part 1. The way you handle attributes passed into a custom element is by just reading it using this.getAttribute, and since getAttribute could return null, we set a default value too before parsing it into an integer.

Note: The code you see above could very easily have been this.getAttribute("x-interval") instead of using the static attribute map pattern that we've done.

Moreover, the query-ability of a component depends on two thing: the loading of the script and the parsing of the HTML [2]. If the HTML was parsed before the script was loaded, then when the script loads and the custom element is defined, the constructor will have access to the attributes and the children nodes [3]. However, if the script and the custom element definition loaded first, then the constructor would not be able to access the document nodes because it might not be fully parsed yet. To simplify this for our example, we can move this query logic to the connectedCallback, which will only run when the element is connected to the document.

By querying the attribute in the connectedCallback, we'd will only set the interval with the attribute once for when the component connects to the document. That means the timer wouldn't update if you change the attribute from the outside like so:

const timer = document.querySelector("x-timer");
timer.setAttribute("x-interval", "10");

To do that, we'll need to tell the component to observe changes to the attribute and use another lifecycle method called attributeChangedCallback to manage the changes. To observe attributes, you can declare a static property called observedAttributes that the platform recognizes and list the names of the attributes to be tracked. That would change our code like so:

class Timer extends HTMLElement {
  static attrs = {
    interval: "x-interval",
  };
  static observedAttributes = [Timer.attrs.interval];  
  // --snip--
}

Note: This is equivalent static observedAttributes = ["x-interval"];, and if you had more than one attribute to track, you could either comma-separate them in that array individually, or use Object.values like this static observedAttributes = Object.values(attrs); [3].

Another equally valid approach to define observedAttributes is to make it a static getter method:

class Timer extends HTMLElement {
  static attrs = {
    interval: "x-interval",
  };
  static get observedAttributes() { 
    return [Timer.attrs.interval];
  }  
  // --snip--
}

As far as I can tell, they work exactly the same way.

3. React, not overreact

Now that we've told the custom element to track the changes to our attributes, we're ready to handle them in the attributeChangedCallback. This is the signature of the method [4]:

/**
  * @param { string } name
  * @param { string } oldValue
  * @param { string } newValue
  */
attributeChangedCallback(name, oldValue, newValue) {}

This callback gets called when an attribute changes. It is the same callback that gets called for every attribute change. If you have many attributes changing all at once, this callback would get called for each attribute change, respectively, for the number of times they've changed. This means that you will need to ensure in the callback that the updates you make only pertain to the attribute responsible for it, and that there's an actual change in value; you can set the attribute with the same value multiple times, and this would trigger the callback for each change. The way you know what attribute triggered the callback is by checking the name parameter, and to check if the value has changed, you can compare the oldValue with the newValue:

class Timer extends HTMLElement {
  static attrs = {
    interval: "x-interval",
  };
  static observedAttributes = [Timer.attrs.interval];  
  // --snip--
  attributeChangedCallback(name, oldValue, newValue) {}
}

Before we flesh this logic out, let's take a step back and think about the order of events from the browser's perspective. First, the browser instantiates a custom element after encountering it in the parsing phase. Then it calls a few lifecycle methods in the layout and painting phase, before finally connecting the component to the screen in the composite phase. A quick shortcut I use to remember this flow is by thinking about how I would create an HTML element in JavaScript, configure it and then insert it into the document [5]. The steps I'd follow are:

const newTimer = document.createElement("x-timer"); // constructor called
newTimer.setAttribute("x-interval", "2"); // attributeChangedCallback called
document.body.appendChild(newTimer); // connectedCallback called

If you squint a bit, this is essentially what the browser does when you declaratively use custom elements in HTML. The attributeChangedCallback gets called too because the setting of the initial value is also considered a change. This makes sense from the signature because the oldValue would've been undefined and the newValue is the value you've just set.

With that context, you'll need to reason about the order of events when checking or manipulating member properties from within the different methods. For example, this.#timerId gets set in the connectedCallback and since that gets called after attributeChangedCallback, we'll need to ensure we check if the element is connected before creating a new timer (or conversely do nothing if the element is disconnected) [3]. If we wanted to change the timer interval after putting the element on the document, then we would need to ensure our update logic doesn't accidentally run before the update. To do this, we can simply check if the element is connected using the isConnected property that's available to every document node, and return early from the callback if not.

class Timer extends HTMLElement {
  // --snip--
  attributeChangedCallback(name, oldValue, newValue) {
    if (!this.isConnected) {
      return;
    }
  }
}

We also only want to do this if the oldValue and the newValue for any tracked attribute is different, so we can wrap our conditional with that first:

class Timer extends HTMLElement {
  // --snip--
  attributeChangedCallback(name, oldValue, newValue) {
    if (oldValue !== newValue) {
      if (!this.isConnected) { /* --snip-- */ }
    }
  }
}

Checking for the value difference first before the attribute name means that we will only look to do work for an attribute when we know that there has been a change at all. Since we only want our timer update logic to depend on the interval attribute, we can put all of the logic related to it in another conditional that compares the interval attribute name with the name input parameter in the callback:

class Timer extends HTMLElement {
  // --snip--
  attributeChangedCallback(name, oldValue, newValue) {
    if (oldValue !== newValue) {
      if (name === Timer.attrs.interval) {
        if (!this.isConnected) { /* --snip-- */ }
      }
    }
  }
}

Now we're ready to add the logic to replace our existing timer with a new timer when the interval attribute is updated:

class Timer extends HTMLElement {
  // --snip--
  attributeChangedCallback(name, oldValue, newValue) {
    if (oldValue !== newValue) {
      if (name === Timer.attrs.interval) {
        if (!this.isConnected) { /* --snip-- */ }

        const parsed = parseInt(newValue);
        const interval = isNaN(parsed) ? 1 : parsed;

        clearInterval(this.#timerId);

        this.#timerId = setInterval(() => {
          console.log("New timer called", interval);

          this.#count++; 
          this.#countSpan.textContent = this.#count.toString();
        }, interval * 1000);
      }
    }
  }
}

This logic should look very similar to what we previously saw in the connectedCallback. Note that we performed some clean up using clearInterval to manage our resources before reassigning it. We do this because, the reassignment of this.#timerId only mutates the ID that it has stored, and doesn't delete the timer from the scope it lives in. If we don't perform this cleanup, then the previous timer would continue to run in the background and continue to update the counter on its interval alongside the new one, which as you'd imagine would be very confusing.

This is what the final HTML looks like with the logic that updates the timer, which you'd also be able to find on my GitHub.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width" />
    <title>Web Components Part 2</title>
    <link href="styles.css" rel="stylesheet">
    <script src="timer.js"></script>
  </head>
  <body>
    <h1>Web components demo</h1>
    <main>
      <x-timer></x-timer>
      <x-timer x-interval="5"></x-timer>
      <x-timer x-interval="2"></x-timer>
      <button>Update timer 2 to 10 seconds</button>
    </main>
    <script>
      const timerTwo = document.querySelector("x-timer[x-interval='2']");
      const button = document.querySelector("x-timer[x-interval='2'] + button");

      button.addEventListener("click", () => {
        timerTwo.setAttribute("x-interval", "10");
      });
    </script>
  </body>
</html>

Summary

This covers all but one of the lifecycle methods that you get access to with custom elements, and in actuality, these are what you'd use most of the time. The last one is adoptedCallback and you'd most likely encounter it in the context of <iframe> elements [6]. Even though I don't have plans to go through it in the series, the concepts and the way we've covered them so far should give you a good idea on how to begin unpicking it if you do. Other than that, we have enough under our belt to delve even deeper into what web components have to offer.

All of this might feel like a lot of work to put some HTML on the screen and update a few attributes, and it is. Even though we've achieved fine-grained updates in our component, it took a fair bit of reasoning about the lifecycle methods to get there. The reason the custom elements API feels a little cumbersome is because it's low level by design to give you the most control. This means that you can do anything with it, including build your own abstractions on top of it.

There are other component-based abstractions that will give you the same effect with a lot less work, and some even give you the same level of fine-grained control. Though we'll look at a few UI frameworks alongside web components, the ultimate aim of this series is to demonstrate what the web platform is capable of, and get you to start thinking about the different tradeoffs you make when picking different tools. My hypothesis is that by understanding what the platform has to offer, you'll be in a much better position to evaluate the complexity you choose to take on when building experiences. Lastly, I'll leave you with a little spoiler of what's to come: web components are cool and they are here to stay.

If you think of anything I've missed or just wanted to get in touch, you can reach me through a comment or Mastodon.

References

Zach Leatherman's <browser-window> component [GitHub]
Danny Engelman's comment on loading order [Comment]
𒎏Wii's comment on loading order [Comment]
MDN Web Components [Website]
Component Lifecycle Reference Diagram [Website]
Component Lifecycle Reference [Website]

Web Fundamentals: The HTML-JSX Confusion

Hasan Ali — Fri, 08 Sep 2023 21:55:00 +0000

The mistake
Parsers
XHTML & JSX
Why it matters
Summary

1. The mistake

This post was originally going to be a short correction on Web Fundamentals: Web Components Part 1 about a false claim I made. I claimed that you can follow along with a simple HTML file by copy and pasting the code snippets that were originally written in Astro. However, that isn't entirely true unless you tweaked some of the markup first. I used Astro's markup syntax [1] which is very similar to HTML, and since I didn't use any of its templating features in my snippets, I thought it'd be identical to HTML. It turns out that it would only be identical to the incorrect HTML I would've written because I wasn't aware of how browsers parsed it. The mistake I made was not put closing tags on my custom elements. I wrote <x-timer /> instead of <x-timer></x-timer>.

I suppose this is a small enough error that you could either ignore or accept a quick correction for, but I thought it'd be more valuable to take this opportunity to peak behind the scenes of how browsers parse HTML. My intention with this snippet was to declare an empty element in the document, and then add children to it using JavaScript. It worked for me in Astro because Astro's templating syntax is closer to JSX than it is HTML. If you were to do the same thing in a plain .html file and then view it in the browser, there's a chance it might not look right depending on the markup that followed the declaration. What's the problem then? And why is it nuanced?

2. Parsers

Syntax is an agreement. It’s an agreement between you and the tool that parses it. When we follow the rules, we expect to see the same results every time because that’s what we’ve agreed to. If the rules were strict, it'd be harder to break but it might also feel too rigid. If the rules were lenient, it'd offer greater flexibility but it can also be harder to avoid ambiguity in the code.

The HTML parser is very flexible by design. It’s built in such a way that even if you break the rules a little, it’ll figure out how to simplify things and display something on the screen. It’s very tolerant. This means if you view the following incomplete markup in the browser, it'll still render a page:

<div>
<p>HTML is tolerant
<br>
<p>Unusally tolerant if you've used a programming language
<section>
Why does it work without any closing tags?

If you inspect this page, you'll see that the browser has insert some basic tags you've missed and also figure out where to put the closing tags for the elements you’ve declared:

<html>
  <head></head>
  <body>
    <div>
      <p>HTML is tolerant</p>
      <br>
      <p>Unusally tolerant if you've used a programming language</p>
      <section>
        Why does it work without any closing tags?
      </section>
    </div>
  </body>
</html>

This might've been exactly what you wanted. Or you might've intended for the section to be outside of the div. Since you've omitted the closing tags, there is no way for the HTML parser to deduce your intent any further [2]. It simplifies it and just does what it does because that’s the agreement. This flexibility means that the burden of enforcing the correctness of the markup is on you. Are there other parsers with different rules that will yell at you when you're being ambiguous like this? Yes.

The flexibility is a feature of the HTML parser, but there are other parsers out there that are stricter, namely XML parsers. XML is a data format like JSON. In XML, there are no predefined tags and you can use it to create whatever shape you want to describe your data. For example:

<person>
  <name>Hasan</name>
  <occupation>Software Engineer</occupation>
  <hobbies>
    <hobby>
      <name>Writing</name>
      <reason>It helps me shape my thinking</reason>
      <frequency>Few times a week</frequency>
    </hobby>
    <hobby>
      <name>Video games</name>
      <reason>It helps me relax and unwind</reason>
      <frequency>Few times a week</frequency>
    </hobby>
    <hobby>
      <name>Cooking</name>
      <reason>It helps me try new things and be creative</reason>
      <frequency>Almost everday</frequency>
    </hobby>
  </hobbies>
</person>

If you're more familiar with JSON, the equivalent is:

{
  "name": "Hasan",
  "occupation": "Software Engineer",
  "hobbies": [
    {
      "name": "Writing",
      "reason": "It helps me shape my thinking",
      "frequency": "Few times a week"   
    },
    {
      "name": "Video games",
      "reason": "It helps me relax and unwind",
      "frequency": "Few times a week"   
    },
    {
      "name": "Cooking",
      "reason": "It helps me try new things and be creative",
      "frequency": "Almost everyday"    
    }   
  ] 
}

There are no predefined tags in XML and if you notice, every tag that we created has a closing tag and this isn't optional [3]. It's because without it there would be no way to know where boundaries of different elements would be. With HTML, the parser uses rules of predefined elements to decide where the closing tags could go if it's not specified. If there aren't any predefined tags, the only way to reliably parse XML would be to expect explicit closing tags. So, what if you wrote HTML like it were XML so you gain all the benefits of XML? This would remove all ambiguity in your markup at the time of authoring it.

3. XHTML & JSX

This was the motivation behind XHTML, or the XML syntax for HTML [4]. You can write your markup strictly in the XML syntax, but it does have the drawback of not rendering anything if you get the markup wrong. With it, you’ve traded the flexibility of the HTML syntax for correctness and depending on the problems you’re facing, this might be worth it. The actual history of how the standards evolved is a little murky to me, but today you can have the better parts of both approaches and write your HTML markup using a mixture of traditional HTML syntax and an XML-like one. This compatibility was added in HTML5 to be more friendly to parser-agnostic markup, so it can be parsed by both HTML and XML parsers. The XML syntax inspired the JSX syntax with the advent of React [5], and even though strict XHTML is not in fashion anymore, it's impact can be felt by the templating syntaxes that it inspired.

With that context established, how would you define elements that can't have children according to the HTML specification, like <br> or <input>, using the XML syntax? In the specification, these elements are called "void elements" [6]. XML syntax requires you to have closing tags, so how can you write this and remain parser agnostic? The XML syntax supports "self-closing" tags for this reason, so that would mean <br> and <input> would become <br /> and <input />, respectively (on the other hand, the HTML parser is also smart enough to ignore the erroneous closing tags for void elements, but don't do this). This was added to HTML5, but there are still strict rules around it. There's a short list of predefined void elements and that's it. You cannot define any other elements as if they were void elements (for example, you can't do <div /> instead of <div></div> for an empty div), and this is the reason why my code snippet wasn't valid HTML.

When the HTML parser encounters a non-void element with a self-closing tag, it treats it as if it was just an opening tag [7]. The parser then figures out where to put the closing tag like it normally would when you omit it, and that's why my snippet would've worked only some of the time if it were used directly in HTML. It worked reliably for me in Astro because Astro uses a JSX-like syntax, which would translate <div /> to <div></div>, and <x-timer /> to <x-timer></x-timer>. The more granular reason this syntax isn't supported for custom elements is because the parser cannot ensure that it can be a void element in the parsing phase [8] without running the connectedCallback, and that doesn't happen until the layout and painting phase [9].

4. Why it matters

Does it really matter? I think when learning the fundamentals, it's important to be shown the right thing and then the alternatives for the very specific problems they solve. That's quite challenging today because of how ubiquitous non-standard technologies are, and how much they influence our understanding of the web platform. When I learnt HTML 15 years ago, I didn't spend long enough with it to notice things like void elements and optional tags. Having written JSX in React, Solid and Astro for years, my brain couldn't even understand why my mistake was a mistake; until I saw it pointed out in a video about WebC [8], which is a templating syntax that is much closer to native HTML than JSX is.

A part of understanding the web is understanding how the browser handles what you throw at it. In Web Fundamentals: HTML Forms we looked at how the browser takes your declarative HTML form and submits an HTTP request to the server when you submit it. In Web Fundamentals: Web Components Part 1 we looked at how the browser parses and executes your custom element logic. This approach gives us a stronger foundation when trying to understand and evaluate some of the modern innovations in web development, because framework authors are building on top of the strengths and weaknesses of the platform.

Summary

HTML tags are so fundamental to web development that the rules around it can often be overlooked, especially when you work with various templating languages regularly. By looking at how the browser parses HTML tags, we saw that the source of my error was not understanding the difference between HTML and JSX syntaxes. We built up to it by looking at the different considerations the different parsers have had to make and how all of that culminated in my misunderstanding of when it's okay to use self-closing tags. This was an example of the importance of questioning your most fundamental assumptions because that is how you keep growing and stay up-to-date.

If you think of anything I've missed or just wanted to get in touch, you can reach me through a comment or Mastodon.

References

Astro templating syntax [Website]
Where HTML beats C [YouTube]
XML Tags [Website]
XHTML [MDN]
React JSX closing tags [Website]
HTML spec on void elements [Website]
HTML spec on HTML parsing [Website]
WebC is neat! with Zach Leatherman, Web Developer [YouTube]
Web Fundamentals: Web Components Part 1 [Website]

Web Fundamentals: Web Components Part 1

Hasan Ali — Mon, 14 Aug 2023 10:08:00 +0000

Liquid syntax error: Unknown tag 'endraw'

Web Fundamentals: HTML Forms

Hasan Ali — Tue, 11 Jul 2023 17:00:00 +0000

What are forms?
How do they work?
How do we build it?
Summary

1. What are forms?

Forms are one of the fundamental tools through which we interact with the web everyday [1]. It enables us to sign into apps, signup for newsletters, purchase things online and post comments to list a few. They're a key mechanism through which we send information from our browser to the server.

In this tutorial, we're going to start with the simplest incarnation of forms and start to gain some appreciation for just how much functionality is built into the web platform. We'll go over how they work and how to build it. To follow along, you'll need a text editor, and a web server that can serve HTML files and handle requests. For my web server, I'm going to use Deno [2] and a web framework called Oak [3] to handle requests. On the frontend, it'll be plain HTML.

Prerequisites:

Basic understanding of how servers work [MDN]
HTTP verbs [MDN]
An installation of Deno [Website]

2. How do they work?

Before we dive into forms, let's start with what happens when you visit a website:

You request for a website through the address bar or a link
The server receives your request
The server responds to your request by sending HTML as text
Your browser renders that HTML

When you visit a site, the request that you make to the server is a GET request. The server needs to be configured to handle requests based on the path of the website being accessed and also what type of request is being made (i.e. GET, POST or any of the other HTTP verbs [4]). For example, when you access the site https://hasanhaja.com/picks then you make a GET request to the path /picks. Where as if you go to https://hasanhaja.com then you make a GET request to the path / .

With that context, let's follow an example where the HTML that is returned contains a form.

The form is denoted by the HTML tag <form> and nested within it are fields for the data we want to collect along with a submit button. The default behavior of forms is the construct a search query with the form data and make another GET request to the same path.

The server can be configured to identify the search query parameters so that it can respond as instructed.

There's also another way forms can be configured on the frontend. If we'd like the form to submit data by making a POST request to the same path with the form data in the body of the request, we can add the method attribute to the HTML like this <form method="post">. The server can be configured very similarly to handle this request.

In the above example, we only see the server return HTML as a response to the request, but in actuality it can be configured to perform any arbitrary action with the data. If this were a form to subscribe to a newsletter, then the server will perform the logic to add them to the email list and then send an HTML response to inform the user that the request was handled successfully.

If the form field were a search filter in an e-commerce website, then the form data can be used to query the database for all the products related to the search and then the response can be constructed with these results. The applications for forms are endless, and that's precisely why they're everywhere.

3. How do we build it?

Okay, let's build a form and start tinkering!

To keep things as simple as possible, our form will contain the minimum number of fields required for it to qualify as a form. Here's a form with one text field [5] called "name":

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width" />
        <title>Form</title>
    </head>
    <body>
        <h1>Our form</h1>
    <form>
      <h2>Your details</h2>
      <label for="name">Name</label>
      <input id="name" name="name" type="text">
      <button type="submit">Submit</button>
    </form>
    </body>
</html>

This is what the HTTP request looks like when you click submit:

GET /?name=Hasan HTTP/1.1
Host: localhost:8000
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:109.0) Gecko/20100101 Firefox/114.0
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8
Accept-Language: en-GB,en;q=0.5
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Referer: http://localhost:8000/
Upgrade-Insecure-Requests: 1
Sec-Fetch-Dest: document
Sec-Fetch-Mode: navigate
Sec-Fetch-Site: same-origin
Sec-Fetch-User: ?1

The HTML form constructed this entire HTTP request for us, and we only need to consume this on the server and send a response back. Let's look at the server code that can handle this form submission:

import { Application, Router } from "oak";

const router = new Router();

router
  .get("/", async (context) => {
      const { search } = context.request.url;

      if (!search) {
        await context.send({
          root: `${Deno.cwd()}/static`,
          index: "index.html",
        });
        return;
      }

      const params = new URLSearchParams(search);
      const name = params.get("name");
      context.response.body = `<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width" />
    <title>Form</title>
  </head>
  <body>
    <h1>Our form</h1>
    <p>Hi there, ${name}!</p>
  </body>
</html>
      `;
});

const app = new Application();
app.use(router.routes());
app.use(router.allowedMethods());

await app.listen({ port: 8000 });

The .get handler for the path "/" handles both the request for the page and the form submission. The conditional check if (!search) is to distinguish between the form being requested or the form being submitted. When the page is requested without the search query parameters, it means the user is requesting the form, and when it's requested with the query parameters it means the form was submitted. In our implementation when we encounter a form submission, we construct HTML inline and respond with the name in the body of the HTML.

The functionality of context.send is to read the static HTML file from the server's filesystem and send it as text in the response. The Oak framework constructs an HTTP response with the appropriate headers to tell the browser what kind of content it will be rendering. You can debug the response headers in the Network tab of the browser's developer tools, and this is what it looks like for our form submission response:

HTTP/1.1 200 OK
content-type: text/html; charset=UTF-8
vary: Accept-Encoding
content-encoding: gzip
content-length: 187
date: Mon, 10 Jul 2023 22:05:42 GMT

Aside: The content-type: text/html is why responding with an inlined HTML string by setting the context.response.body is both valid and equivalent to the context.send approach. The context is an implementation detail specific to the Oak framework, and your mileage may vary depending on how you handle HTTP requests.

This can get a little confusing on the server. It's confusing because when the form data is sent to the server, the underlying HTTP verb is still GET. That means when the server receives a GET request, it also needs to check if form data is being sent to it. Using GET with data is a perfectly valid pattern, but we can make our lives a little easier when dealing with forms to separate the logic for getting forms and posting data.

To switch this form to send the form data via POST, we can add the "method" attribute with the value "post" to the form tag.

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width" />
        <title>Form</title>
    </head>
    <body>
        <h1>Our form</h1>
    <form method="post">
      <h2>Your details</h2>
      <label for="name">Name</label>
      <input id="name" name="name" type="text">
      <button type="submit">Submit</button>
    </form>
    </body>
</html>

This seems too trivial and it is. The web platform is incredibly powerful and feature-rich. This little declaration entirely changed the communication mechanism. This is the HTTP request that gets sent to the server:

POST / HTTP/1.1
Host: localhost:8000
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:109.0) Gecko/20100101 Firefox/114.0
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8
Accept-Language: en-GB,en;q=0.5
Accept-Encoding: gzip, deflate, br
Content-Type: application/x-www-form-urlencoded
Content-Length: 10
Origin: http://localhost:8000
Connection: keep-alive
Referer: http://localhost:8000/
Upgrade-Insecure-Requests: 1
Sec-Fetch-Dest: document
Sec-Fetch-Mode: navigate
Sec-Fetch-Site: same-origin
Sec-Fetch-User: ?1

And this is the payload that goes with the request:

name=Hasan

On the server, we can handle this by adding another handler to our router:

/* --snip-- */
router
  .get("/", async (context) => {
      const { search } = context.request.url;

      if (!search) {
        await context.send({
          root: `${Deno.cwd()}/static`,
          index: "index.html",
        });
        return;
      }
            /* --snip-- */
  })
  .post("/", async (context) => {
    const formBody = await context.request.body({ type: "form" }).value;
    const name = formBody.get("name");

    context.response.body = `<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width" />
        <title>Form</title>
    </head>
    <body>
        <h1>Our form</h1>
    <p>Hi there, ${name}!</p>
    </body>
</html>
    `;
  })
;

/* --snip-- */

We'll leave the .get handler as is so it can still serve the form to us, but when we submit it our .post handler will handle that request. And that's how simple forms are!

This is our entire server code that handles form submissions through the GET and POST method:

import { Application, Router } from "oak";

const router = new Router();

router
  .get("/", async (context) => {
      const { search } = context.request.url;

      if (!search) {
        await context.send({
          root: `${Deno.cwd()}/static`,
          index: "index.html",
        });
        return;
      }

      const params = new URLSearchParams(search);
      const name = params.get("name");
      context.response.body = `<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width" />
    <title>Form</title>
  </head>
  <body>
    <h1>Our form</h1>
    <p>Hi there, ${name}!</p>
  </body>
</html>
      `;
  })
  .post("/", async (context) => {
    const formBody = await context.request.body({ type: "form" }).value;
    const name = formBody.get("name");

    context.response.body = `<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width" />
        <title>Form</title>
    </head>
    <body>
        <h1>Our form</h1>
    <p>Hi there, ${name}!</p>
    </body>
</html>
    `;
  })
;

const app = new Application();
app.use(router.routes());
app.use(router.allowedMethods());

await app.listen({ port: 8000 });

All the source code for this post can also be found on my GitHub.

Summary

Forms are simple and they are deeply supported in the web platform. They enable us to capture data from users and this provides an interactive web experience. In this post, we looked at the anatomy of HTML form and how to build them. We saw two methods of submitting form data to the server and we saw that although the difference in code is very minimal, the communication of intent is far stronger with the POST method.

HTML forms have a lot of features packed into them. There are a lot more fun and complex situations that require delving into them deeply. Examples of this can be:

Validating the input to ensure it's in the correct format before sending it to the server
Validating the data on the server and responding with an error message if the validations fail

Stay tuned for follow up posts in this web fundamentals series.

If you think of anything I've missed or just wanted to get in touch, you can reach me through a comment or Mastodon.

References

Web forms — Working with user data [MDN]
Deno [Website]
Oak framework [Website]
HTTP verbs [MDN]
Form Input element [MDN]

TDD isn't Agile

Hasan Ali — Fri, 28 Apr 2023 22:49:48 +0000

Tech Twitter would have me believe that test-driven development is the worst thing ever. Maybe it’s just trendy to hate it, or maybe it’s a historical thing. I don’t have that context. I’m an advocate for well-tested code and I work in an environment where our tests give us a lot of confidence. I’ve also worked in a place that only did manual testing when new features were added. Those weeks of hunting down bugs weren’t fun especially when the behavior of the new features were completely intertwined with existing features. Those were definitely places where automated tests could’ve saved us hundreds of hours of blood, sweat and tears. So, why do I still think test-driven development isn’t the answer?

Before we start, let’s outline the test-driven development framework [1]:

Read, understand, and process the feature or bug request
Translate the requirement into a failing unit test
Implement the code that makes that test pass with the simplest solution
Refactor code
Repeat

My first take to seeing this was this should be interpreted and not be regarded as a framework. It’s imperative for developers to understand the benefits of tests, even when in my experience the suggestion of writing tests causes them to shift uncomfortably in their seats. When you regard the framework loosely it encourages thinking of the testability of code when developing. Prescribing a stringent framework has put and will put people off from writing any tests in the first place. It’s important to try and understand the sentiment rather than brush it off with, “don’t knock it till you’ve tried it”. I think the reason is the framework itself isn’t congruent with the way people think through problems.

In my experience, when faced with a problem, bug or feature the response usually isn’t:

“What should I tackle next? Should I write another failing test or refactor?”

It’s often:

“Why is this happening? Will it work if I try this?”

TDD isn’t the way we encourage anyone to solve problems, let alone engineers. We encourage them to experiment, tinker and try different things. We try and foster curiosity and also critical thinking. You could argue that that is what TDD posits, but it isn’t really; not if you adopt it strictly. “Read, understand and process” sounds like critical thinking, but what does “understand” and “process” even mean? Without experimentation, you might not be able to ask the right questions in the first place to properly understand the problem. Being tied to writing a test before trying something out introduces hurdles before it facilitates problem solving.

We should definitely encourage engineers to write tests. It’s a valuable tool to document weird behaviors and edge cases, and to ensure engineers don’t accidentally refactor those considerations away. It’s a tool to introduce confidence into areas of your codebase that may inherently be more fragile. However, I don’t think it should be the primary mechanism through which we think about a problem. Even though writing tests first might encourage exploratory questions that may catch something, it’s often the case that you don’t think of all the edge cases. This isn’t a fault of TDD but this not something TDD can mitigate either [2], so why do twice the work? I think you’ll be in a good place if all you got out of TDD is “well-tested code is good”. If you’re being force-fed the TDD framework, then that by definition isn’t agile [3] because it puts process over people.

If you think of anything I have missed or just wanted to get in touch, you can reach me through a comment or Mastodon.

References

5 Steps of test-driven development [Website]
Difficulties in using TDD [Medium]
Agile Manifesto [Website]

Photo by Julia Koblitz on Unsplash

React Server Components: The future of getting started with the web

Hasan Ali — Sun, 23 Apr 2023 22:27:24 +0000

Where it began
What Astro means for the web
Scalable complexity
Summary

Where it began

If I were to start in web development today and I already knew some HTML, CSS and JavaScript, I’d be grateful to the person that convinces me to pick Astro over anything else.

I didn’t learn web development this way. I knew the very basics of HTML and CSS when I started programming in Java. And even though I fell in love with the web for how accessible it is, I didn’t want to be the person that wrote markup, changed the color of buttons or thought about what feature works in what browser. If I were to come onto the scene, I’d do it in a sophisticated way. I’d do it in Java.

I professionally built apps in Vaadin for a little over a year and as good as it was, it’s no longer for me and the things I’m building. What it did for me was it let me skip a whole lot of web fundamentals. I didn’t learn how forms worked. I didn’t know how to properly structure my markup to best keep things accessible. I didn’t even understand how to center a button component within a layout container because the docs assumed I understood enough of the web. I didn’t.

When I started taking web development seriously, I tried to go back to the fundamentals but there was a popular new kid on the block causing a racket. React. I tried avoiding it so I could learn some JavaScript and semantic HTML, but I kept hearing, “it’s just JavaScript”. Fine, I guess this is a two in one offer. Little did I realize, I was adding newer and newer abstractions over what I had, and what I had was absolutely nothing. React felt amazing. I felt like I was close to the fundamentals again but I wasn’t really. This isn’t a critique or an anti-React piece. I’m grateful for the doors it opened for me, and to be fair, it’s still paying the bills. If I already had a good foundation, I would’ve been in a better position to reason about the decisions I’m accepting and endorsing in my applications when using React.

What Astro means for the web

This is the reason why I think Astro is a great starting point. If I had come into web development, and been in a situation where I had to build and publish a website quickly, Astro would have me covered. Sure, I ended up doing the same thing with Next.js but I see that as another layer of abstraction over React. For me, this entire house of cards was build on feeble web fundamentals that were derived from the shortcomings of the abstractions Vaadin proposed. I needed fewer abstractions, not more. The exact combination of stacks might be unique, but I don’t think I’m alone in this experience. I think like me, a lot of us ventured into web development with varying levels of exposure to the web, and got given abstraction over abstraction to churn out features and entire applications with very little room to breathe or think.

If I had Astro, I could’ve had my component model abstraction. I could’ve learnt the benefits of scoped styling. I could’ve naturally sprinkled in the JavaScript exactly where I needed the interactivity. These are good and reasonable abstractions that empower you to build websites better than if you hand rolled them yourself. I strongly believe I would’ve spent more time learning about the web and all of the features it had to offer, while enjoying the benefits we’ve distilled from years of experimentation with tools like Angular, Gatsby, Next.js and Remix. As a novice, I would’ve had the best of both worlds with a package so simple that it would empower me to learn the web platform better.

This is why I love Astro. I see Astro as the baseline for anyone coming into web development. If Astro is the starting point, we don’t have to do our awkward explanation of the “MPA” acronym: “we only call them multi-page applications because of single-page applications, which were the new kids on the block. Multi-page applications are how websites have always worked.” That’s a lot of indirection. Now, it’s back to being simple: “Astro is how websites have always worked.”

Scalable complexity

Once we’re rolling with Astro, we can sprinkle in some more complexity, because let’s be honest, we can’t help ourselves. The model lends itself to incrementally adding this only where you need it. This won’t safeguard you from doing something completely unreasonable, but it does give you sufficiently simple building blocks to keep the magic to a minimum, and this ensures you can always reason about your code.

When you feel more comfortable at this level, the point now becomes less about Astro and more about the mental model of the Islands Architecture. Astro does the Islands Architecture well, but it isn’t unique to it. You can take this abstraction with you to other metaframewoks that support it and generally keep all of the benefits. We now know how the web works, serve different pages of your website, organize your code into components so you can reuse them, style these components without accidentally changing the style of another and add interactivity to different parts of the page. What more could you need?

That depends on the complexity of what you’re building. The model we have with something like Astro is very much suitable for a website, and you can push that quite far. By being an MPA, each page has its own markup, styles and interactive bits. If we were map out an end-to-end of this, we’d have the following:

User requests a page
Server responds with HTML, CSS and JavaScript
The full page loads in the browser
User clicks a link to another page
Server responds with the HTML, CSS and JavaScript for that page
The full page loads in the browser

Even if you reuse the same interactive component on both pages, they’ll have no way of knowing they are the same component. You’ll need this if you’re building something that’s more of an SPA. A workaround would be to store the state of the component from the first page in the client’s browser (using session or local storage) and then resume that state when the same component loads on the second page. This still doesn’t give you a proper SPA-like experience and for that we’ll need to persist those islands. How do we do this and just load the HTML around it from the server?

Enter Server Components.

React Server Components, or more generally, the Server Component architecture is what I think is the next iterative step in this journey. They encompass the Islands Architecture and extend it by persisting islands on page navigation [1] [2]. Notice, we’ve built up this complexity in stages just for what we’ve needed. At any point, we can drop all the way back down to output simple markup for any route within the same project. This model enables you to scale complexity up and all the way down when appropriate. There’s no magic in the mental model. There’s some implementation magic in how only the updated parts of the HTML from the server are patched in, but conceptually it’s dead simple. If you want markup, just use server components. If you want interactivity, then add client components for islands. And server components also have you covered when you want to persist those islands with SPA-like navigation.

In terms of tools, Next.js 13 currently supports RSCs but because Server Components are an architecture [3], other metaframeworks could adopt it. For example, SolidStart has been exploring it since before RSCs dropped [3] and even the Astro team is exploring what client-side routing could look like in Astro [4].

Summary

Coming into web development can be a daunting ordeal. If you focus on and build up your web fundamentals, you’ll be in a very good place to keep up with all the advances that happen in this space. Astro is a great piece of technology and it will instil in you a model of the web that is congruent with the web. The Islands Architecture lets you slowly scale up complexity only where you need it and it also makes understanding Server Components, the next step in this evolution, easier to understand and appreciate.

If you think of anything I have missed or just wanted to get in touch, you can reach me through a comment or Mastodon.

References

Dan Abramov’s explanation of the difference between Islands Architecture and Server Components [Twitter]
Dan Shappir’s explanation of the difference between Islands Architecture and Server Components [Twitter]
Ryan Carniato: Into the Depths with Server Components and Functions [YouTube]
Astro’s Roadmap: Client-side Routing [GitHub]

Photo by Sigmund on Unsplash

Why I need Zig

Hasan Ali — Wed, 12 Apr 2023 13:45:30 +0000

I've been thinking about why I feel more productive in some programming languages over others and this article by Chris Krycho of the New Rustacean Podcast made it click for me: https://v5.chriskrycho.com/journal/some-thoughts-on-zig/

I've been a programming language enthusiast since I started coding. A few years ago I decided to stop language hopping so much and work on building real things with a few of them. This helped me get through my masters with C++ and Python, and helped me start my career with Java. Now I spend a vast majority of my time writing TypeScript for work and personal projects, and this has been the most productive I've ever felt. Some of it comes down to experience for sure, but I think a big part of it is the size of the language.

I struggled to move as quickly as I can in TypeScript when working in Java or C++, and I think that made each "learning rep" longer so I couldn't do as many reps. This made the learning feedback loop feel not as rewarding. With the experience I've accumulated now, I feel more confident that I'll have better luck with those languages for the same domain. Which brings me to Zig.

I did a very narrow subset of Systems Programming in C++ and when I tried to get into it with Rust, I kept hitting a wall. I underestimated how steep the "steep learning curve" was. I've been playing with Zig for a couple days now and it's giving me the same productivity wins as TypeScript did in the beginning. I hope this will better build my confidence in the systems domain, so I can appreciate Rust more.

With all that said, this isn't a "Language A is better than B"; I'm a technology pluralist. And as much as I love Rust, I think I need a bit of time with Zig first to help me grow.

If you think of anything I have missed or just wanted to get in touch, you can reach me through a comment or Mastodon.

Photo by John Cobb on Unsplash

Forem: Hasan Ali

Web Fundamentals: Web Components Part 2

Contents

1. Recap

2. More with Custom Elements

3. React, not overreact

Summary

References

Web Fundamentals: The HTML-JSX Confusion

Contents

1. The mistake

2. Parsers

3. XHTML & JSX

4. Why it matters

Summary

References

Web Fundamentals: Web Components Part 1

Web Fundamentals: HTML Forms

Contents

1. What are forms?

2. How do they work?

3. How do we build it?

Summary

References

TDD isn't Agile

References

React Server Components: The future of getting started with the web

Contents

Where it began

What Astro means for the web

Scalable complexity

Summary

References

Why I need Zig