DEV Community: Tiger Oakes

Deploy a site to GitHub Pages from multiple branches using GitHub Actions

Tiger Oakes — Sat, 26 Dec 2020 00:00:00 +0000

I’ve been moving many repositories over to GitHub Actions to automate deployment and testing. One of my projects uses GitHub Pages, but includes data from two different branches:

The main branch contains the bulk of the website
The app-challenge branch contains a second site that appears under a /heleon/ path

Using GitHub Actions, I set up the site pull from both branches before deploying. The script looks like this:

name: Deploy from two branches

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      # Checkout the `main` branch
      - uses: actions/checkout@v2
      # Install Node.js
      - uses: actions/setup-node@v2-beta
        with:
          node-version: '14'
      # Install npm dependencies
      # (similar to npm install)
      - run: npm ci
      # Run code to build the site files inside the `big-island-buses` folder
      - run: npm run build

      # Checkout the `app-challenge` branch
      - uses: actions/checkout@v2
        with:
          ref: app-challenge
          # Put the checked out files inside the `big-island-buses/heleon` folder
          path: big-island-buses/heleon
          clean: false
      # Delete the .git folder from `big-island-buses/heleon`
      # This turns the files into a plain folder instead of a git repository
      - run: rm -rf big-island-buses/heleon/.git
      # Deploy the `big-island-buses` folder to GitHub Pages
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: "./big-island-buses"
          user_name: 'github-actions[bot]'
          user_email: 'github-actions[bot]@users.noreply.github.com'

The first sequence of steps checks out the main branch, installs Node.js and npm dependencies, then runs the build script. The files created by the build script end up in a folder named big-island-buses.

The second sequence checks out the app-challenge branch, and places the files inside a folder named heleon, which is a subfolder of big-island-buses. These files are static so they don’t have a separate build script.

However, putting one git repository inside another like this creates problems for the GitHub Pages script. Deleting the .git folder turns the git repository into a plain folder.

Going from Android LinearLayout to CSS flexbox

Tiger Oakes — Fri, 18 Dec 2020 00:00:00 +0000

Are you an Android developer looking to learn web development? I find it easier to learn a new technology stack by comparing it to a stack I’m already familiar with. Android developers can layout views using the simple yet flexible LinearLayout class. The web platform has similar tools to layout elements using CSS, and some concepts are shared. Here’s some tips to learn web development using your Android knowledge.

Let’s focus on a horizontal layout, similar to a LinearLayout with the "horizontal" orientation. The layout in Android may look something like this:

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    id="@+id/horizontal"
    android:layout_width="200dp"
    android:layout_height="100dp"
    android:orientation="horizontal"
    android:gravity="center_vertical|center_horizontal">

  <TextView
    id="@+id/child1"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:layout_weight="1"
    android:background="#bcf5b1"
    android:text="One" />

  <TextView
    id="@+id/child2"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:layout_gravity="top"
    android:background="#aacaff"
    android:text="Two" />

  <TextView
    id="@+id/child3"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:background="#e3e2ad"
    android:text="Three" />

</LinearLayout>

On the web, layouts are split across two languages: HTML for declaring elements (similar to XML files in Android declaring views) and CSS for declaring styling (similar to the styles.xml file).

<div id="horizontal">
  <span id="child1">One</span>
  <span id="child2">Two</span>
  <span id="child3">Three</span>
</div>

#horizontal {
  width: 200px;
  height: 100px;
  display: flex;
  flex-direction: row;
  justify-content: center;
  align-items: center;
}

#child1 {
  background: #bcf5b1;
  flex-grow: 1;
}

#child2 {
  background: #aacaff;
  align-self: flex-start;
}

#child3 {
  background: #e3e2ad;
}

These files look somewhat similar to the Android XML, except that most attributes have been moved to CSS and have different names. CSS allows you to specify blocks of rules. Rules have a selector to indicate which element the styles are applied to, with the # character corresponding to an ID. Inside the rules are various declarations: pairs of properties and values.

Let’s break down some of these properties and how they correspond to Android’s LinearLayout.

width and height

The CSS width and height properties correspond to android:layout_width and android:layout_height. The pixel unit (px) is used in place of density independent pixels (dp). CSS pixels correspond 1:1 with density independent pixels, and do not necessarily correspond to the actual amount of pixels and element takes up on a device.

