Synaptic Spillage

Building a CLI in Node for DevPail

Todd Esposito — Sun, 30 Jan 2022 19:38:36 GMT

This is the second in a series of articles about building DevPail, my general-purpose development environment tooling tool. You don't have to read the previous article to learn something here, but the context may help you understand what I'm talking about.

The story so far...

In the first article, I introduced my solution to tooling churn, which is to keep all the tooling for each of my projects into an isolated, transportable environment I'm calling a DevPail. It's a Docker container where the tooling runs, coupled with a volume which holds all the tooling and development artifacts. However, the commands needed to use DevPail are fairly involved, so let's solve that issue today by creating a Command Line Interface (CLI) to handle all these tedious details.

Adding a CLI to the project

DevPail's project directory so far is pretty bare:

devpail/
  - imagesrc/
    - homedir/
    - Dockerfile

Node configuration

Since we've chosen to build or CLI in Node, we need to initialize a Node package:

$ cd devpail
$ mkdir src
$ npm init -y

Here we're creating the src directory to hold our CLI source code, and asked npm to create a package.json.

Coding from 30,000 feet

My habit is to build "kinda" code before actual code. It's real code, but at about 30,000 feet, with zero hope of running. This gives me the basic structure of the code, and a framework I can fill in with the gritty-kitty details as I go.

For DevPail, I'll need to be able to:

Build the DevPail image; let's call this devpail --build
Run a shell in the DevPail container for any project; let's call this devpail --shell
Run the DevPail tooling inside the container for any project; let's call this devpail

Let's start coding

Let's create a file called src/cli.js to hold this code, and start building that framework. We know that the first thing we have to do is process those command line options, if any.

const status = processOptions()
if (status) {
    console.log(`\nDevPail: ${status}\n`)
}

As promised, this code totally won't work yet. Let's move down one level:

function processOptions() {
    var args = process.argv.slice(2)
    if (args && args[0] === '--build') {
        return buildImage()
    } else if (args && args[0] === '--shell') {
        return runShell()
    } else {
        return runContainer()
    }
}

process.argv contains the entire command line, including the command used to start DevPail, so we slice it out, and check what's left for command line arguments. We always check that there are any arguments at all, and then if the first one is something we want to act on.

In our very simple case, the above works well enough. However, for anything even slightly more complex, you'll want to look into a package such as yargs to handle your command line arguments.

Now that we have our basic flow in place, we can flesh out the details.

Fleshing out the details

Building `--build`

We've already know how to build the DevPail image from the command line:

docker build -t devpail imagesrc

Let's adapt that to Node. To run a docker, a shell command, we'll use the child_process module. And to tell docker where the Dockerfile is, we'll need to use the path module. Let's start by including those at the top of our script:

const { spawnSync } = require('child_process')
const path = require('path')

And then we'll Node-ify that command line:

function buildImage() {
    console.log('DevPail: Building image "devpail:default"...')
    spawnSync(
        'docker',
        [
            'build',
            '-t',
            'devpail:default',
            path.resolve(__dirname, '..', 'imagesrc')
        ],
        {
            shell: true,
            stdio: 'inherit'
        }
    )

That path.resolve(...) call uses the inbuilt __dirname constant to get the location of the running script (src/cli.js), and then step up one level, and give us the imagesrc directory in which our Dockerfile is housed.

--build: ✔

Running DevPail with no arguments

I'm going to skip ahead to the third point in the list, for reasons which will become apparent.

You'll recall that rather lengthy command line which runs the container:

docker run -it --rm -v myproject-tooling:/home/pn/app -v ~/myproject:/home/pn/app/src devpail

First Pass

Let's make this easier and a bit smarter.

We'll require that you run the devpail command (the one we're building now) from the root of the project you want to "DevPail-ize", as it were. This means that the current working directory should be the target project's name.

The solution will look much like that for --build, but with a few tweaks. Our first pass will look like:

function runContainer() {
    var project = path.basename(process.cwd())
    spawnSync(
        'docker',
        [
            'run',
            '-it',
            '--rm',
            '-v', `${project}-DevPail-Tooling:/home/pn/app`,
            '-v', `${process.cwd()}:/home/pn/app/src`,
            `devpail:default`
        ],
        {
            shell: true,
            stdio: 'inherit'
        }
}

Handling duplicate project folder names

Of course, you might use the same name for more than one project, but in different sub-trees, so we'll handle that case by adding a hash of the FULL path to the project's directory:

function createProjectName() {
    return path.basename(process.cwd()) 
        + '-' 
        + require('crypto')
            .createHash('md5')
            .update(process.cwd())
            .digest('hex')
            .slice(0, 8)
}

function runContainer() {
    var project = createProjectName()
...

Naming the container

Docker will create a name for each running container from a couple random words which bear no relation to the purpose of the container. Let's make that name meaningful. And while we're at it, let's do the same for the container's hostname, which will be useful later on.

function runContainer() {
    var project = createProjectName()
    spawnSync(
        'docker',
        [
...
            '--name', `${project}-DevPail`,
            '--hostname', project,
            `devpail:default`
        ],
...
}

devpail (no arguments): ✔

Implementing `--shell`

We can run a shell in our container by way of the --entrypoint argument to the docker command, as in:

docker -it --rm --entrypoint /bin/bash devpail

Of course, the above command line will also need all the other parameters we provided in the section above, and that sounds like --shell is just a special case of the no-arguments version of the devpail command.

Let's revisit processOptions() first:

function processOptions() {
...
    } else if (args && args[0] === '--shell') {
        return runContainer(['--entrypoint', '/bin/bash'])
    } else {
        return runContainer()
    }
}

Now let's handle those arguments in runContainer():

function runContainer(opts = []) {
    var project = createProjectName()
    spawnSync(
        'docker',
        [
...
            ...opts,
            `devpail:default`
        ],
...
}

--shell: ✔

Next Up: making Gulp work

At this point, we can easily build and run DevPail for a project, but it doesn't really accomplish anything just yet.

In the next installment of this series, we'll build out a pluggable GulpJS system that will actually do something useful.

I've made huge updates to the publicly available DevPail project, on both GitHub and NPM. It's evolved considerably since the first article, and I'm using it in production for several projects. So please feel to take a look at it. And then tune back in here to read more about the process of creating this tool!

Building a Docker/Gulp-based development environment: Introducing DevPail

Todd Esposito — Sun, 19 Dec 2021 23:30:34 GMT

This is the first in a series of articles about building DevPail, my general-purpose development environment tooling tool.

Days gone by

Oh, how I long for the days of yore. Especially Tuesdays. Tuesdays of yore were the best. Back then, building software was super simple. You could just fire up an editor, write some code, and build you software like this:

$ vimacs main.c
$ gcc main.c
$ ./a.out

Every. Single. Time.

But then you wake up (or move on to 200-level classes), and the world is much more complex. Now, because your project has grown to multiple source files, in multiple languages, using multiple technologies, you need... (insert ominous music) Tooling.

What is this "tooling" of which you speak?

The short version (and that's all you're getting, folks; Google's got you for the long version) is: the software you use to write and manage your software. In the example above, this is the editor with which you write the code, and the compiler/linker package you use to translate the code into an executable. But we're way beyond that in today's world. Now, we also have:

linters to validate our code is syntactically correct and properly formed
testing frameworks to make sure our code does what we expect it to
development servers to preview our code's operation while we work
packagers to wrap up our code into neat little bundles we can send to others
task runners to manage all of that stuff
so much more, just waiting to guide you down another rabbit hole

And not just one of each of those, but one or more for each and every language we use. Oh, you say, you're only using one language. I doubt it. For example, for web work you're likely using at least three of HTML, CSS, JavaScript, Python, Ruby and Go and, well, you get the idea.

Please don't get pedantic on the definition of a language here; Let's agree that these are at least dialects whose features and rules we have to learn.

What's the problem with tooling?

The issue, of course, is that each of these tools is itself software, and as such, undergoes the same churn as all software projects. We find and fix bugs. We add, revise and remove features. We replace some tools entirely in favor of something newer or more well-suited to what we're doing. And some fall into disrepair out of neglect or abandonment.

In a project started just a year ago, the tooling may have become unusable because it's not compatible with the latest version of some other tool, or the underlying platform. In projects even older, this is nearly guaranteed.

I've had the pleasure of having to tell a client that, yes, I can add that relatively small feature to their website, but the cost of revising the tooling will cost more than the feature. And, no, their previous developer didn't keep the tooling specs pinned to the versions which worked back then. This is NOT a happy conversation, for either of us.

In addition, every new platform, library and framework brings with it more tooling. So while the tooling from your last project may work, it'll need at a minimum some tweaks to work with the new stuff. And when you go back to a previous project and the tool flow you're used to isn't there, you either end up fighting you own tools or "investing" time retrofitting the new tools into the old workflow.

We need a bucket of tools we can carry with us

You know those 5-gallon bucket and apron combos people use to carry their tools from job to job? (Hint: check out the cover image for this article.) Everything's in there: tools, spare parts, old candy wrappers, everything! And the entire bucket, unaltered, moves from job to job with ease.

I want one of those for software tooling. So I built one, and I call it DevPail (yes, it's on GitHub). It's not a silver bullet for every possible werewolf, but it makes me happy.

Please note, the version available on GitHub, as of this writing, is very young, not feature-complete, and not well documented. I'm actively working on it. Patience is a virtue.

Let's walk through building it together!

Designing DevPail

The general philosophy is that we have three concerns in building our development environments, which we want to keep separate:

All the infrastructure (i.e. NodeJS or Python) lives in the bucket, which can be moved easily from job to job -- and this is important -- without alteration. One ring to rule them all, so to speak.
The project-specific tooling (i.e. node_modules or site-packages) are carried around with the bucket, like the apron. Separate, but connected.
The project's code lives on the host system (well, probably in a source control repo somewhere, but that's picking nits).

The bucket: Docker

I tried using VMs to contain all my tooling for a project, but for my needs at least, that's like swatting a fly with a sledgehammer. I need a much lighter tool, which doesn't take two minutes to boot. Docker provides just what we need.

The apron: Gulp

I've been using Gulp for years, but I'm really tired of needing to copy/paste/tweak/cus/tweak the gulpfile every time I start a new project. While I like Gulp in general, I want a plug-able solution which can be configuration-driven rather than strictly code-driven. Gulp, in its infinite coolness, can be made to meet that objective.

The tools: Everything else, on demand, as needed

Each project, naturally, has it's own requirements for platform and tooling, so those should be configurable easily. Ideally by setting a couple of entries in a package.json file.

Enough exposition, let's build

Let's start by creating a directory for our project directory, and some subidirectories. Next, let's build a Dockerfile:

$ mkdir -p devpail/imagesrc/homedir
$ cd devpail
$ vimacs imagesrc/Dockerfile

We'll talk about that homedir entry below, and in the following installments of this series.

Choose a base image

DockerHub contains (no pun) images to meet needs both sublime and obscene... ok, wait, that's over the top. There are lots of images there, and you'll surely find one you like.

I've chosen one which gives us Python 3.8 and NodeJS 14 because that matches my most common deployment environments. This image includes a non-root user called pn whose home directory is, of course, /home/pn.

# syntax=docker/dockerfile:1
FROM nikolaik/python-nodejs:python3.8-nodejs14

The Dockerfile we're building here is a somewhat simplified version of what you'll see in the GitHub repo, for the sake of clarity.

Add Gulp to the image

We'll need the Gulp CLI, so we add that to the image. Not much to see here.

RUN npm install --global gulp-cli

Setup our container environment

We want to use bash rather than the Docker default sh for reasons which will become apparent later on.

We also want to be able to run any tools we've added via pip/poetry and npm/yarn, so we set up some environment variables which we'll leverage... later on, and update our PATH.

SHELL ["/bin/bash", "-c"]

ENV PYTHONROOT="/home/pn/app/site-packages"
ENV PYTHONPATH="${PYTHONROOT}/lib/python3.8/site-packages"
ENV NODE_PATH="/home/pn/app/node_modules/.bin"
ENV PATH="/usr/local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:${PYTHONROOT}/bin:${NODE_PATH}"

Create our container directory structure

As stated above, our base image gives us a pn user, so we'll make our tools run in the container as that user. It's a best practice to avoid running anything as root, even inside a container.

We'll copy a few files we need into the image from the homedir we made before into the home directory of the pn user, and ensure those files are owned by pn.

We will mount a volume to hold all the per-project tooling under /home/pn/app, and ensure that directory is writable by pn.

USER pn
COPY --chown=1000:1000 homedir/* /home/pn
WORKDIR /home/pn/app
RUN chown 1000:1000 /home/pn/app

Make our container's server accessible

Our Gulp process will spin up one or more server processes, on ports 3000 through 3009. Yes, it's more than we likely need, but the cost is near zero, and gives us lots of flexibility, so why not? Let's ensure we can connect to those ports from our host.

EXPOSE 3000 3001 3002 3003 3004 3005 3006 3007 3008 3009

Run our development tooling

Finally, when we run the container, we (usually) want to run our default Gulp task.

ENTRYPOINT [ "/bin/bash", "-c", "gulp" ]

Build and run the image

Building the image is pretty straightforward. We ask Docker to build the image described by the Dockerfile in imagesrc, and we tag (-t) that image as devpail.

$ docker build -t devpail imagesrc
... (lots of docker output) ...

Running it will take a bit more work, so we'll walk through the command line bit by bit. Here it is:

$ docker run -it --rm -v myproject-tooling:/home/pn/app -v ~/myproject:/home/pn/app/src devpail

docker run tells docker to... um... run an image.
-i (interactive) and -t (tty), which we've abbreviated as -it, allows us to interact with the container. Basically, we're "shelling" into the container.
--rm (note the double-dash here) tells Docker to remove the container when it exits.
-v myproject-tooling:/home/pn/app mounts a named volume to ~/app. This will hold our per-project tooling, keeping it nicely wrapped up.
-v ~/myproject:/home/pn/app/src mounts our project's directory. Replace this with your actual project directory.
devpail is the image we want to run.

$ docker run ...(as above)
[01:02:34] Local gulp not found in ~
[01:02:34] Try running: npm install gulp

We've build an image, and then run that image in a container. It didn't DO anything, but it's a good start.

In upcoming articles, we'll build our Gulp tasks, simplify running all those docker commands, and make DevPail a bit smarter. Not necessarily in that order. Stay tuned!

This Just In: Yet Another Local Web Server

Todd Esposito — Sat, 02 Oct 2021 05:17:57 GMT

Fact is, I should not have built this code. I'm sure that somewhere, there's a suitable NPM or PyPi package (or something in some other language) which would have worked out just fine. But nothing I saw on the first page of my search results seemed like it was both the correct functionality AND light-weight enough.

I'm using GitPages to host the documentation and demos for my little Web Components library. The docs are Markdown files, which GitPages dynamically converts to HTML for me. So surely there's a local equivalent I can use to test my updates prior to publication, right?

Jekyll, et al, Not Really to the Rescue

The "official" method is to install Jekyll and a bunch of other tooling. Jekyll is written in Ruby, and I don't use Ruby myself (no offense), so it seemed like a bridge too far to install an entire language system just to test this one thing. I would spend more time configuring that then writing the docs. Bleh.

There are several "markdown web servers" out there too, but they uniformly seem to just want to server markdown, and not do that nifty GitPages translate-on-the-fly thing. Maybe I just missed the silver bullet. Too late if I did, because I wrote one in about 90 minutes.

I LOVE to tinker

I know JavaScript reasonably well, so why not just dive in? I legitimately spent less time building what I present here than I had researching a pre-built solution.

So let's talk code, eh?

First, as in any project a complete, well-thought-out plan was needed. Except I didn't make one, exactly. As is my habit, I start by writing code that just won't work, but expresses the basics:

I need an HTTP server
which sends files from the current directory
and processes Markdown into HTML on the fly
and if a request for an .html resource comes in but no such file exists, try the corresponding .md file
and if the URL looks like a directory, serve up index.html (which could actually be index.md)
and gives meaningful errors as needed

We'll set up a project

mkdir mdserver
cd mdserver
npm init -y

and add this code as index.js:

const http = require('http')

// create a simple HTTP server
const server = http.createServer((req, rsp) => {
  // convert the requested URL to a local pathname
  let pathname = resolveUrl(req.url)

  // send the content from that pathname, or an error
  return resolvePath(pathname)
})

// listen for requests.
server.listen(3000, "localhost", () => {
   console.log(`ehMDserver: running at http://localhost:3000/`)
})

This stub doesn't won't actually work, because I haven't defined resolveURL() and resolvePath(). That's OK, it's all part of my process of starting from a relatively high level, and then drilling down into the details.

Let's convert the URL to a local pathname

This one is currently super simple, but later we'll add some additional features, so hang tight:

const pathlib = require('path')
...
function resolveUrl(url) {
  return pathlib.resolve(`./${url}`)
}

Now you may be thinking, "how does he know we'll add features later?" Well, truthfully, I didn't. But the principle of mapping out the high-level steps means that if this never evolves, the main function is still readable. And if it does evolve, the main function is still readable.

Now let's send a file

For starters, let's just send, verbatim, whatever file is requested.

const fs= require('fs')
...
function resolvePath(path) {
  if (fs.existsSync(path)) {
    if (fs.lstatSync(path).isFile())  {
      return sendFile(path)
    }
  }
}

You'll note that I've once again called a non-existent function, but -- again -- you get what this thing is doing.

Now we'll need to implement sendFile():

function sendFile(path) {
  body = fs.readFileSync(path)
  rsp.writeHead(200,
    {
      'Content-Type': 'text/plain',
      'Content-Length': Buffer.byteLength(body)
    }
  )
  rsp.end(body)
}

We read the file from disk, send HTTP headers Content-Type and Content-Length and send the file contents to the client.

And now we have a problem: our rsp (response) object, which came into our main function, needs to be here too, so we'll pass it all down the chain. In fact, as long as we're at it, let's send the req (request object) as well. Could prove useful later, and for now we're not worried about a linter complaining.

function resolvePath(req, rsp, path) {
...
      return sendFile(req, rsp, path)
...
}
function sendFile(req, rsp, path) {
  body = fs.readFileSync(path)
  rsp.writeHead(200,
    {
      'Content-Type': 'text/plain',
      'Content-Length': Buffer.byteLength(body)
    }
  )
  rsp.end(body)
}

const server =  http.createServer((req, rsp) => {
...
  return resolvePath(req, rsp, pathname)
})

Now when we run node index.js and visit http://localhost:3000/index.js we'll get back the content of index.js unaltered.

But we'll need some special handling for Markdown files, so let's add that special case to our sendFile() function:

function sendFile(req, rsp, path) {
  if (path.endsWith('.md')) {
    return sendMarkdown(req, rsp, path)
  }
  body = fs.readFileSync(path)
  rsp.writeHead(200,
    {
      'Content-Type': 'text/plain',
      'Content-Length': Buffer.byteLength(body)
    }
  )
  rsp.end(body)
}

Commence Markdownification

Ah, Internet, how I love thee! There are plenty of libraries which will convert Markdown into HTML, all just a search-engine away. Let's add one to our project:

npm install --save showdown

And write our sendMarkdown() function:

const showdown  = require('showdown')
showdown.setFlavor('github')

function sendMarkdown(req, rsp, path) {
  body = fs.readFileSync(path, 'utf-8')
  converter = new showdown.Converter()
  html = ''
    + converter.makeHtml(body)
    + "";
  rsp.writeHead(200,
    {
      'Content-Type': 'text/html',
      'Content-Length': Buffer.byteLength(html)
    }
  )
  rsp.end(html)
}

Since the showdown converter doesn't wrap it's output in html tags, we do that inline, and set the content type correctly.

What about all those other file types?

So far, we've completed a few of the original goals. Let's modify sendFile() to handle more file types, including those we will likely encounter along the way.

function sendFile(req, rsp, path) {
  let ctype
  ext = path.split('/').slice(-1)[0].split('.').slice(-1)[0]
  switch (ext) {
    case 'css':
    case 'html':
      ctype = `text/${ext}`; break
    case 'gif':
    case 'jpeg':
    case 'png':
      ctype = `image/${ext}`; break
    case 'jpg':
      ctype = 'image/jpeg'; break
    case 'js':
      ctype = 'text/javascript'; break
    case 'md':
      return sendMarkdown(req, rsp, path)
    default:
      ctype = 'text/plain'
  }
  body = fs.readFileSync(path)
  rsp.writeHead(200,
    {
      'Content-Type': ctype,
      'Content-Length': Buffer.byteLength(body)
    }
  )
  rsp.end(body)
}

We capture the file extension (if any), and add a switch statement to map the usual gang of file extensions (with a special case for .jpg) the the correct MIME type. Yes, there are libraries for this, but this suffices for our very simple needs, and keeps the project lightweight.

Now we can serve up files which are named explicitly, and we are converting Markdown to HTML, but we are not handling directory indexes or mapping an .html URL to a corresponding .md file.

Handling directories and non-existent paths

If you visit http://localhost:3000/, the request will time out, because we're not sending any data unless we find a file, and / is NOT a file, per-se. What we really want is to serve an index file (either index.html or index.md) when a request maps to a directory. And we want to send back a 404 error if we can't find the requested file or the index for a directory.

Let's modify resolvePath() a bit:

function resolvePath(req, rsp, path) {
  path = pathlib.normalize(path)
  if (fs.existsSync(path)) {
    if (fs.lstatSync(path).isFile())  {
      return sendFile(req, rsp, path)
    } else if (fs.lstatSync(path).isDirectory()) {
      return resolvePath(req, rsp, `${path.replace(/\/$/, '')}/index.html`)
    }
  } else {
    return sendError(req, rsp, 404))
  }
}

First, we normalize the path to account for segments like ../../stuff and other variations.

Then, if the path exists and is a file, we call sendFile() as before. If it's a directory, we call resolvePath() (recursively) for a theoretical index.html in that directory. We do a little regex work to ensure have exactly one '/' between the original URL and index.html. If the path doesn't exits, we'll call sendError() to send back a 404-Not-Found. Probably should write that, too:

function sendError(req, rsp, code) {
  messages = {
    404: "Not Found"
  }
  rsp.writeHead(code, {'Content-Type': 'text/html'})
  rsp.end(`${code} ${messages[code]}
`)
}

Serving Markdown where HTML was requested

If the URL ends in .html, but no such file exits, we should look for a file with the same name, but ending in .md. This, once again, is handled by resolvePath():

function resolvePath(req, rsp, path) {
  path = pathlib.normalize(path)
  if (fs.existsSync(path)) {
...
  } else if (path.endsWith('.html')) {
    // Maybe there's a corresponding .md file we can send instead?
    return resolvePath(req, rsp, path.slice(0, -5) + ".md")
  } else {
    return sendError(req, rsp, 404)
  }
}

We've wedged another if-clause between "the path exits" and "send a not-found" which will, if the path ends in .html, call resolvePath() with the updated pathname.

All the boxes ticked!

That wraps it up. We've completed all of the original objectives, to wit:

We have an HTTP server
which sends files from the current directory (with the correct MIME-types, mostly)
and processes Markdown into HTML on the fly
and if a request for an .html resource comes in but no such file exists, it tries the corresponding .md file
and if the URL looks like a directory, it serves up index.html (which could actually be index.md)
and gives meaningful errors as needed (just 404, but they're meaningful!)

You may recall I mentioned adding features to resolveURL(), but those aren't covered here. You can find a more complete version of this code in the eh-mdserver GitHub project, which has a few more tricks up it's sleeve.

The repository also contains the version we built here for your kind consideration.

As always, your constructive comments are very welcome!

Events: Web Components Phone Home

Todd Esposito — Wed, 15 Sep 2021 23:07:06 GMT

This is (probably) the final installment in my series on Web Components, which you should totally check out if you haven't already, not only because I wanted to use the phrase "totally check out" in print, but also because those previous couple of articles lay the groundwork for understanding this one.

Obligatory Recap

In the previous articles, we've built a reasonably capable component which let's us add a "loading" screen to a web page. You add the component to the page in a few lines of code:

<html>
<head>
  <script src="eh-loading-modal.js">script>
head>
<body>
  <main>some content heremain>
  <eh-loading-modal>eh-loading-modal>
  <script>
     const loader = document.getElementsByTagName('eh-loading-modal')[0]
     loader.show()
     setTimeout(() => loader.hide(), 5000)
  script>
body>
html>

We include the components source in the , drop the component on the page with the tag, and manipulate it with JavaScript.

Huh? Events?

Events are signals you can listen for and respond to in your code. For example, you've probably seen code like:

node.AddEventListener('click', somefunction);

This tells your browser that when a users "clicks" on that particular node, it should run your somefunction() code. DOM nodes "emit events" during interactions with the person on the other side of the screen, or when other "interesting" things happen. Different interactions result in different events, of course, and there are a handful of standardized events. Ok, it's LARGE handful.

You can, in your code, emit these standard events or create your own custom events.

Emitting an Event

Our component isn't a very good candidate for an event source. It intentionally doesn't interact with the user, and it doesn't much matter if the window is resized, or the battery goes low. But lack of solid reasons never stopped me before, so ... onward!

We're going to have our component emit an event whenever it is shown or hidden. I know, it's unlikely such a feature would be useful, but, like the plot in every RomCom ever put to film, let's just pretend it makes sense.

First, let's revisit our component's code, specifically the show() and hide() methods:

window.customElements.define('eh-loading-modal',
  class EhLoadingModal extends HTMLElement {
...
    show() { this.setAttribute("visible", "") }
    hide() { this.removeAttribute("visible") }
...

If you've forgotten what these are doing, please see Slots and Properties and Attributes, Oh My!. Basically, call show() to show the modal, and hide() to hide it.

We want some events to come out of the component when it goes from hidden to showing, and from showing to hidden (again, as in a RomCom, it's best not to question it), so let's revise those methods slightly:

window.customElements.define('eh-loading-modal',
  class EhLoadingModal extends HTMLElement {
...
    show() { 
      this.setAttribute("visible", "")
      this.dispatchEvent(new CustomEvent("show"))
    }
    hide() {
      this.removeAttribute("visible")
      this.dispatchEvent(new CustomEvent("hide"))
    }
...

Pretty straightforward. We do the work needed to effect the transition we want, and then we call dispatchEvent() to send out a custom Event. The dispatchEvent() method is inherited from HTMLElement, so we don't need to worry about it.

Now, let's update our POC page, crack open the Console window in your favorite browser and test it out:

<html>
<head>
  <script src="eh-loading-modal.js">script>
head>
<body>
  <main>some content heremain>
  <eh-loading-modal visible>
    <h2>Please Waith2>
    <p>We're loading your report. This could take a moment.p>
  eh-loading-modal>
  <script>
     const loader = document.getElementsByTagName('eh-loading-modal')[0]
     loader.addEventListener('show', e => console.log("Modal is showing"))
     loader.addEventListener('hide', e => console.log("Modal is hidding"))
     loader.show()
     setTimeout(() => loader.hide(), 5000)
  script>
body>
html>

You should get something very like this in your Console:

Why not "Standard" Events?

When you use addEventListener(), you specify a string naming the event, which matches what we send via dispatchEvent(). And, as shown above, you create a CustomEvent object to carry your event. But you can ALSO use a "standard" event:

        this.dispatchEvent(new Event("change"))

Events like "change" and "click" are in common usage. We all understand what they mean in the context of standard HTML nodes, like an or a

Component Styling For Fun and Profit

Todd Esposito — Mon, 23 Aug 2021 15:19:59 GMT

In the continuing saga of our Web Component building journey, we now turn our attention to allowing our web components to be styled. In case you missed it, we've been building a "loading modal" web component, and we've added some customizability via slots, properties and attributes already.

This component gives us a nice, simple way to drop a commonly-used feature into a web page. Load the component via