Inline text elements like span default to wrapping their content, so we don’t need to set an explicit width and height.

display: flex

The display property sets the layout used for an element’s children. It’s used in place of the LinearLayout tag to specify the layout system. Having this information in CSS instead of the HTML/XML allows web developers to change the layout system in response to screen size or other factors.

The flex display value, also known as Flexbox layout , corresponds roughly with LinearLayout, and I’ll focus on it in this post.

flex-direction

flex-direction lets you set the layout direction, just like the android:orientation attribute. Rather than "horizontal" and "vertical", you can set the value to be row or column. Just as LinearLayout defaults to horizontal orientation, flexbox direction defaults to row.

justify-content and align-items

In Android, the gravity for a view can be set on both axis in a single attribute. center_vertical and center_horizontal can be used at the same time, or even combined into the shorthand android:gravity="center".

CSS breaks up the attribute into two different properties, depending on the axis. These properties are relative to the flex-direction rather than the absolute direction, so “top” will be different between horizontal and vertical content.

justify-content sets the alignment of items in the direction of the flexbox. When flex-direction is set to row, justify-content affects the horizontal layout. Using the value center corresponds with android:gravity="center_horizontal".

align-items sets the alignment of items perpendicular to the direction of the flexbox. When flex-direction is set to row, align-items affects the vertical layout. Using the value center corresponds with android:gravity="center_vertical".

flex-grow

Children of a LinearLayout can have a layout_weight assigned to them, allowing the child to be stretched. Available space will be distributed among children based on their weight values, which defaults to 0. CSS flexbox has the equivalent flew-grow property, which has the exact same behavior.

align-self

The alignment of a single item in a flexbox can be overridden using the align-self property. This corresponds with android:layout_gravity. Like align-items, the values are perpendicular to the flex-direction instead of absolute directions. When flex-direction is set to row, flex-start represents the top of the container. Similarly, flex-end represents the bottom of the container.

Flexbox layout is capable of much more than LinearLayout, and its a commonly used tool in web development. If you’re looking to work on some CSS, or if you’re a web developer reading this post in reverse, I hope this comparison helped you!

The secret trap when using ANY in TypeScript

Tiger Oakes — Tue, 13 Oct 2020 00:00:00 +0000

What is `any`?

If you’re working with TypeScript, chances are you’ll work with the any type. any essentially turns off typechecking, and allows the corresponding variable to be used for anything. You can call any methods on an any variable, and they’ll all return any as well. It’s great when you can’t write types for everything in your codebase.

let obj: any = { x: 0 };
// None of these lines of code are errors
const foo: any = obj.foo();
obj();
obj.bar = 100;

What are function overloads?

TypeScript has another neat feature called function overloads. Some JavaScript functions return different results based on the arguments you supply, and this can be represented in TypeScript by written multiple function types on top of each other. Only one function signature can match at a time. The matching overload is determined by the arguments you supply to he function. The first applicable overload will always be chosen.

function convertType(value: string): number;
function convertType(value: number): string;
function convertType(value: string | number): number | string {
  if (typeof value === 'number') {
    return value.toString();
  } else {
    return parseFloat(value);
  }
}

const num: number = convertType('number');
const str: string = convertType(num);

Using overloading with arrays

Some functions want to transform an array in some way, and return an array with the same length and slightly modified types. A good example of this is Promise.all, which transforms an array of promises into a single promise that resolves with an array of values.

Using generic function definitions, you can infer the type of the array passed into Promise.all. However, the resulting type will be an array without positional data.

class Promise {
  static all<T>(array: (T | Promise<T>)[]): T[];
}

Promise.all([Promise.resolve(10), Promise.resolve('hello world')]).then(
  (result) => {
    // result's type is (number | string)[]
    // @ts-expect-error: Type 'string' is not assignable to type 'number'.
    const num: number = result[0];
  }
);

TypeScript does let you infer type of specific array items, but then you need to hardcode the length. Using overloading, you can have a couple of variations for different array lengths.

class Promise {
  static all<A, B, C>(
    array: [A | Promise<A>, B | Promise<B>, C | Promise<C>]
  ): [A, B, C];
  static all<A, B>(array: [A | Promise<A>, B | Promise<B>]): [A, B];
  static all<A>(array: [A | Promise<A>]): [A];
  // fallback to unknown length
  static all<T>(array: (T | Promise<T>)[]): T[];
}

Promise.all([Promise.resolve(10), Promise.resolve('hello world')]).then(
  (result) => {
    // result's type is [number, string]
    // This line is no longer an error
    const num: number = result[0];
  }
);

However, you can only write so many overloads. Eventually you need to fallback to an array with an unknown length like above. TypeScript’s official type definitions for Promise.all hardcodes arrays up to length 10, and fallback after that.

How `any` creates problems with overloads

Remember that any will match with any type, and that function overloads use the first applicable overload. These two facts cause problems when you pass a variable with type any into a function with overloads.

function convertType(value: string): number;
function convertType(value: number): string;
function convertType(value: string | number): number | string {
  if (typeof value === 'number') {
    return value.toString();
  } else {
    return parseFloat(value);
  }
}

const num: any = 10;
// @ts-expect-error: Type 'number' is not assignable to type 'string'.
const str: string = convertType(num);

The first overload is always used when you pass in a variable with type any, because it will be applicable to that signature. Even if there is a more generic signature later, the first overload is chosen. The overload ordering cannot be reversed, because the more generic signature will match every variable you pass in. As far as I know, you can’t write a signature that only matches if the variable is type any, because matching with anything works in both directions.

In the case of Promise.all, the first function overload signature is an array with a hardcoded length of 10. That can create confusing bugs like this, where any is passed in and the resulting type becomes an array of exactly 10 unknowns.

Evan™

@evantahler

Ok @typescript world - why is awaiting a map of `any` an array of *exactly* 10 `unknown`s?

22:31 PM - 12 Oct 2020

0 1

Future solutions

Hardcoding the array length isn’t great, because you can only support so many variations. TypeScript 4.0 introduces a new feature called “variadic tuple types”, which lets you capture the exact array argument and transform it. Future type definitions for Promise.all may replace all the function overloads with a single function signature, removing the any bug entirely.

TypeScript may also add special handling for passing any into function overloads in the future. If you know of an existing issue, or see something I missed, let me know.

TIL How to cache Kotlin Android view binding extensions

Tiger Oakes — Mon, 27 Jul 2020 00:00:00 +0000

In Android projects written with Kotlin, you can replace findViewById<ViewType>(R.id.view_id) calls by simply writing view_id. The Kotlin Android Extensions plugin adds this extension property automatically to Activities, Fragments, Views, and classes with the LayoutContainer interface.

However, views don’t cache the extension property. Using view.view_id is equivalent to calling findViewById every time and looking up the view over and over again. This is an easy mistake to make in fragments, where you can get the root view.

import kotlinx.android.synthetic.main.fragment_main.view.*

class MainFragment : Fragment(R.layout.fragment_main) {

  fun bindUi() {
    view.learn_button.setOnClickListener { ... }
    view.connect_button.setOnClickListener { ... }
  }
}

Prefer the extension property on Activities, Fragments, and classes with the LayoutContainer interface as those are cached. You can identify which version you use based on the import statement.

import kotlinx.android.synthetic.main.fragment_main.*

class MainFragment : Fragment(R.layout.fragment_main) {

  fun bindUi() {
    learn_button.setOnClickListener { ... }
    connect_button.setOnClickListener { ... }
  }
}

TIL How to use git branch aliases with Mozilla Central

Tiger Oakes — Mon, 20 Jul 2020 00:00:00 +0000

I just set up Mozilla Central with a git wrapper so I can contribute to the main Gecko codebase using Git. It works great, but the default branch has an unusual name compared to what I’m used to.

> git branch
branches/default/tip
bug1602126

You can create symbolic references in Git, so that the default branch has a name you’re used to.

> git symbolic-ref refs/heads/main refs/heads/branches/default/tip

> git branch
branches/default/tip
bug1602126
main -> branches/default/tip

> git checkout main
Switched to branch 'main'

> git status
On branch branches/default/tip

Maskable Icon template for Affinity Designer

Tiger Oakes — Sun, 12 Jul 2020 00:00:00 +0000

To support full-bleed icons on various platforms, there’s a new PWA icon purpose called “maskable icons”. By providing an icon with padding, the web browser can crop it to fit alongside other icons (especially on Android where different manufacturers use different shapes). You can read more about it on my posts on CSS Tricks and web.dev.

It can be difficult to design a maskable icon as you have to deal with several constraints without a clear preview of what the icon looks like. To help with that, I created Maskable.app. It lets you preview and edit your maskable icons on the web. However, if you’re designing icons in local design software you’ll need to export the icon before you can preview it. In order to quickly look at possible renderings, I created an Affinity Designer template based on Cyril Mottier’s Adaptive Icon Template.

The template makes use of a Affinity Designer 1.5 feature: Symbols. The left-most icon – labeled “Master” – is based on a symbol which is then duplicated to get different shapes. Any changes made to the master symbol will be directly replicated to the other copies. Symbols are marked with a solid orange border on the left. The template is licensed under the CC BY 2.0, just like the original template by Cyril Mottier.

Maskable Icon Template

TIL Android Studio can show KDocs on hover

Tiger Oakes — Fri, 10 Jul 2020 00:00:00 +0000

I like easy access to documentation written in comments. In Android Studio, and other JetBrains editors, you can display function types and docs on hover when you turn on a simple setting.

In Android Studio’s settings window, go to “Editor” > “General” and check “Show quick documentation on mouse move”. You can leave the delay at the default value.

When editing code, you can quickly check documentation by just hovering over code.

Experimenting with using Eleventy for web apps

Tiger Oakes — Mon, 13 Apr 2020 00:00:00 +0000

This weekend I’ve been tweaking Big Island Buses, my bus schedule web app, and pre-rendering parts of the app. This was also my first time using Eleventy to build a site!

NotWoods / big-island-buses

A far easier to use unofficial schedule for the Hawaii Hele-On Bus. Created for the House Student App Challenege.

Like many web apps, most of Big Island Buses’ UI was generated on the client using JavaScript. Some very minimal HTML was sent by the server, and only contained the logo and some empty <div>s. Once the app is loaded up, JavaScript code connects to my API and builds new HTML elements on the client to represent bus routes and other information. However, until that API data is downloaded, an empty list of routes is presented to the user.

But is that really necessary? Bus schedules don’t change frequently. Why can’t the server always populate the list of bus routes in advance? I started experimenting with pre-rendering HTML in Node.js using Eleventy, and this is what I came up with.

To generate the HTML on the server, I went with Eleventy. Eleventy lets you import data from JSON files and use that in Nunjucks templates, which are then parsed to create HTML files. My first step was to expose my API inside the templates.

For Big Island Buses, the API is just a JSON file representing bus schedule data. Exposing it to Eleventy is as simple as moving the file inside a _data folder. However, this also results in no extra JSON files being generate for the client, which wouldn’t work for my use case. Luckily you can create a simple template file that spits out all the data as JSON again:

---
permalink: /api.json
---
{{ api | dump | safe }}

By default, template files like this are converted into files ending with .html. I can adjust that using the permalink option, and tell Eleventy to save a file using the .json extension instead. The dump filter here is built into Nunjucks, and tells it to print out the api variable as JSON data. Finally I use the safe filter so that no characters are escaped, such as quotation marks (").

Now that I have the API data on both the server and client, I can start using it elsewhere in the templates. I took my preexisting index.html file and converted it to a Nunjucks template, then added a for loop to insert all the bus routes.

<h2>Other Routes</h2>
<ul id="other">
{% for id, route in api.routes %}
<li style="border-color: #{{ route.route_color }}">
<a href="/routes/{{ id }}/">
{{ route.route_long_name }}
</a>
</li>
{% endfor %}
</ul>

Just like that, the list of routes is now pre-rendered on the server. Users never need to look at an empty menu again. Now all that’s left is updating the client code so that it doesn’t make a second copy of the list on screen. One naive solution is to just clear out the list when the JavaScript is ready, then run the same code as before.

const otherRoutes = document.getElementById('other');
otherRoutes.innerHTML = ''; // new code
populateList(otherRoutes, api.routes);

But that just repeats what the server has already done. It makes more sense to just remove this code entirely, and send less JavaScript to the client.

// intentionally left blank

Overall I enjoyed using Eleventy to help set up pre-rendering for Big Island Buses. I’ve been playing around with adding this functionality to the app for ages, but hadn’t found a good tool to accomplish it. Eleventy lets you use any JavaScript code you like, so some parts of the app (such as rendering schedule times) can share code while parts like the menu can use different systems. I’m hoping I can roll out more features in the future!

Scraping a 15-year-old Drupal site into Markdown files

Tiger Oakes — Sat, 07 Mar 2020 00:00:00 +0000

Your mission is to migrate a website from a server-side CMS to Jamstack. The site is 15 years old and is currently built with Drupal. All the pages need to be converted to markdown. And by the way, nobody knows the password to the server.

This is the mission I took on last year when I moved ubccsss.org to static rendering. I’m a computer science undergraduate at the University of British Columbia, and our CS club, UBC CSSS, has been around for over 50 years. The club’s website is a tad newer, and was created in 2005. Being a student club meant two things: the staff changed every year, and there was no documentation. Everyone was unfamiliar with the server, and many passwords had been lost to time. Crucially, we didn’t have passwords for the Drupal database, so we couldn’t use existing tools to migrate from Drupal to other systems.

Drupal is a server-side Content Management System (CMS) like Wordpress. It lets you create new pages on your site using a graphical admin interface, and handles publishing for you. When someone navigates to the website, Drupal loads pages from its database and renders the HTML on the fly for each visitor.

Drupal makes the creation of basic posts simple, but also complicates changing the overall website layout. The site banner, footer, and other pages throughout the site use raw HTML and Drupal doesn’t expose a simple way to edit that. While many students have some experience creating websites for personal projects, very few have experience tweaking CMSes like Drupal. Our hands were tied whenever we wanted to make larger changes to the site design.

I started an initiative to move our website to the Jamstack. Jamstack refers to creating static HTML files and serving those directly, with no database involved. Posts would be represented as Markdown files in a Github repository, then HTML would be generated from those files on new commits. Rather than rendering HTML on the fly, all visitors are sent the exact same HTML file. Markdown and Github are familiar tools for CS students, so they were suitable for this student site.

With no server passwords, I had to explore alternative ways to move the site out of Drupal. Luckily we still had access to the admin panel. There, I had quick access to all the posts published since the website was created. Since I couldn’t access the database, I went for a different route: scraping all the HTML pages on the website.

Gathering a list of all the pages

The first step was to collect all the page links in the Drupal website into a single file that I could read later on. All the pages are listed in a table on the admin panel, making it straightforward to read the HTML table and store the data in the cells. However, the admin panel is gated behind a login, so I can’t just download the HTML from a command line and parse through it.

Rather than figure out the authentication system, I went for a different route: scrape the page using Firefox DevTools. By pasting a script into DevTools, I could run some Javascript while already logged in. Using querySelectorAll, I could get an of all the table rows on the page, then extract data from the cells.

/** Extract all the posts from this page */
function findLinks() {
  const rows = document.querySelectorAll('.table-select-processed tbody tr');
  Array.from(rows).map(row => {
    // Each child is a table cell. The underscores are for ignored cells.
    const [_c, titleCell, typeCell, authorCell, _s, updatedCell] = row.children;
    return {
      title: titleCell.textContent,
      link: titleCell.querySelector('a').href,
      type: typeCell.textContent,
      author: authorCell.textContent,
      date: updatedCell.textContent,
    };
  });
}

After converting the table into an array of objects, I created a hidden <a> tag to download the results as a JSON file.

const textData = JSON.stringify(findLinks());
// Create an in-memory text file and get a URL to the file
const file = new Blob([textData], { type: 'text/plain' });
const url = URL.createObjectURL(file);

// Make a link element then click it to download the file.
const download = document.createElement('a');
download.href = url;
download.download = `drupal.json`;
download.dispatchEvent(new MouseEvent('click'));

The final step in the script is to automatically navigate to the next page.

function nextPage() {
  const current = document.querySelector('.pager-current');
  if (current.nextElementSibling == null) return null; // Last page.

  const nextPage = current.nextElementSibling.querySelector('a').href;
  location.assign(nextPage);
}

All that’s left is to paste in the script each time we navigate to the next page. Many posts can be displayed on a single page, so in the end I only had to press “Ctrl-V” around 15 times. I put all the downloaded files into a new folder, and began working on additional tools.

Converting HTML to Markdown

Now that I had a list of public HTML pages, I could create a command-line script to download the HTML then convert it. I used fs-extra to read the downloaded JSON files, since it adds promise support to Node JS’ file system module.

const { readdir, readJson } = require('fs-extra');
const { join } = require('path');

async function scrapeAll(dataFolder, outFolder) {
  const dataFiles = await readdir(dataFolder);
  await Promise.all(
    // Iterate through list of JSON files
    dataFiles.map(async file => {
      const filePath = join(dataFolder, file);
      const json = await readJson(filePath);
      // Iterate through objects in the JSON array
      return Promise.all(json.map(node => scrapePage(node, outFolder)));
    })
  );
}

Each JSON object includes a link to the article, and some metadata downloaded from Drupal’s admin tables. All the HTML pages have the same base structure, so I could look for the <article> tag on each page and extra HTML from it.

To parse the HTML, I used cheerio. This module can quickly parse HTML text and lets you query it with jQuery’s API. This let me extract the core article HTML without opening the browser. I then used turndown to automatically convert the HTML into Markdown syntax.

const { outputFile } = require('fs-extra');
const { join } = require('path');
const fetch = require('node-fetch');
const cheerio = require('cheerio');
const TurndownService = require('turndown');

const turndownService = new TurndownService();

async function scrapePage(node, outFolder) {
  // Get HTML text from the page
  const response = await fetch(node.link);
  const text = await response.text();
  // Parse the HTML with Cheerio
  const $ = cheerio.load(text);

  // Get the HTML from the <article> tag
  const article = $('article');
  const html = article.html().trim() || '';
  const markdown = turndownService.turndown(html);

  // Add Markdown front matter at the start of the file
  const frontMatter = `---
title: ${node.title}
href: ${node.link}
type: ${node.type}
author: ${node.author}
date: ${getDate(node).toISOString()}
--------

`;

  const url = new URL(node.link, 'https://ubccsss.org');
  const fileName = join(outFolder, `${url.pathname}.md`);
  await outputFile(fileName, frontMatter + markdown);
}

function getDate(node) {
  // Dates in Drupal follow the format MM/DD/YYYY - HH:MM
  const DATE_REGEX = /^(\d{2})\/(\d{2})\/(\d{4}) - (\d{2}):(\d{2})$/;
  const [_, month, day, year, hour, min] = DATE_REGEX.exec(node.date);
  return new Date(`${year}-${month}-${day}T${hour}:${min}:00`);
}

This ensures that all the HTML pages I found are downloaded and converted to markdown. However, HTML isn’t the only important type of asset on the website. I also needed to download images, so I added some code to download from any <img> tags detected on the page.

const { createWriteStream, ensureDir } = require('fs-extra');
const { dirname, join } = require('path');
const fetch = require('node-fetch');

function downloadImages(article, outFolder) {
  // For each <img> tag...
  article
    .find('img')
    .toArray()
    // Turn the source into an absolute URL
    .map(img => new URL($(img).attr('src'), 'https://ubccsss.org'))
    // Ignore images from external sites
    .filter(url => url.host === 'ubccsss.org')
    // Download the image
    .forEach(async url => {
      const imagePath = join(outFolder, url.pathname);
      const [res] = await Promise.all([
        fetch(url),
        ensureDir(dirname(imagePath)),
      ]);

      const dest = createWriteStream(imagePath, 'binary');
      res.body.pipe(dest);
    });
}

Next steps

With these tasks completed, I now had a copy of 15 years of website content as Markdown files. The next phase was to take the Markdown and send it through a static site renderer. But that’s a story for another time.

If you’re curious to see the full code and exported data, it’s all available on Github.

ubccsss / drupal-export

Extract data from Drupal site

Automatic resume editor

Tiger Oakes — Tue, 30 Oct 2018 00:00:00 +0000

After writing my resume in Microsoft Word for years, I recently transitioned to generating it from plain HTML and CSS. This works much better for me because I can separate the resume content (my work experience and descriptions) from its layout (the colors and positions of text and number of columns). I added additional features so that I can edit the resume on-the-fly with JavaScript and quickly save a new copy, in case I don’t have access to my main machine and I need to make some small adjustments. Here’s how I did it.

Content with HTML and JSON Resume

The first step for displaying my resume online is to represent the data in a way the browser understands, with HTML. I started by converting my resume into JSON, following the JSON Resume schema. I use a static site generator for my website, so I wrote an template that read the JSON file and then wrote the corresponding HTML elements.

<header class="resume-header">
    <div class="name-container">
        <h1 class="name">{{.basics.name}}</h1>
        <p class="summary">{{.basics.summary}}</p>
    </div>
    <a class="resume-email" href="mailto:{{.basics.email}}">{{.basics.email}}</a>
</header>

Layout with CSS

When I first redesigned my website, I wanted to include my resume without just using an embedded PDF. Instead, I recreated my resume in HTML and CSS, so that it showed up as elements in the browser. I used some rarer CSS features like inch and centimeter units so the virtual “page” was still an 8.5”x11” sheet.

.resume {
  max-width: 8.5in;
  min-height: 11in;
}

Obviously this isn’t optimal because now I have two copies of my resume: a Microsoft Word document, and the online version. Every time I update the Word document, the corresponding HTML needs to be updated. Word was also becoming a hassle because I have the small blocks to the left of headers that need to be realigned, and often an extra blank page is created because of the two-column layout.

Generating a PDF from the site

I next set out to find a way to output a PDF from the online version of my site, so I could get rid of the Word version. The way most people make PDFs from some website is to just print it out. Easy! Unfortunately printing in web browsers has some weird bugs, and my layout turned into a 1 column design as soon as I opened the print preview.

If you were hoping to use Flexbox or CSS Grid in print stylesheets, you will probably be disappointed. You can check out the Chrome bugs for Flexbox and for Grid.

The best suggestion I can give right now is to keep your print stylesheets reasonably simple.

– A Guide To The State of Print Stylesheets in 2018 - Smashing Magazine

I got stuck here for a while as I tried different layouts. Eventually I settled on a table-based layout for the resume. CSS display: table allows me to do that without using the <table> HTML tag, so on mobile devices it can switch to a single column instead.

Scripting

At this point I now have my resume rendering in HTML, laid out with CSS, and generating a PDF. Everything works! Except…my site takes 10 seconds to regenerate the HTML files, so when editing the resume I need to wait 10 seconds then refresh the page, no matter what changes I make. This is a lot clunkier than just editing the text in Microsoft Word.

I decided to use JavaScript to update the page given my JSON data. I replicated my HTML template logic in JavaScript, so in the Inspector I could just call an update function and paste in my JSON.

function update(data) {
  // Header
  document.querySelector(".name").textContent = data.basics.name;
  document.querySelector(".summary").textContent = data.basics.summary;
  const email = document.querySelector(".resume-email");
  email.textContent = data.basics.email;
  email.href = `mailto:${data.basics.email}`;
}

Extras

I’m still not a fan of typing update(, paste, ), enter. Why not just paste in the JSON directly without having to call the function? I added a listener for the "paste" event that responds when I paste JSON onto the resume window.

document.onpaste = e =>
  update(JSON.parse(e.clipboardData.getData("text/plain")));

I also sometimes need to make small changes to my resume when I’m away from my computer. It would be nice to be able to edit the JSON in the web browser inspector. Using the Fetch API, I can load my JSON file in as a JavaScript object. I can use a Proxy object to detect when the object is changed, and then call update() automatically.

let jsonResume = await fetch().then(r => r.json());
const proxyHandler = {
  /** Recursive proxy for nested objects. */
  get(target, key) {
    if (typeof target[key] === "object" && target[key] !== null) {
      return new Proxy(target[key], proxyHandler);
    } else {
      return target[key];
    }
  },
  /** Update HTML when any changes are made */
  set(target, key, value) {
    target[key] = value;
    update(jsonResume);
    return true;
  }
};
window.resume = new Proxy(jsonResume, proxyHandler);

Proxy is used to add custom behavior when getting or setting properties. The set function is called when a setting a value, and is customized to also call my update function. The get function is customized to return a proxy for nested objects.

Next steps

In the future, I’d like to automatically generate a PDF from my markup and save it on the website for download, instead of manually using Print to PDF. wkhtmltopdf or Headless Chrome might be good tools for this.

It would also be helpful to have the rendered resume allow for text editing directly, instead of manipulating JSON in the inspector. The contenteditable HTML attribute lets a user change the text in an HTML element, but probably needs some tweaking to properly handle lists and emphasis.

You can see all of my source code on my GitHub repository for my website.

NotWoods / tigeroakes.com

My portfolio website. Designed to work offline, load quickly, and showcase some of my favorite projects.

Unifying code to read local and network files

Tiger Oakes — Fri, 26 Oct 2018 00:00:00 +0000

Many web applications let users either upload a file or enter a URL to download the file from.
When uploading files, the HTML file input lets you read the file using the FileReader API in JavaScript.
When downloading from the network, the fetch function is used.
With a tip from my manager at Google, I learned there's a way to use the same code for both local and network files with a simple trick.

How local files are read

JavaScript represents local files as Blobs.
Blobs represent raw binary data, and are seen in some other places like SQLite.
For a file, they represent its contents as binary data that needs to be converted to text.

JavaScript also offers the FileReader object, an API to read files (as it says on the tin).
It can be paired with a file picker input or a drag-and-drop target.
I'm just going to focus on the file picker for now.
You can use it like this:

async function loadLocalFile(file) {
    return new Promise((resolve, reject) => {
        const reader = new FileReader();
        reader.onload = event => {
            resolve(event.target.result);
        };
        reader.onerror = event => {
            reject(event.target.error);
        };
        reader.readAsText(file);
    });
}

form.onsubmit = async () => {
    const data = await loadLocalFile(fileInput.files[0]);
    console.log(data);
};

How network files are read

Every single page on the internet is identified by a URL (Uniform Resource Locator), which looks something like https://example.com/page.html.
URLs point to a location on the internet, and web browsers use them to look up where a website is located and then display its contents to you.

Getting data from another website page for your program is pretty easy in modern JavaScript using the fetch API.
You just pass a URL into the fetch function and it lets you wait for the text from the webpage to be downloaded.

async function loadNetworkFile(url) {
    const response = await fetch(url);
    return fetch.text();
}

form.onsubmit = async () => {
    const data = await loadNetworkFile(urlInput.value);
    console.log(data);
};

The unified code

Many web apps allow you to either select a file from your computer, or specify a URL to download it.
This is pretty common with image uploading but I've seen it for many different file types.
In my project Super Size, I wanted to let users specify the JSON data to load via a URL or local file without the need to duplicate a lot of code.
It would be ideal if the File object could be read with the fetch API, providing a simple uniform way to load data with Promises.
Turns out you can do just that!

You can create a URL pointing to a Blob using the URL.createObjectURL() function.
The function is commonly used to display an uploaded image, but works with any file type.
The resulting URL can be consumed with the Fetch API, so you can reuse the network code with a local file.

The one gotcha is that the URL needs to be freed afterwards, otherwise you have a memory leak by holding onto a pointer to the Blob object.
You can do that with the URL.revokeObjectURL() function.

async function loadNetworkFile(url) {
    const response = await fetch(url);
    return fetch.text();
}

async function loadLocalFile(file) {
    const url = URL.createObjectURL(file);
    const data = await loadNetworkFIle(url);
    URL.revokeObjectURL(url);
    return data;
}

form.onsubmit = async () => {
    let data;
    if (urlInput.value) {
        data = await loadNetworkFile(urlInput.value);
    } else {
        data = await loadLocalFile(fileInput.files[0]);
    }
  console.log(data);
};

You can see a more complex example of this in the source code for Super Size.
You can also see it in action on the live app.

DEV Community: Tiger Oakes

Deploy a site to GitHub Pages from multiple branches using GitHub Actions

Going from Android LinearLayout to CSS flexbox

width and height

display: flex

flex-direction

justify-content and align-items

flex-grow

align-self

The secret trap when using ANY in TypeScript

What is any?

What are function overloads?

Using overloading with arrays

How any creates problems with overloads

Future solutions

TIL How to cache Kotlin Android view binding extensions

TIL How to use git branch aliases with Mozilla Central

Maskable Icon template for Affinity Designer

TIL Android Studio can show KDocs on hover

Experimenting with using Eleventy for web apps

NotWoods / big-island-buses

A far easier to use unofficial schedule for the Hawaii Hele-On Bus. Created for the House Student App Challenege.

Scraping a 15-year-old Drupal site into Markdown files

Gathering a list of all the pages

Converting HTML to Markdown

Next steps

ubccsss / drupal-export

Extract data from Drupal site

Automatic resume editor

Content with HTML and JSON Resume

Layout with CSS

Generating a PDF from the site

Scripting

Extras

Next steps

NotWoods / tigeroakes.com

My portfolio website. Designed to work offline, load quickly, and showcase some of my favorite projects.

Unifying code to read local and network files

How local files are read

How network files are read

The unified code

What is `any`?

How `any` creates problems with overloads