PQINA

Updating CSS Border Radius When A Container Is Overflowing

2025-11-26T00:00:00Z

In this article we’ll create a container element that dynamically adjusts its border-radius when its contents overflows.

This week I learned about corner-shape via nerdy.dev. This led me down the path of adding big squircle corners to code blocks in the FilePond documentation. Great! But unfortunately they looked terrible when the scrollbar was active.

I wondered if I could detect (with CSS only) if a container is overflowing so I could dynamically lower the border-radius to fit the scrollbar, and I quickly found on bram.us that, yes, that’s very much possible.

So here we are, the CSS below detects the x and y overflow and then sets the per corner border-radius accordingly.

In short, the --overflows-x and --overflows-y custom properties are set to 1 if overflow is detected (with the CSS animation). The amount we subtract from the default border-radius --tl is multiplied by the --overflows variable which either sets it to 0 or results in a lowered border-radius.

We use max() to set the --br border-radius so if either of the two --overflows variables is 1 the border-radius is lowered.

Scroll down for demo’s, please note that at the time of this writing this only works in Chrome and Safari, see caniuse for latest support stats.

pre {
    /* fallback */
    border-radius: 0.5em;
}

/* corners */
@supports (animation-timeline: scroll(self)) {
    pre {
        --overflows-x: 0;
        --overflows-y: 0;
        animation: detect-overflow-x, detect-overflow-y;
        animation-timeline: scroll(x self), scroll(y self);

        /* the default border radius */
        --tl: 2em;

        /* what we subtract from the default when overflowing */
        --s: 1.5em;

        /* calculate the border radius for each corner */
        --tr: calc(var(--tl) - (var(--overflows-y) * var(--s)));

        --br: calc(
            var(--tl) - (max(var(--overflows-x), var(--overflows-y)) * var(--s))
        );

        --bl: calc(var(--tl) - (var(--overflows-x) * var(--s)));

        border-radius: var(--tl) var(--tr) var(--br) var(--bl);
    }
}

@keyframes detect-overflow-x {
    from,
    to {
        --overflows-x: 1;
    }
}

@keyframes detect-overflow-y {
    from,
    to {
        --overflows-y: 1;
    }
}

No scrollbars

When no scrollbars are active all corners use a big border-radius.

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Vertical scrollbar

We automatically lower the top right and bottom right border-radius.

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Horizontal scrollbar

When only a horizontal scrollbar is visible we lower the bottom left and bottom right border-radius.

Both horizontal and vertical scrollbar

Now we lower all the border-radius values except for the top left one.

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmodtemporincididuntutlaboreetdoloremagna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

How To Disable Right Click With JavaScript

2025-09-22T00:00:00Z

In certain situations it might be useful to disable the browser right click context menu functionality. In this article I’ll quickly show you how it’s done. As the context menu is an important user interaction pattern we of course shouldn’t disable it lightly, let’s take a look.

In my case I wanted to disable the right click interaction because it creates very strange situations when users drag an item and then accidentally click the right mouse button. Events fail to fire, or fire in another order, items get stuck, etc.

However the context menu triggered by the right click contains important functionality for the user (searching, printing, translating), so it’s smart to only disable it temporarily. In my case I only disable it when the user starts dragging an item.

Please note that at this time the "contextmenu" event doesn’t fire on iOS Safari

The code below will disable the context menu in all situations.

<script>
    document.addEventListener('contextmenu', (e) => {
        e.preventDefault();
    });
</script>

To only disable it in certain situations we can do with a basic if statement.

document.addEventListener('contextmenu', (e) => {
    // only disable the context menu when the user is doing something
    if (!userIsDoingSomething) {
        return;
    }

    e.preventDefault();
});

Alternatively we can add and remove the contextmenu event depending on if the user started a certain activity.

function preventContextMenu(e) {
    e.preventDefault();
}

// user started doing something, let's disable the context menu
function userStartsDoingSomething() {
    document.addEventListener('contextmenu', preventContextMenu);
}

// user stopped doing something, let's enable the context menu
function userStopsDoingSomething() {
    document.removeEventListener('contextmenu', preventContextMenu);
}

Performance wise there’s not much difference between these solutions. However it’s a bit more clean to only listen for the contextmenu event when it’s relevant, instead of always listening and checking if we should prevent the menu every time the right mouse button is pressed.

To disable right click on a selection of elements we can use the code below, in this case the event handler is attached to an element and the event will be prevented on the element and all its children.

<p id="my-element">Right click doesn't work here.</p>

<script>
    // Select the element
    const myElement = document.querySelector('#my-element');

    // Listen for the `contextmenu` event
    myElement.addEventListener('contextmenu', (e) => {
        e.preventDefault();
    });
</script>

Let’s see that in action.

The right click context menu doesn't work here.

Alright, that’s all there is to it, now you know how it’s done. Great power, great responsibility, please use it wisely.

Crop An Image With Canvas

2025-09-03T00:00:00Z

Cropping images in the browser can be done with the HTML5 canvas element. In this tutorial we’ll load an image from a local URL, crop the image, and present the result on the same page.

Okay, first we need an image. Let’s use the image below, it’s located at the URL: https://pqina.nl/media/test.jpeg

Our next goal is to load this image into a canvas element.

Loading an image in a canvas element

To draw an image to a canvas element we need to use the drawImage method on the 2d context of the canvas element.

<canvas id="my-canvas"></canvas>

This will create a 300 × 150 canvas on the page, we can adjust the width and height with the width and height attributes. For now we’ll try to draw our image.

// get a reference to the canvas element
const myCanvas = document.getElementById('my-canvas');

// then we need to access the 2d context of the canvas for drawing 2d imagery
const ctx = myCanvas.getContext('2d');

// now we draw the image
ctx.drawImage('/media/test.jpeg');

That doesn’t work unfortunately. The drawImage method expects the image in a different format, and it expects a dx and dy coordinate. Those are the x and y coordinates of the top left corner in the canvas where we start drawing the image.

We’ll load the URL into an <img> and then we’ll draw it to our <canvas>, I’ve put a red outline around it so we can clearly see it’s borders.

// get a reference to the canvas element and its 2d context
const myCanvas = document.getElementById('my-canvas');
const ctx = myCanvas.getContext('2d');

// the image we're going to draw
const myImage = new Image();

// we wait for the image to load, then we draw
myImage.onload = () => {
    // draw myImage at 0,0
    ctx.drawImage(myImage, 0, 0);
};

// the image we want to load
myImage.src = '/media/test.jpeg';

Tadaa, there’s our image. And it’s already cropped!

Cropping a square image in canvas

Let’s say we want to make a square crop. To achieve a square crop we’ll have to change the width and height of our canvas to the intended size of the resulting image.

<canvas id="my-canvas" width="256" height="256"></canvas>

Now we want to choose which part we crop, and that we can do with the dx and dy parameters.

Let’s say we want to crop the center. This means we need to use the canvas size and the image size to calculate the correct dx and dy coordinates.

We can get the image width and height using the naturalWidth and naturalHeight properties of the Image instance.

To calculate the center we subtract the image width from the canvas width and then we divide by 2, that puts the top left corner exactly where we want it.

myImage.onload = () => {
    const dx = (myCanvas.width - myImage.naturalWidth) * 0.5;
    const dy = (myCanvas.height - myImage.naturalHeight) * 0.5;

    ctx.drawImage(myImage, dx, dy);
};

That’s it, that’s how you crop an image using the HTML canvas element.

We can supply more parameters to the drawImage to also control the scaling of the image. We can control the quality of the scaling using the imageSmoothingQuality property but at the time of this writing it’s not available on Firefox.

Downloading the resulting image

Okay, we have our resulting image on the screen but we want it in our downloads folder.

We can do so by converting the <canvas> into a Blob using the toBlob() method on the canvas element (not the 2d context).

We’ll use the downloadFile function which we wrote in another article.

Additionally we’ll wrap the toBlob call inside a try catch statement, meaning that if something goes wrong, the site doesn’t crash and we can nicely handle the error.

myImage.onload = () => {
    // make the square crop
    const dx = (myCanvas.width - myImage.naturalWidth) * 0.5;
    const dy = (myCanvas.height - myImage.naturalHeight) * 0.5;
    ctx.drawImage(myImage, dx, dy);

    try {
        // convert to a blob
        myCanvas.toBlob(
            // this function runs when the blob has been created
            (blob) => {
                if (blob === null) {
                    // something went wrong
                    return;
                }

                // we use the `downloadFile` function from this article:
                // https://pqina.nl/blog/how-to-prompt-the-user-to-download-a-file-instead-of-navigating-to-it/
                downloadFile(blob);
            },

            // the image type of the resulting blob
            'image/jpeg',

            // the image quality of the resulting blob, a lower number means more compression
            0.5
        );
    } catch (err) {
        // something went wrong
        console.error(err);
    }
};

Please note that when loading images from remote URLs it’s possible that the remote site doesn’t allow drawing their images to a canvas.

More information on canvas and remote images can be found on MDN.

Using CSS Color-Mix() to lower anchor underline opacity

2025-02-28T00:00:00Z

A tiny code sample showing how to use the CSS color-mix function with currentColor to automatically lower the opacity of anchor underlines.

We can use CSS color-mix to mix two colors and get a new color. The currentColor property holds the selected elements color value.

Let’s combine them.

a {
    text-decoration-color: color-mix(in srgb, currentColor 30%, transparent);
}

In this link to the color-mix function on MDN, we can see the underline is less opaque.

Useful when you just want slightly nicer looking links.

Keep in mind that lowering the opacity too much will result in accessibility issues.

Building A Birthdate Input Custom Element

2024-12-10T00:00:00Z

In this article we look at a <birthdate-input> custom element that automatically orders input fields based on the browser locale. Useful for asking your customers to input their birthdate without presenting them with a datepicker.

Why not a datepicker? Because humans remember their birthdate as a string of numbers and the day of the week is not relevant.

Entering those numbers is easier than navigating a date picker to find your birthdate.

I posted about this on Bluesky and figured it’s probably useful to have a birthdate input custom element for this that automatically adapts to the user browser locale.

The Base HTML

The birthdate is defined by a set of labelled number inputs.

We’ll wrap these inputs in a fieldset so they’re grouped as a birthdate.

An optional locale attribute can be set on the <birtdate-input> to override the default browser locale.

<fieldset>
    <legend>Birthdate</legend>
    <birthdate-input locale="en-US">
        <label for="day">Day</label>
        <input id="day" min="1" max="31" type="number" placeholder="dd" />

        <label for="month">Month</label>
        <input id="month" min="1" max="12" type="number" placeholder="mm" />

        <label for="year">Year</label>
        <input
            id="year"
            min="1800"
            max="2025"
            type="number"
            placeholder="yyyy"
        />
    </birthdate-input>
</fieldset>

The Birthdate Input Custom Element

Now we need to register the <birthdate-input> custom element.

This custom element automatically orders the fields based on the detected locale.

class BirthdateInput extends HTMLElement {
    constructor() {
        super();
    }

    connectedCallback() {
        const defaultFields = ['day', 'month', 'year'];

        // get inputs
        const [day, month, year] = Array.from(
            this.querySelectorAll('input[type="number"]')
        );
        this.inputs = [day, month, year];
        this.inputRefs = { day, month, year };

        // add field keys
        for (const [index, input] of Object.entries(this.inputs)) {
            input.dataset.key = defaultFields[index];
        }

        // order parts based on the browser default locale
        const dateTimeFormat = new Intl.DateTimeFormat(
            this.getAttribute('locale') || undefined
        );
        const parts = dateTimeFormat.formatToParts();
        const order = parts
            .filter((part) => defaultFields.includes(part.type))
            .map((part) => part.type);

        // sort fields
        for (const key of order) {
            const input = this.inputRefs[key];

            // append the label
            this.append(this.querySelector(`label[for=${input.id}]`));

            // then append the input
            this.append(input);
        }

        // just focussed other field, prevent tabbing out of it by accident
        let preventTab = false;
        this.addEventListener('keydown', (e) => {
            if (e.key === 'Tab' && preventTab) {
                e.preventDefault();
                return;
            }
        });

        // auto jump to next field when user inputs numbers
        this.addEventListener('keyup', (e) => {
            // easier prop access
            const input = e.target;
            const { value, placeholder, dataset } = input;
            const currentIndex = order.indexOf(dataset.key);

            // move to previous field
            if (e.key === 'Backspace' && value.length === 0) {
                const previousField = this.inputRefs[order[currentIndex - 1]];
                if (!previousField) return;
                previousField.focus();
            }

            // not a number, ignore
            if (!/[0-9]/.test(e.key)) return;

            // not filled out completely
            if (value.length !== placeholder.length) return;

            // get next field
            const nextField = this.inputRefs[order[currentIndex + 1]];
            if (!nextField) return;

            // focus this field
            preventTab = true;
            setTimeout(() => (preventTab = false), 250);
            nextField.focus();
        });
    }

    disconnectedCallback() {
        // restore original order
        for (const input of this.inputs) {
            this.append(input);
        }
    }
}

customElements.define('birthdate-input', BirthdateInput);

Demo field

This is a live demo of the <birthdate-input> component. The order of the fields is determined by your browser default locale.

Birthdate

Day Month Year

Animating And Transitioning CSS Custom Properties

2024-07-29T00:00:00Z

This code animates a CSS property, and transitions a custom CSS property. The transition property is used in the animation. This combination works on Chrome, but unfortunately fails on Firefox and Safari.

See animation below, followed by the code snippet.

The Bar element should pulse, but at the start of the animation pulses should start at low opacity (similar to Foo) and slowly fade in, which is what happens on Chrome.

On Firefox and Safari the Foo element will fade in but the Bar element will pulse in the same manner no matter the transition state.

Foo

Bar

<style>
    @property --o {
        syntax: '<number>';
        inherits: false;
        initial-value: 0;
    }

    /* Test element so we can see that the custom property transition works */
    #foo {
        --o: 0;
        transition: --o 6s linear;
        background-color: rgba(0, 0, 0, var(--o));
    }

    #foo.in {
        --o: 1;
    }

    /* Element with transition and animation */
    #bar {
        --o: 0;
        transition: --o 6s linear;
    }

    #bar.in {
        --o: 1;
        animation: pulse 0.5s linear alternate infinite;
    }

    @keyframes pulse {
        from {
            background-color: rgba(0, 0, 0, 0);
        }

        to {
            background-color: rgba(0, 0, 0, var(--o));
        }
    }
</style>

<p id="foo">Foo</p>

<p id="bar">Bar</p>

<script>
    setTimeout(() => {
        foo.classList.add('in');
        bar.classList.add('in');
    }, 1000);
</script>

Creating CSS Spring Animations With The Linear Easing Function

2024-07-03T00:00:00Z

While developing FilePond I wanted to run a CSS powered spring animation, but the CSS API didn’t support it natively. So I built this tiny tool to generate linear easing functions that simulate spring animations in CSS.

The app below uses a Svelte spring to animate a transition from 0 to 1, it then records the spring steps and converts them to a linear() CSS transition. As a bonus it also creates a CSS animation. The generated CSS code is available for copy pasting below the app.

Fine-tune the spring animation using the Stiffness and Damping controls.

The code blocks below will receive the resulting CSS transition and animation.

Waiting for data...

Waiting for data...

Using Web Bluetooth To Read BBQ Temperature Sensor Data

2024-03-05T12:00:00Z

In this short read we’ll explore the Web Bluetooth API. We’ll connect with my Bluetooth BBQ thermometer. Then we’ll try to read out its data and listen to its temperature updates. At the end of the article you’ll have a good idea about what you can do with the Web Bluetooth API.

A couple months ago we purchased the Hermanos Grill 5.0 Bluetooth BBQ thermometer. It supports up to 6 temperature sensors, in this article I’ll connect 2. It also supports Bluetooth so you can connect your phone and see BBQ temperatures without having to get out of your chair.

Ahhhh, we’re truly living in the future aren’t we!

Connecting To The Device

At this time the Web Bluetooth API is only supported by Chrome. Unfortunately there’s no signal from other vendors that they’re working on adding support.

So much for living in the future. 🤷‍♂️

The first thing we need to do is connect to the Hermanos device over Bluetooth, we can do that by calling navigator.bluetooth.requestDevice()

We can pass filter parameters to have the browser only show the devices we’re interested it (we should do this in production), but for now we set acceptAllDevices to true so we can see every device around us.

const device = await navigator.bluetooth.requestDevice({
    // Show us all the things!
    acceptAllDevices: true,
});

The Web Bluetooth API requires a user interaction as trigger to connect, for security reasons you can’t just connect to a device on page load.

The user needs to click something that initiates the connection request.

Let’s add a connect button.

<button type="button" onclick="connect()">Connect</button>

<script>
    async function connect() {
        const device = await navigator.bluetooth.requestDevice({
            acceptAllDevices: true,
        });
    }
</script>

Pretty straightforward.

Click our “Connect” button and Chrome opens a panel to select a Bluetooth device.

With the device connection set up, let’s move on to the next steps:

Connecting to the GATT server on the remote device.
And then requesting the primary service.

I had to look up the GATT acronym because I just can’t pass on an opportunity to use the <abbr> tag.

GATT is an acronym for “Generic ATTribute Profile”.

It sets the terms for communication between two Bluetooth devices. So now you know.

Connecting To The Bluetooth GATT Server

There’s nothing more to it than calling device.gatt.connect()

async function connect() {
    const device = await navigator.bluetooth.requestDevice({
        acceptAllDevices: true,
    });

    // Connect to the GATT server
    const server = await device.gatt.connect();
}

Now that we have a reference to the GATT server, we can request the primary service.

At this point, I struggled a tiny bit.

To get the primary service we call server.getPrimaryService()

async function connect() {
    const device = await navigator.bluetooth.requestDevice({
        acceptAllDevices: true,
    });

    const server = await device.gatt.connect();

    // We fetch the primary service
    const service = await server.getPrimaryService();
}

This function however expects a Universally Unique Identifier.

It should be called like this getPrimaryService(uuid)

I had no idea where to get this UUID (another <abbr> 🥳), as I don’t have any documentation on this device I’m trying to connect to.

After some looking around I stumbled uppon a handy Chrome utility. You can navigate to chrome://bluetooth-internals, connect to a device, and inspect it.

Chrome queries the device and displays an overview of the available internals:

I just love how hardcore that interface is. Zero design. Those blue bar are clickable, it’s an accordion. The inspect button doesn’t always work, or inspects the incorrect device. Let’s say it’s probably a work in progress.

But while it doesn’t look great, it’s functional. We can see the service with Type set to Primary, and it displays that UUID we’ve been looking for.

We need to pass the UUID as a parameter to getPrimaryService, and we need to inform the device we’re going to do that by adding it to the optionalServices array when we call requestDevice

// 1. Store the UUID in a constant so we can use it more easily
const PRIMARY_SERVICE_UUID = '0000ffb0-0000-1000-8000-00805f9b34fb';

async function connect() {
    const device = await navigator.bluetooth.requestDevice({
        acceptAllDevices: true,

        // 2. Tell the device which services we want to use
        optionalServices: [PRIMARY_SERVICE_UUID],
    });

    const server = await device.gatt.connect();

    // 3. Fetch the primary service by UUID
    const service = await server.getPrimaryService(PRIMARY_SERVICE_UUID);
}

Just like that the service variable contains a reference to the primary BluetoothRemoteGATTService

This GATT service has characteristics, we can see this in the Chrome Bluetooth Internals accordion.

Let’s subscribe to the temperature characteristic for notifications!

Subscribing To Bluetooth Characteristic Notifications

This specific BBQ temperature thingy has a notification characteristic, meaning it sends out temperature information (and probably some other stuff), and we can subscribe to those notifications.

We know this because we can see it in the Chrome Bluetooth Internals accordion. It shows this nice green checkmark next to the Notify property.

Let’s get access to the notification characteristic by calling getCharacteristic() and passing the characteristic UUID.

const PRIMARY_SERVICE_UUID = '0000ffb0-0000-1000-8000-00805f9b34fb';

// 1. Add another constant
const NOTIFICATION_CHARACTERISTIC_UUID = '0000ffb2-0000-1000-8000-00805f9b34fb';

async function connect() {
    const device = await navigator.bluetooth.requestDevice({
        acceptAllDevices: true,
        optionalServices: [PRIMARY_SERVICE_UUID],
    });

    const server = await device.gatt.connect();

    const service = await server.getPrimaryService(PRIMARY_SERVICE_UUID);

    // 2. Get the notification characteristic from the primary service
    const characteristic = await primaryService.getCharacteristic(
        NOTIFICATION_CHARACTERISTIC_UUID
    );
}

Now that we have our Characteristic we can listen for its 'characteristicvaluechanged' event.

const PRIMARY_SERVICE_UUID = '0000ffb0-0000-1000-8000-00805f9b34fb';

const NOTIFICATION_CHARACTERISTIC_UUID = '0000ffb2-0000-1000-8000-00805f9b34fb';

async function connect() {
    const device = await navigator.bluetooth.requestDevice({
        acceptAllDevices: true,
        optionalServices: [PRIMARY_SERVICE_UUID],
    });

    const server = await device.gatt.connect();

    const service = await server.getPrimaryService(PRIMARY_SERVICE_UUID);

    const characteristic = await primaryService.getCharacteristic(
        NOTIFICATION_CHARACTERISTIC_UUID
    );

    // Listen to the change event
    characteristic.addEventListener('characteristicvaluechanged', (e) => {
        // I'm called when the value changes
    });
}

To get this show on the road we need to tell our characteristic to start notifying, this we can do with the startNotifications method.

const PRIMARY_SERVICE_UUID = '0000ffb0-0000-1000-8000-00805f9b34fb';

const NOTIFICATION_CHARACTERISTIC_UUID = '0000ffb2-0000-1000-8000-00805f9b34fb';

async function connect() {
    const device = await navigator.bluetooth.requestDevice({
        acceptAllDevices: true,
        optionalServices: [PRIMARY_SERVICE_UUID],
    });

    const server = await device.gatt.connect();

    const service = await server.getPrimaryService(PRIMARY_SERVICE_UUID);

    const characteristic = await primaryService.getCharacteristic(
        NOTIFICATION_CHARACTERISTIC_UUID
    );

    // Tell it to start sending update notifications
    await characteristic.startNotifications();

    // Then we listen for changes
    characteristic.addEventListener('characteristicvaluechanged', (e) => {
        // I'm called when my value changes
    });
}

The cached value of the notification characteristic is stored as a DataView in the characteristic.value property.

For clarity we’ll detach the event handler function and log the value.

const PRIMARY_SERVICE_UUID = '0000ffb0-0000-1000-8000-00805f9b34fb';

const NOTIFICATION_CHARACTERISTIC_UUID = '0000ffb2-0000-1000-8000-00805f9b34fb';

async function connect() {
    const device = await navigator.bluetooth.requestDevice({
        acceptAllDevices: true,
        optionalServices: [PRIMARY_SERVICE_UUID],
    });

    const server = await device.gatt.connect();

    const service = await server.getPrimaryService(PRIMARY_SERVICE_UUID);

    const characteristic = await primaryService.getCharacteristic(
        NOTIFICATION_CHARACTERISTIC_UUID
    );

    await characteristic.startNotifications();

    // Handles the 'characteristicvaluechanged' event
    const handleValueChanged = (e) => {
        // Updated value
        console.log(characteristic.value);
    };

    // Move the event handler to a separate function
    characteristic.addEventListener(
        'characteristicvaluechanged',
        handleValueChanged
    );
}

In our developer console we can see the following log.

We have some data to work with! Let’s try to read the sensor temperatures from it.

Getting Data From The BlueTooth Characteristic DataView

A DataView. What is this, and how do we get the temperature information from it? 🤔

The DataView contains the binary data returned by the notification characteristic. If you have a manual telling you which data is where, that’s useful, but I didn’t have one.

With some experimentation and perseverance we can figure this out.

In the developer console we can expand DataView, then buffer, then [[Int8Array]]

To figure out which data correlated to which sensor I detached all sensors and then plugged in each one while watching for changes.

When I attached sensor 1, the values of index 2 changed from -1 to 1, and 3 changed from -1 to an integer.
The same happened for sensor 2, but it updated indexes 4 and 5

So looks like that’s where the device stores the sensor data. Our next step is to convert these values to temperatures.

This took me over an hour to figure out. For some reason I decided to click the little computer chip next to DataView and Chrome opened the Memory inspector.

Honestly. This caught me off guard. I’ve logged DataView instances before but can’t remember seeing this icon, perhaps it’s new?

Anyway, here’s the panel in all its glory:

This is super useful.

We can click through the memory locations and see what value each location contains. The 3F location in the top right converts to 319 and that correlates quite nicely with the 32 ℃ the device display shows for sensor 1.

319 / 10 = 31,9

Plausible. Let’s read those bytes.

const handleValueChanged = (e) => {
    // We get the value at index 2 as `Uint16`
    const sensorOneTemp = characteristic.value.getUint16(2) / 10;

    // We get the value at index 4 as `Uint16`
    const sensorTwoTemp = characteristic.value.getUint16(4) / 10;

    // Log the information to the dev console
    console.clear();
    console.log('characteristicvaluechanged');
    console.log('#1', sensorOneTemp);
    console.log('#2', sensorTwoTemp);
};

And presto, we can see the result below. The temperature for sensor 2 increases when I hold it between my fingers.

You can inspect the final code snippet below.

<button type="button" onclick="connect()">Connect</button>

<script>
    const PRIMARY_SERVICE_UUID = '0000ffb0-0000-1000-8000-00805f9b34fb';

    const NOTIFICATION_CHARACTERISTIC_UUID =
        '0000ffb2-0000-1000-8000-00805f9b34fb';

    async function connect() {
        const device = await navigator.bluetooth.requestDevice({
            acceptAllDevices: true,
            optionalServices: [PRIMARY_SERVICE_UUID],
        });

        const server = await device.gatt.connect();

        const service = await server.getPrimaryService(PRIMARY_SERVICE_UUID);

        const characteristic = await primaryService.getCharacteristic(
            NOTIFICATION_CHARACTERISTIC_UUID
        );

        await characteristic.startNotifications();

        const handleValueChanged = (e) => {
            const sensorOneTemp = characteristic.value.getUint16(2) / 10;
            const sensorTwoTemp = characteristic.value.getUint16(4) / 10;

            console.clear();
            console.log('characteristicvaluechanged');
            console.log('#1', sensorOneTemp);
            console.log('#2', sensorTwoTemp);
        };

        characteristic.addEventListener(
            'characteristicvaluechanged',
            handleValueChanged
        );
    }
</script>

This is a real Connect button, it’s linked up to the finished script.

If you own the same sensor, in theory, you should be able to connect to it on this page.

Conclusion

It’s crazy to me how powerful web browsers have become, we linked up a Bluetooth device in under 10 lines of code. 🤯

If you followed along you should have a good idea now about how you could use the Bluetooth Web API, there’s plenty of other and probably more useful use cases out there. Let me know what you decided to connect to!

Let’s keeps our fingers crossed that Apple and Mozzila add support for the Web Bluetooth API soon so we can start creating truly cross platform web apps.

What's the JavaScript version of sleep

2023-10-17T00:00:00Z

There’s no sleep function in JavaScript, how can we make one?

Let’s jump right in and write the function.

function sleep(milliseconds) {
    return new Promise((resolve) => setTimeout(resolve, milliseconds));
}

It’s a basic function that when called returns a Promise that’s resolved after the given number of milliseconds.

How do we use this function?

// sleep for 1 second
sleep(1000).then(() => {
    // do this after 1 second
});
// do this first

Please note that any code placed after sleep will run before the code inside the then function.

We can also use async/await

// sleep for 1 second
await sleep(1000);

// do this after 1 second

That’s it. A super quick way to create a sleep function in JavaScript.

Useful for when we, for example, want to sleep an authentication process a random number of milliseconds to obfuscate if our server is busy or not.

Flexible CSS Colors With Custom Properties

2023-08-10T00:00:00Z

Let’s use CSS Custom Properties and calc() to create various CSS color effects, fasten your seatbelt, we’re going from 0 to 100 in 1.5 seconds.

No time to waste, let’s go!

Setting Up A Basic Color Scheme

First we create a basic black text on white background style for our page.

Note that in the :root selector we don’t use functional notations for our colors, we only set the numbers.

<html>
    <p>Our very plain page</p>
</html>

:root {
    --foreground: 0, 0, 0; /* black */
    --background: 255, 255, 255; /* white */
}

html {
    color: rgb(var(--foreground));
    background: rgb(var(--background));
}

Our very plain page

A very plain page indeed, let’s add some different tints of grey.

Creating Different Color Tints

Let’s add a paragraph with a grey background. We can do this by creating an rgba color and lowering its alpha value.

<html>
    <p>Our very plain page</p>
    <p class="panel">A panel with a grey background</p>
</html>

.panel {
    background: rgba(var(--foreground), 0.25);
}

Our very plain page

A panel with a grey background

By adjusting the alpha value we can create various tints of grey.

<html>
    <p>Our very plain page</p>
    <p class="panel">A panel with a grey background</p>
    <p class="panel-dark">A panel with a dark grey background</p>
</html>

.panel-dark {
    background: rgba(var(--foreground), 0.5);
}

Our very plain page

A panel with a grey background

A panel with a dark grey background

A useful trick, but in situations where our panels overlap it will quickly become apparent that their backgrounds aren’t opaque.

Let’s move the bottom panel so it overlaps with the top one.

.panel-dark {
    margin-top: -1em;
}

Our very plain page

A panel with a grey background

A panel with a dark grey background

We can see the dark color where the top panel shows behind the bottom panel.

To fix this we set can the background-color of the bottom panel to an opaque color and then overlay a linear-gradient on top of that. We can reduce code duplication by assigning the gradient color to a separate custom property.

.panel-dark {
    --overlay: rgba(var(--foreground), 0.5);
    background-image: linear-gradient(var(--overlay), var(--overlay));
    background-color: rgb(var(--background));
}

Our very plain page

A panel with a grey background

A panel with a dark grey background

Now our darker panel is opaque.

You’d imagine it would be possible to use multiple background colors, but while the background property supports setting multiple background images it’s not possible to stack background colors.

Adding A Dark Theme

Next up is adding a dark theme using the prefers-color-scheme: dark media feature.

We only have to swap the --foreground and --background values, and we’re set.

:root {
    --foreground: 0, 0, 0;
    --background: 255, 255, 255;
}

@media (prefers-color-scheme: dark) {
    :root {
        --foreground: 255, 255, 255;
        --background: 0, 0, 0;
    }
}

Let’s view the light and dark themes side by side.

Our very light page

A grey panel

A dark grey panel

Our very dark page

A grey panel

A dark grey panel

Great, our theme is working!

Let’s step it up a notch by adding some more exiting styles.

Using CSS Custom Properties As Style Modifiers

We’re going to replace the text on our page with a button that we’ll try to make look good in both the bright and the dark theme.

<html>
    <button type="button">Our button</button>
</html>

button {
    color: rgb(var(--background));
    background: rgb(var(--foreground));
    border: 0;
}

Our button is looking “good” and it’s automatically styled in dark mode as well.

Let’s now add some more details to our button.

We’ll try to make it look more realistic by simulating light shining from the top. This creates a shadow below the button and a highlight on top. To make this more apparent we will dim the page background color.

html {
    /* Dim page background color */
    --overlay: rgba(var(--foreground), 0.2);
    background-image: linear-gradient(var(--overlay), var(--overlay));
    background-color: rgb(var(--background));

    /* Same text color as before */
    color: rgb(var(--foreground));
}

button {
    /* Nicely rounded corners */
    border-radius: 0.5rem;

    /* Slightly dimmed color for text */
    color: rgba(var(--background), 0.85);

    /* An inset shadow above the text */
    text-shadow: 0 -1px 0 rgba(var(--foreground), 0.9);

    /* A subtle gradient as background */
    background: linear-gradient(
        rgba(var(--foreground), 0.6),
        rgba(var(--foreground), 0.75)
    );

    /* A shadow and inset, define all the values used in the box-shadow, and then stack them */
    --shadow-behind: 0 0.125rem 0.5rem rgba(0, 0, 0, 0.4);
    --shadow-below: 0 0.125rem 0.25rem rgba(0, 0, 0, 0.2), 0 0.06125rem 0.125rem
            rgba(0, 0, 0, 0.2);
    --highlight-outline: 0 0 0 1px rgba(0, 0, 0, 0.5);
    --highlight-inset: inset 0 0 0 1px rgba(255, 255, 255, 0.1);
    --highlight-top: inset 0 1px 0 0 rgba(255, 255, 255, 0.3);
    --highlight-bottom: inset 0 -1px 0 rgba(0, 0, 0, 0.4);

    box-shadow: var(--highlight-outline), var(--highlight-top), var(
            --highlight-bottom
        ), var(--highlight-inset), var(--shadow-below), var(--shadow-behind);
}

Let’s take a look at the results.

The button looks excellent on the bright page, but on the dark page something it’s not great.

The gradient is inverted, going from dark to light.
The outline is too bright.
The white text-shadow is very bright and should be below the text.
The button is too bright overall which causes loss of detail.

These problems are partly caused by blatantly inverting the colors, but it’s also related to our eyes being more sensitive details when it’s light.

Let’s introduce 2 new CSS Custom Properties and update the button styles to fix gradient directions and improve contrast so details are better visible in dark mode.

:root {
    --foreground: 0, 0, 0;
    --background: 255, 255, 255;

    /* By default this is set to 1 so it doesn't cause inversions */
    --mod-invert: 1;
}

@media (prefers-color-scheme: dark) {
    :root {
        --foreground: 255, 255, 255;
        --background: 0, 0, 0;

        /* We set this one to -1 so we can use it to invert values */
        --mod-invert: -1;

        /* Set to 2 so we can use this to multiple values to increase contrast */
        --mod-contrast: 2;
    }
}

button {
    /* Nicely rounded corners */
    border-radius: 0.5rem;

    /* Slightly dimmed color for text */
    color: rgba(var(--background), 0.85);

    /* 
    An inset shadow above the text 
    - Flip the text shadow direction 
    - Lower shadow opacity
    */
    --text-shadow-y: calc(-1px * var(--mod-invert));
    --text-shadow-alpha: calc(0.9 * (var(--mod-contrast, 4) * 0.25));
    text-shadow: 0 var(--text-shadow-y) 0 rgba(
            var(--foreground),
            var(--text-shadow-alpha)
        );

    /* 
    A subtle gradient as background
    - Flip the gradient direction in dark mode 
    - Lower opacity in dark mode
    */
    --linear-gradient-direction: calc(90deg + (var(--mod-invert) * 90deg));
    --linear-gradient-factor: calc(var(--mod-contrast, 2.5) * 0.4);
    background: linear-gradient(
        var(--linear-gradient-direction),
        rgba(var(--foreground), calc(0.6 * var(--linear-gradient-factor))),
        rgba(var(--foreground), calc(0.75 * var(--linear-gradient-factor)))
    );

    /* 
    A shadow and inset, define all the values used in the box-shadow, and then stack them
    - Calculate factor to use for the button outline intensity
    */
    --shadow-behind: 0 0.125rem 0.5rem rgba(0, 0, 0, 0.4);
    --shadow-below: 0 0.125rem 0.25rem rgba(0, 0, 0, 0.2), 0 0.06125rem 0.125rem
            rgba(0, 0, 0, 0.2);
    --highlight-outline-alpha-factor: calc(var(--mod-contrast, 2.85) * 0.35);
    --highlight-outline: 0 0 0 1px rgba(var(--foreground), calc(0.5 * var(--highlight-outline-alpha-factor)));
    --highlight-inset: inset 0 0 0 1px rgba(255, 255, 255, calc(0.1 * var(--mod-contrast, 1)));
    --highlight-top: inset 0 1px 0 0 rgba(255, 255, 255, calc(0.3 * var(--mod-contrast, 1)));
    --highlight-bottom: inset 0 -1px 0 rgba(0, 0, 0, calc(0.4 / var(--mod-contrast, 1)));
    box-shadow: var(--highlight-outline), var(--highlight-top), var(
            --highlight-bottom
        ), var(--highlight-inset), var(--shadow-below), var(--shadow-behind);
}

Let’s compare the old and the new dark button, the light version has stayed the same.

Excellent, now let’s look at the light and dark pages next to each other.

Quite the improvement!

Admittedly this all escalated a bit fast in this last section, but I hope you learned a couple new tricks and this gives you some ideas on how to apply them to your code, see you in the next one!

Create Crisp Image Borders With CSS Pseudo Elements

2023-03-16T00:00:00Z

Transparent image borders can have contrast issues and look dull, let’s make them nice and crisp with this tiny CSS trick.

The demo below shows a default half transparent image border.

Boring border

We can see that we lose contrast depending on the colors of the image near the border.

The border looks nice when it’s near a contrasting area, but it kind of dissapears when near colors of the same brightness.

In the example below we overlay the border on top of the image, this creates a very nice sharp edge.

Fancy colorful border

The side-by-side comparison below makes it more clear.

Boring border

Fancy colorful border

For this CSS trick we use an inset box-shadow instead of a border, while an image can have an inset box-shadow it won’t show as that’s where its pixels are rendered.

So to do this we’ll have to overlay another element on top. Let’s set up the HTML.

<div class="fancy-border">
    <img src="cat.jpeg" alt="" />
</div>

We’ll scale the .fancy-border element to be as wide as the image.

Next we create a Pseudo Element with an inset box-shadow and overlay it on top of the image.

Finally we set pointer-events to none to hide the Pseudo Element element from user interactions.

.fancy-border {
    position: relative;
    width: fit-content;
    border-radius: 1rem;
}

.fancy-border img,
.fancy-border::after {
    border-radius: inherit;
}

.fancy-border img {
    display: block;
}

.fancy-border::after {
    content: '';
    position: absolute;
    left: 0;
    top: 0;
    width: 100%;
    height: 100%;
    box-shadow: inset 0 0 0 1px rgba(0, 0, 0, 0.25);
    pointer-events: none;
}

Edit Images With Vue And Pintura

2023-02-13T00:00:00Z

In this quick tutorial we’ll build a Vue image editor using Pintura a powerful JavaScript image and video editor SDK.

We could build a complete image editor ourselves but that would literally take months, it would turn this quick tutorial into a not-so-quick tutorial.

To get started we’ll set up a basic Vue Composition API based template and then add Pintura.

<script setup>
    // Coming up next...
</script>

<template>
    <!-- File selection -->
    <input type="file" />

    <!-- Editor output -->
    <img src="" alt="" />
</template>

While this tutorial is based on the Vue 3 Composition API, Pintura works just as well with Vue 2 or the Vue 3 template API.

Receiving User Selected Files

Let’s first write the logic get the selected image file from the file input.

We’ll need to get the files, select the first file, and then make sure it’s an image.

<script setup>
    function handleFile(e) {
        // Get files from the file input
        const { files } = e.target;

        // Only need the first file
        const [file] = files;

        // We're only interested in images, also, if no file selected we can't continue
        if (!file || !/image/.test(file.type)) return;

        // We're ready to edit an image...
    }
</script>

<template>
    <input type="file" @change="handleFile" />

    <img src="" alt="" />
</template>

Editing Images With Vue

Now that we’re sure we’ve selected an image file we can add Pintura and edit the image.

We’ll import the openDefaultEditor factory, this creates and opens a feature complete image editor instance in a modal.

<script setup>
    // Import the default Pintura modal editor
    import { openDefaultEditor } from '@pqina/pintura';

    function handleFile(e) {
        const { files } = e.target;

        const [file] = files;

        if (!file || !/image/.test(file.type)) return;

        // Open Pintura in a modal
        const editor = openDefaultEditor({
            src: file,
        });

        // Fires when we're done editing the image
        editor.on('process', ({ dest }) => {
            // Next up is showing the resulting image...
        });
    }
</script>

<template>
    <input type="file" @change="handleFile" />

    <img src="" alt="" />
</template>

Showing The Output Image

When we’re done editing an image the resulting image is returned in the callback assigned to the 'process' event. The dest property contains the output image file.

By defining a reactive property we can set the src attribute of the image by updating the src property of the outputImage object.

<script setup>
    import { openDefaultEditor } from '@pqina/pintura';

    // The Vue reactive property helper
    import { reactive } from 'vue';

    // The source of the image we want to display
    const outputImage = reactive({ src: '' });

    function handleFile(e) {
        const { files } = e.target;

        const [file] = files;

        if (!file || !/image/.test(file.type)) return;

        const editor = openDefaultEditor({
            src: file,
        });

        editor.on('process', ({ dest }) => {
            // Show the resulting image file
            outputImage.src = URL.createObjectURL(dest);
        });
    }
</script>

<template>
    <input type="file" @change="handleFile" />

    <img :src="outputImage.src" alt="" />
</template>

Uploading The Resulting Image

We can use Pintura to upload the edited image as well. We set the store property on the imageWriter, this tells Pintura to POST the resulting image to the specified URL. Pintura will show a progress indicator while it’s busy uploading.

<script setup>
    import { openDefaultEditor } from '@pqina/pintura';

    import { reactive } from 'vue';

    const outputImage = reactive({ src: '' });

    function handleFile(e) {
        const { files } = e.target;

        const [file] = files;

        if (!/image/.test(file.type)) return;

        const editor = openDefaultEditor({
            src: file,

            // Here we pass the `store` property to the `imageWriter`, it'll
            // POST our image as FormData to the defined end point at `/upload/`
            imageWriter: {
                store: '/upload/',
            },
        });

        editor.on('process', ({ dest }) => {
            outputImage.src = URL.createObjectURL(dest);
        });
    }
</script>

<template>
    <input type="file" @change="handleFile" />

    <img :src="outputImage.src" alt="" />
</template>

Conditionally Loading Pintura

Pintura weighs in at about half the size of a 5¼ inch floppy (about 200KB gzipped), while super small for an image editor, that’s still quite a lot of data for slower connections.

To improve page performance we can use tree-shaking and only import the internal Pintura modules we need, but on top of that we can wait with loading Pintura until the user selects an image to edit. It’s at that time we need the editor image editing.

Let’s make this tiny change now, we’ll use a dynamic import to load the module.

<script setup>
    import { reactive } from 'vue';

    const outputImage = reactive({ src: '' });

    async function handleFile(e) {
        const { files } = e.target;

        const [file] = files;

        if (!file || !/image/.test(file.type)) return;

        // Dynamically load Pintura when the user has selected a valid image file
        const { openDefaultEditor } = await import('@pqina/pintura');

        const editor = openDefaultEditor({
            src: file,
            imageWriter: {
                store: '/upload/',
            },
        });

        editor.on('process', ({ dest }) => {
            outputImage.src = URL.createObjectURL(dest);
        });
    }
</script>

<template>
    <input type="file" @change="handleFile" />

    <img :src="outputImage.src" alt="" />
</template>

Conclusion

With only a couple lines of code we’ve added a fully featured image editing solution to our project and we didn’t even use the Vue Pintura Components. While integrating Pintura we’ve learned about reactive Vue objects and dynamic loading of JavaScript modules.

We’ve got everything we need to add image editing functionality to a Vue project, making it possible to crop profile pictures, build photo collages, annotate images, and much more.

Compress An Image Before Upload With JavaScript

2023-01-01T00:00:00Z

In this quick tutorial we’ll use JavaScript to compress images selected with a file input element. We’ll compress images and save them back to the file input ready for upload.

To make sure users can upload their images and prevent super big images from being uploaded we can compress image data before upload without bothering the user with all kinds of requirements.

If you’re in a hurry, or find it easier to read the code itself, you can jump to the final code snippet here

Getting The Selected Image Files

In the example below we’ll accept all kinds of files but will only compress the images. The multiple attribute enables selection of more than one file.

To prevent other files from being added we can optionally set the file input accept attribute to "image/*"

Let’s set up a file input field, we’ll listen for the "change" to detect when the user has selected one or more files. We’ll handle the TODO items in the next section.

<input type="file" multiple class="my-image-field" />

<script>
    // Get the selected files from the file input
    const input = document.querySelector('.my-image-field');
    input.addEventListener('change', (e) => {
        // Get the files
        const { files } = e.target;

        // No files selected
        if (!files.length) return;

        // For every file in the files list
        for (const file of files) {
            // We don't have to compress files that aren't images
            if (!file.type.startsWith('image')) {
                // TODO: Not an image
            }

            // TODO: Compress the image
        }

        // TODO: Store the files
    });
</script>

Our code now runs when a user selects one or more image files. Next up is compressing the images.

Since we’ve got some todo’s to take care of… I’ve been building a macOS daily Todo tracking app called Hotlist (a fun side project to learn app development), who knows, maybe it’s just what you’ve been looking for.

Anyhow… Let’s get back to image compression!

Compressing The Images

We’ll implement the compressImage function. This function will convert the passed File object to an ImageBitmap, draw it to a <canvas> element, and then the canvas returns a compressed JPEG using the toBlob API.

Please note that we could also ask for a WEBP but that this (at the time of this writing) isn’t support on Safari 🤷‍♂️

Let’s get to it.

<input type="file" multiple class="my-image-field" />

<script>
    const compressImage = async (file, { quality = 1, type = file.type }) => {
        // Get as image data
        const imageBitmap = await createImageBitmap(file);

        // Draw to canvas
        const canvas = document.createElement('canvas');
        canvas.width = imageBitmap.width;
        canvas.height = imageBitmap.height;
        const ctx = canvas.getContext('2d');
        ctx.drawImage(imageBitmap, 0, 0);

        // Turn into Blob
        return await new Promise((resolve) =>
            canvas.toBlob(resolve, type, quality)
        );
    };

    // Get the selected file from the file input
    const input = document.querySelector('.my-image-field');
    input.addEventListener('change', async (e) => {
        // Get the files
        const { files } = e.target;

        // No files selected
        if (!files.length) return;

        // For every file in the files list
        for (const file of files) {
            // We don't have to compress files that aren't images
            if (!file.type.startsWith('image')) {
                // TODO: Not an image
            }

            // We compress the file by 50%
            const compressedFile = await compressImage(file, {
                // 0: is maximum compression
                // 1: is no compression
                quality: 0.5,

                // We want a JPEG file
                type: 'image/jpeg',
            });
        }

        // TODO: Store the files
    });
</script>

The compressedFile variable will now contain the compressed image file.

Next up is saving the compressed image file (and the ignored files), back to the file input.

Saving The Compressed Image Back To The File Input

We’ll create a DataTransfer object with which we’ll create our new files list. This list we can then later save back to the file input

The DataTransfer object only accepts File objects so we need to turn our Blob into a File, let’s update the compressImage function.

<input type="file" multiple class="my-image-field" />

<script>
    const compressImage = async (file, { quality = 1, type = file.type }) => {
        // Get as image data
        const imageBitmap = await createImageBitmap(file);

        // Draw to canvas
        const canvas = document.createElement('canvas');
        canvas.width = imageBitmap.width;
        canvas.height = imageBitmap.height;
        const ctx = canvas.getContext('2d');
        ctx.drawImage(imageBitmap, 0, 0);

        // Turn into Blob
        const blob = await new Promise((resolve) =>
            canvas.toBlob(resolve, type, quality)
        );

        // Turn Blob into File
        return new File([blob], file.name, {
            type: blob.type,
        });
    };

    // Get the selected file from the file input
    const input = document.querySelector('.my-image-field');
    input.addEventListener('change', async (e) => {
        // Get the files
        const { files } = e.target;

        // No files selected
        if (!files.length) return;

        // We'll store the files in this data transfer object
        const dataTransfer = new DataTransfer();

        // For every file in the files list
        for (const file of files) {
            // We don't have to compress files that aren't images
            if (!file.type.startsWith('image')) {
                // Ignore this file, but do add it to our result
                dataTransfer.items.add(file);
                continue;
            }

            // We compress the file by 50%
            const compressedFile = await compressImage(file, {
                quality: 0.5,
                type: 'image/jpeg',
            });

            // Save back the compressed file instead of the original file
            dataTransfer.items.add(compressedFile);
        }

        // Set value of the file input to our new files list
        e.target.files = dataTransfer.files;
    });
</script>

Select one or more image files in the file input below to test out the code, no worries, nothing is uploaded, everything stays in the browser.

Conclusion

We’ve learned how to use canvas and DataTransfer to set up a tiny unobtrusive script to help us compress images before upload. This script will make it easier for our users to upload images.

Of course there are still a lot of improvements to make, for example we could:

Resize the image to fit a maximum bounding box.
Crop the image to a certain aspect ratio.
Better deal with erroneous input and show fitting error messages.
Make sure we handle Safari memory issues.

If we’re looking for a more robust solution we could use FilePond to handle the file upload, it can do image resizing, compression, and more.

If we need even more control we can use Pintura to enable our users to edit images before upload, Pintura is also a drop-in replacement for our compressImage function.

Creating A Custom Svelte Media Query Store

2022-12-22T00:00:00Z

In this short read we create a custom Svelte store to listen for Media Query changes. Super useful for when we want to react to the user changing the system theme or resizing the browser window.

If you just want to get your hands on the ready made custom store you can jump to the code, else let’s explore how to create this custom store together.

Svelte Custom Stores

Svelte exports a set of default stores, namely readable, writable, and derived.

We’re going to use the writable store and wrap our custom Media Query Listener store around it.

This is what we’re going for.

// Import our custom store
import mediaQueryStore from './mediaQueryStore.js';

// Create a dark mode preference store
const prefersDarkMode = mediaQueryStore('(prefers-color-scheme:dark)');

// This will log `true` when in dark mode, it'll automatically be
// called again when the user changes the system preference
$: console.log($prefersDarkMode);

The $ symbol is Svelte magic.

It means Svelte will automatically subscribe and unsubscribe to the store.

You could rewrite the code snippet above without magic like this.

// Import our custom store
import mediaQueryStore from './mediaQueryStore.js';

// Need to clean up the store when done
import { onDestroy } from 'svelte';

// Create a dark mode preference store
const prefersDarkMode = mediaQueryStore('(prefers-color-scheme:dark)');

// This will log `true` when in dark mode
const unsub = prefersDarkMode.subscribe((value) => {
    console.log(value);
});

// Unsubscribe from store when destroying this component
onDestroy(() => {
    unsub();
});

We’re going to need the writable Svelte store and our store factory only accepts one parameter, the Media Query it should observe, so this is the base for our custom store.

// We need to use the writable Svelte store
import { writable } from 'svelte/store';

/**
 * Svelte Media Query Store
 * @param mediaQueryString { string }
 */
export default (mediaQueryString) => {
    /* Store here */
};

Let’s see how we can listen for Media Query changes first.

Listening For Media Query Changes

We can use the MediaQueryList to listen for Media Query changes.

To start watching we use the matchMedia method.

// Create the MediaQueryList
const mql = window.matchMedia('(prefers-color-scheme:dark)');

// Listen for changes
mql.addEventListener('change', (e) => {
    // e.matches is true when user prefers dark mode
    console.log('Prefers dark mode', e.matches);
});

// mql.matches is true when user prefers dark mode
console.log('Prefers dark mode', mql.matches);

Fairly straightforward.

Let’s now move this logic into a Svelte store so it’s even easier to use.

Using MediaQueryList In A Custom Svelte Store

Let’s create a writable store inside our media query store and set up its default logic.

import { writable } from 'svelte/store';

/**
 * Svelte Media Query Store
 * @param mediaQueryString { string }
 */
export default (mediaQueryString) => {
    // We'll need the subscribe and set methods of the writable store
    const { subscribe, set } = writable(
        // The initial value of the store is undefined
        undefined,

        // This function is called on first subscribe call
        () => {
            // Construct
            // ...

            // This function is called on last unsubscribe call
            return () => {
                // Destroy
                // ...
            };
        }
    );

    // We only expose the subscribe method to the outside world
    return { subscribe };
};

Now let’s add our MediaQueryList logic to the store.

import { writable } from 'svelte/store';

/**
 * Svelte Media Query Store
 * @param mediaQueryString { string }
 */
export default (mediaQueryString) => {
    const { subscribe, set } = writable(undefined, () => {
        // Start observing media query
        let mql = window.matchMedia(mediaQueryString);

        // Set first media query result to the store
        set(mql.matches);

        // Called when media query state changes
        const onchange = () => set(mql.matches);

        // Listen for changes (need to support old `addListener` interface)
        'addEventListener' in mql
            ? mql.addEventListener('change', onchange)
            : mql.addListener(onchange);

        // when no more listeners
        return () => {
            // stop listening (need to support old `removeListener` interface)
            'removeEventListener' in mql
                ? mql.removeEventListener('change', onchange)
                : mql.removeListener(onchange);
        };
    });

    return { subscribe };
};

That’s it, we can now use this store in our Svelte projects like shown below.

import mediaQueryStore from './mediaQueryStore.js';

const prefersDarkMode = mediaQueryStore('(prefers-color-scheme:dark)');

$: console.log($prefersDarkMode);

Set Fill Color of SVG Background-image

2022-11-18T00:00:00Z

A quick guide explaining how to change the color of an SVG when it’s used as a CSS background-image.

If you want you can jump to the code, else we can explore how this works together.

SVG Background Color Fill Demo

We’ll start with a live demo, focus, hover, or click on the circle below and the background color will animate.

I’ll let the cat out of the bag.

This is just a normal button with an SVG used as a CSS mask

Instead of changing the fill color of the SVG we change the background-color of the button. But that shouldn’t spoil the fun as it opens up a world of possibilities but we’ll get to that.

Using An SVG As A CSS Mask

We can see our cool smiley SVG below 😎

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
    <g
        stroke-linecap="round"
        stroke-width="4"
        stroke="rgb(0, 0, 0)"
        fill="none"
    >
        <circle cx="12" cy="12" r="10" />
        <path d="M7 11 H17" />
    </g>
</svg>

What’s amazing about the timeline we live in is that we can pass the SVG to the CSS url() function without base64 encoding it or escaping all kinds of characters.

Prefix the SVG with data:image/svg+xml,
Add some structure by ending a line with \
Just like that a readable SVG has appeared in our CSS.

Allright, let’s first assign the SVG to the background property so we can see it, we’ll turn it into a mask in a couple minutes.

button {
    /* ...Other styles */

    /* Color */
    background-color: Crimson;

    /* Store the SVG in a variable so it's easy to re-use */
    --svg: url('data:image/svg+xml,\
    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">\
        <g stroke-linecap="round" stroke-width="4" stroke="rgb(0, 0, 0)" fill="none">\
            <circle cx="12" cy="12" r="10"/>\
            <path d="M7 11 H17"/>\
        </g>\
    </svg>');

    /* Assign the SVG variable */
    background-image: var(--svg);
}

button:hover,
button:focus {
    background-color: Turquoise;
}

button:active {
    background-color: Gold;
}

We can interact with the live demo below to see the SVG has loaded and the styles are correctly applied.

Now it’s time to remove the background property and assign the --svg variable to the mask property.

The black parts of the SVG will be the visible parts of the element and the transparent parts will become invisible.

button {
    /* ...Other styles */

    /* Chrome, still requires prefix in 2022 */
    -webkit-mask: var(--svg);

    /* Firefox and Safari */
    mask: var(--svg);
}

Tadaa! 🥳

If you have trouble getting the mask to work, a handy trick is to temporarily assign the mask to the background-image property.

This allows us to visually see where the black and transparent parts of your mask are, this becomes especially useful when building more complex masks.

Any Background Goes

Because we’re masking the button we can use any background style or effect we can think of.

The Complete SVG Background-image Style Code Snippet

You can find the copy button on the right hand side of the code snippet, enjoy!

<button type="button">I'm a cool circle button</button>

<style>
    button {
        /* Base styles */
        display: block;
        width: 4rem;
        height: 4rem;
        border: none;
        cursor: pointer;

        /* Hide button caption text */
        overflow: hidden;
        color: transparent;

        /* The fill animation */
        background-color: Crimson;
        transition: background-color 0.2s;

        /* Store the SVG in a variable so it's easy to use */
        --svg: url('data:image/svg+xml,\
        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">\
            <g stroke-linecap="round" stroke-width="4" stroke="rgb(0, 0, 0)" fill="none">\
                <circle cx="12" cy="12" r="10"/>\
                <path d="M7 11 H17"/>\
            </g>\
        </svg>');

        /* Chrome, still requires prefix in 2022 */
        -webkit-mask: var(--svg);

        /* Firefox and Safari */
        mask: var(--svg);
    }

    button:hover,
    button:focus {
        background-color: Turquoise;
    }

    button:active {
        background-color: Gold;
    }
</style>

Conclusion

We learned a nice trick where we used the CSS mask property to change the fill color of a SVG when it’s used as a background-image

On top of that we learned that the mask property is identical to the background property so we can switch them out to make debugging the mask image easier.

Edit Video and Images With React

2022-11-10T00:00:00Z

In this short step by step tutorial we’ll set up Pintura Image Editor with its Video Editor extension to edit images and videos in the browser with React.

We’re going to use Pintura because building a complete video editor from scratch is going to take ages. It let’s us skip over all the drama of dealing with various browser quirks and device differences to the fun part of integrating an image editor.

Let’s set up a basic JSX file and then we’ll add Pintura.

function App() {
    return <div>Hai!</div>;
}

export default App;

I did say basic.

Adding The Pintura Editor Component

Let’s download Pintura and add the React <PinturaEditor> component to the mix.

We’ll also need to load the Pintura stylesheet, and to keep things concise we’ll import getEditorDefaults, a helper function that contains all the default editor settings.

// Import the editor styles
import '@pqina/pintura/pintura.css';

// Import the editor default configuration
import { getEditorDefaults } from '@pqina/pintura';

// Import the editor component from `react-pintura`
import { PinturaEditor } from '@pqina/react-pintura';

// get default properties
const editorConfig = getEditorDefaults();

function App() {
    return (
        <div>
            <PinturaEditor
                {...editorConfig}
                src="./my-image.jpeg"
            ></PinturaEditor>
        </div>
    );
}

export default App;

One final thing we need to do is set a height to the PinturaEditor parent element, by default Pintura will try to fill all the available vertical space.

const divStyle = {
    height: 600,
};

function App() {
    // Assign height style to div
    return (
        <div style={divStyle}>
            <PinturaEditor
                {...editorConfig}
                src="./my-image.jpeg"
            ></PinturaEditor>
        </div>
    );
}

When we now add an image to our project public folder and call it my-image.jpeg it loads in Pintura.

Getting the resulting image

We’ll set the imageCropAspectRatio to 1 so Pintura enforces a square image crop and we get an obviously different output image. If your input image is square already set it to 16/9 which will require a 16:9 crop.

Now to get the resulting image file we add the onProcess callback.

function App() {
    // called when user is done editing the image
    const handleProcessMedia = (res) => {
        console.log(res);
        // logs: { src:…, dest:… , imageState:…, store:… }
    };

    return (
        <div style={divStyle}>
            <PinturaEditor
                {...editorConfig}
                src="./my-image.jpeg"
                imageCropAspectRatio={1}
                onProcess={handleProcessMedia}
            ></PinturaEditor>
        </div>
    );
}

Let’s add an <img> element so we can preview the edited image.

function App() {
    const [editorResult, setEditorResult] = useState(undefined);

    const handleProcessMedia = (res) => {
        // Get a reference to the file object
        const { dest } = res;

        // Set an ObjectURL to the file object
        setEditorResult(URL.createObjectURL(dest));
    };

    return (
        <div style={divStyle}>
            {editorResult && <img src={editorResult} alt="" />}

            <PinturaEditor
                {...editorConfig}
                src="./my-image.jpeg"
                imageCropAspectRatio={1}
                onProcess={handleProcessMedia}
            ></PinturaEditor>
        </div>
    );
}

That’s it!

With image editing implemented it’s finally time to move on to video editing.

Video Editing

To enable video editing we load the Pintura Video extension and import the relevant functionality.

But first we need to decide which video encoder to use.

Choosing a VideoEncoder

The Pintura Video extension ships with a MediaStreamEncoder and an FFmpegEncoder.

Using MediaStreamEncoder

The MediaStreamEncoder uses browser APIs to generate the output video. This results in a very lightweight package.

Unfortunately the MediaStream API is still a bit limited and speeding up the video generation process is not possible. This means the time it takes to generate a video is equal to the total video clip play time. Video clip time means the amount of time remaining after trimming the video in Pintura.

For short videos this is fine, for longer video’s it will take too long to generate a video resulting in a sub par user experience.

Using FFmpegEncoder

When using the FFmpegEncoder we rely on the FFmpeg WASM library. It’s a versatile client-side video encoder. For longer video’s it’s a lot faster than using the MediaStreamEncoder.

The downside of using the FFmpegEncoder is that it needs to download the FFmpeg core package which clocks in at 25MB, depending on the user connection, this can be quite a lot of data to transfer. Consider however that uploading a big video file to the server will also take a while so this might not be a huge problem.

Adjusting the template

Let’s first zoom in on the non-template part of the JSX file.

We need to import the video editor specific functionality and load the video editor plugin styles.

Then we adjust the default configuration so Pintura knows how to handle image input and video input.

import '@pqina/pintura/pintura.css';

// Add video editor styles
import '@pqina/pintura-video/pinturavideo.css';

// Add video editor trim plugin and export logic
import {
    createDefaultVideoWriter,
    createMediaStreamEncoder,
    plugin_trim,
    plugin_trim_locale_en_gb,
} from '@pqina/pintura-video';

// We need to import the default media writer
// this allows us to handle images and videos
import {
    getEditorDefaults,
    setPlugins,
    createDefaultMediaWriter,
    createDefaultImageWriter,
    imageStateToCanvas,
} from '@pqina/pintura';

import { PinturaEditor } from '@pqina/react-pintura';

// Add the video trim plugin to Pintura
setPlugins(plugin_trim);

// Configure the editor to output videos and images
const editorConfig = getEditorDefaults({
    locale: {
        ...plugin_trim_locale_en_gb,
    },
    imageWriter: createDefaultMediaWriter(
        {
            // Images and videos will be resized down to 200 width,
            // aspect ratio is maintained
            targetSize: {
                width: 200,
            },
        },
        [
            // Used for writing output images
            createDefaultImageWriter({
                // Convert all input images to JPEGs
                mimeType: 'image/jpeg',

                // Compress image
                quality: 0.75,
            }),
            // Used for writing output videos
            createDefaultVideoWriter({
                encoder: createMediaStreamEncoder({
                    // Required for drawing video output
                    imageStateToCanvas,

                    // Compress video
                    videoBitrate: 384 * 1024,
                }),
            }),
        ]
    ),
});

The next step is to adjust the template so it loads an MP4 file and can preview a generated video.

function App() {
    const [editorResult, setEditorResult] = useState(undefined);

    const handleProcessMedia = (res) => {
        // Get a reference to the file object
        const { dest } = res;

        // Set an ObjectURL to the file object
        setEditorResult({
            url: URL.createObjectURL(dest),
            type: /video/.test(dest.type) ? 'video' : 'image',
        });
    };

    return (
        <div style={divStyle}>
            {editorResult &&
                (editorResult.type === 'image' ? (
                    <img src={editorResult.url} alt="" />
                ) : (
                    <video src={editorResult.url} />
                ))}

            <PinturaEditor
                {...editorConfig}
                util="trim"
                src="./my-video.mp4"
                imageCropAspectRatio={1}
                onProcess={handleProcessMedia}
            ></PinturaEditor>
        </div>
    );
}

Let’s add a video called my-video.mp4 to the public folder, when we refresh the page Pintura automatically loads the video and shows the trim utility.

That’s all there is to it. Pintura can now be used to edit both images and video’s.

To test the video editor functionality please visit either edit.video or try this demo on the Pintura product page

Upload An Image With Node.js

2022-08-02T00:00:00Z

This short and concise guide shows how to set up image uploading with Node.js and Express.

If you’re in a hurry you can jump to the complete code snippet else let’s set it up step by step together.

Set Up The Server

We’ll start with a basic Express server.

Create a new folder and run npm init to generate a package.json file, then install Express.

npm install express

We’ll create an index.js file in the root of our folder and we’ll copy the Express Hello world example to this file as a starting point.

const express = require('express');
const app = express();
const port = 3000;

app.get('/', (req, res) => {
    res.send('Hello World!');
});

app.listen(port, () => {
    console.log(`Example app listening on port ${port}`);
});

Let’s start the server.

node index.js

Open a browser and navigate to http://localhost:3000, it should show “Hello World!”

Adding A Form

Let’s create a folder called public and add a file called index.html with the following HTML.

<!DOCTYPE html>
<form action="/upload" method="POST" enctype="multipart/form-data">
    <input type="file" name="image" />
    <button type="submit">Upload</button>
</form>

We’ve added the enctype form attribute and set it to "multipart/form-data". This is needed to correctly post the file data contained in the file input field.

Note that we’ve set the name attribute of our file input element to "image", this is the name we’ll use to read the image data on the server.

Our form will POST to the post upload route, which we’ll add soon. First we have to tell our server to serve the index.html page.

const express = require('express');
const app = express();
const port = 3000;

// Add this line to serve our index.html page
app.use(express.static('public'));

app.get('/', (req, res) => {
    res.send('Hello World!');
});

app.listen(port, () => {
    console.log(`Example app listening on port ${port}`);
});

Next up we’ll add the upload route.

app.get('/', (req, res) => {
    res.send('Hello World!');
});

app.post('/upload', (req, res) => {
    // We'll handle the image upload here
});

To handle file uploads we need the express-fileupload middleware, this will read the multipart/form-data and add a files property to the request object.

Let’s install it now.

npm install express-fileupload

Now we’ll update the index.js file to use express-fileupload

const express = require('express');
const fileUpload = require('express-fileupload');
const app = express();
const port = 3000;

// Use the express-fileupload middleware
app.use(fileUpload());

app.use(express.static('public'));

app.get('/', (req, res) => {
    res.send('Hello World!');
});

app.post('/upload', (req, res) => {
    // Log the files to the console
    console.log(req.files);

    // All good
    res.sendStatus(200);
});

app.listen(port, () => {
    console.log(`Example app listening on port ${port}`);
});

Restart the server. When we refresh the page it now shows our form. When we upload a file, it logs the file to the server console.

It’ll look something like this

[Object: null prototype] {
  image: {
    name: 'test.jpeg',
    data: <Buffer ff d8 ff e0 00 10 4a 46 49 46 00 01 01 01 00 48 00 48 00 00 ff e2 0c 58 49 43 43 5f 50 52 4f 46 49 4c 45 00 01 01 00 00 0c 48 4c 69 6e 6f 02 10 00 00 ... 1234567 more bytes>,
    size: 234732,
    encoding: '7bit',
    tempFilePath: '',
    truncated: false,
    mimetype: 'image/jpeg',
    md5: 'c76564e19a5e8cd647a2d60478ad94b3',
    mv: [Function: mv]
  }
}

The final step is to move the file to an upload folder.

First let’s create a folder called upload in our project directory.

Then we’ll adjust the app.post route to look like this.

app.post('/upload', (req, res) => {
    // Get the file that was set to our field named "image"
    const { image } = req.files;

    // If no image submitted, exit
    if (!image) return res.sendStatus(400);

    // Move the uploaded image to our upload folder
    image.mv(__dirname + '/upload/' + image.name);

    res.sendStatus(200);
});

You can now find the uploaded file in the upload folder.

Securing The Upload

While this works it’s not super secure, our users can now upload anything to our server, let’s restrict them a bit so our server is more secure.

Only Allowing Images

Let’s first block all uploaded files that aren’t images.

app.post('/upload', (req, res) => {
    const { image } = req.files;

    if (!image) return res.sendStatus(400);

    // If doesn't have image mime type prevent from uploading
    if (!/^image/.test(image.mimetype)) return res.sendStatus(400);

    image.mv(__dirname + '/upload/' + image.name);

    res.sendStatus(200);
});

This would cover most file uploads, it’s possible malicious actors use a different fake a different mimetype so to be absolutely sure a file is of a certain type we have to inspect the file contents itself.

Limit Upload Size

We can tell express-fileupload to limit the file upload size. This prevents users from uploading huge files in an attempt to DoS attack our server.

app.use(
    fileUpload({
        limits: {
            fileSize: 10000000, // Around 10MB
        },
        abortOnLimit: true,
    })
);

Now our server returns an HTTP 413 statuscode when the file is too big.

Preventing Malicious File Names

Malicious users can try to upload an image named ‘…/index.js’ but express-fileupload will automatically strip those dots and the file will still end up in the correct folder.

The Final Node.js Image Upload Script

This the complete Node.js script ready for copy pasting.

const express = require('express');
const fileUpload = require('express-fileupload');
const app = express();
const port = 3000;

app.use(
    fileUpload({
        limits: {
            fileSize: 10000000,
        },
        abortOnLimit: true,
    })
);

// Add this line to serve our index.html page
app.use(express.static('public'));

app.get('/', (req, res) => {
    res.send('Hello World!');
});

app.post('/upload', (req, res) => {
    // Get the file that was set to our field named "image"
    const { image } = req.files;

    // If no image submitted, exit
    if (!image) return res.sendStatus(400);

    // If doesn't have image mime type prevent from uploading
    if (!/^image/.test(image.mimetype)) return res.sendStatus(400);

    // Move the uploaded image to our upload folder
    image.mv(__dirname + '/upload/' + image.name);

    // All good
    res.sendStatus(200);
});

app.listen(port, () => {
    console.log(`Example app listening on port ${port}`);
});

Conclusion

We’ve written a server script that can handle image uploads, we secured our code, and finally we’ve set up a form that allows users to select and upload images.

We could take this a step further and enable our users to edit the images before upload. This saves server bandwidth and improves the quality of the images uploaded, for example by always forcing a square image.

The <pintura-input> element makes this straight forward. This Pintura powered web component automatically opens a powerful image editor when an image is added to the file input field and enables your users to edit images before upload.

How To Clone A File With JavaScript

2022-07-12T00:00:00Z

A short code example showing how to create a clone (or copy) from a File object received from a file input element.

We’ll use a file input element as a source for the file.

<input type="file" />

<script>
    document.querySelector('input').addEventListener('change', (e) => {
        // we'll get the first file in the file input
        const original = e.target.files[0];

        // no file received, exit
        if (!original) return;

        // create our clone
        const clone = new File([original], original.name, {
            type: original.type,
            lastModified: original.lastModified,
        });

        // log the original, the clone, and a comparison to the console
        console.log(original, clone, original === clone);
    });
</script>

Open your developer console and test it out below:

How To Set The Value Of A File Input

2022-06-23T00:00:00Z

It’s always been impossible to set the value of a file input element with JavaScript, but this has changed last year and it’s now broadly supported, let’s see how it’s done.

If you’re interested in why this is useful, read on below, else jump to the solution

Why Is Setting The Value Of A File Input Useful?

Being able to set the value of a file input comes in handy when we’ve edited an image in the browser, or when one or more files have been dropped on the page and we want to upload them to a server.

In both situations we end up with File objects that we can’t leave anywhere but in memory. We can serve the files as downloads, upload them asynchronously, or convert them to base64 strings and store them in a hidden text field, but we couldn’t store them in a file input element.

When we’re in control of the backend we can create an API to handle asynchronous file uploads or convert base64 encoded files back to file ojects. But there are a lot of situations where we don’t control the backend.

We’re using a NoCode platform or service.
We built a web component and don’t know where it’s going to be used.
There’s simply no time or people available to make the required backend changes.
The backend is so old that literally no one wants to touch it.

In all these situations there’s no way to upload File objects created in the browser.

The moment we can set the value of a file input the backend seizes to be part of the equation, meaning we can finally progressively enhance the file input element.

Updating The File Input Files Property

We’ll set up a file input element and a short script that sets the file input files property.

The script creates a new File object and stores it in myFile

We then use DataTransfer to wrap the file in a FileList which we can assign to the files property of our file input element.

<input type="file" />

<script>
    // Get a reference to our file input
    const fileInput = document.querySelector('input[type="file"]');

    // Create a new File object
    const myFile = new File(['Hello World!'], 'myFile.txt', {
        type: 'text/plain',
        lastModified: new Date(),
    });

    // Now let's create a DataTransfer to get a FileList
    const dataTransfer = new DataTransfer();
    dataTransfer.items.add(myFile);
    fileInput.files = dataTransfer.files;
</script>

And presto! The file input now contains “myFile.txt”

This works on all modern browsers. 🎉

Don’t see any file info? You’re probably browsing the web on Safari for MacOS 👇

But Safari

Safari was the last browser to add support for the DataTransfer constructor, it was added in version 14.1.

While Safari for MacOS detects the field has a value assigned it doesn’t show the file name. For some situations that’s fine, for others that is bad UX.

Interestingly it does work correctly on Safari for iOS 🤷‍♂️

Let’s give Safari for MacOS a little help using this knowledge:

Webkit based browsers can render pseudo-elements inside a file input.
The content of a pseudo-element can be set to an attribute value using attr()
Safari populates the webkitEntries property, Chrome doesn’t.

To target Safari we’ll check if webkitEntries has a length. Then we’ll set the current file name to the data-file attribute, finally we’ll add a pseudo-element and set its content property value to the value of the data-file attribute.

<style>
    /* Add pseudo-element only if data attribute is set */
    input[data-file]::after {
        content: attr(data-file);
        margin-left: 0.375em;
    }
</style>

<input type="file" />

<script>
    // Get a reference to our file input
    const fileInput = document.querySelector('input[type="file"]');

    // Create a new File object
    const myFile = new File(['Hello World!'], 'myFile.txt', {
        type: 'text/plain',
        lastModified: new Date(),
    });

    // Now let's create a FileList
    const dataTransfer = new DataTransfer();
    dataTransfer.items.add(myFile);
    fileInput.files = dataTransfer.files;

    // Help Safari out
    if (fileInput.webkitEntries.length) {
        fileInput.dataset.file = `${dataTransfer.files[0].name}`;
    }
</script>

The field below now shows the file name as well.

In a real project we’d probably want a more robust solution.

We could for example dispatch a custom 'change' event and then update the data-file attribute according to the contents of the files property.

Additionally we’d have to deal with multiple files, situations where the field is cleared, or where the user inputs a new file. But that’s for another time.

For now let’s just celebrate the fact that we can finally set the value of a file input element. 😅

Conclusion

We worked around the limitation of FileList not having a constructor by creating a DataTransfer instance, populating it with files, and then getting the files property from it.

To finish things of we helped Safari to correctly show the currently selected file name.

That’s it. It took a while but we finally have a viable solution to set the value of a file input element. I’ve been using this solution with Pintura in production since last year, and it’s been working wonderfully.

Annotate Images With JavaScript

2022-06-21T00:00:00Z

In this tutorial we use Pintura, a JavaScript image editor, to quickly create a JavaScript image annotation solution to annotate and decorate user submitted images and photos.

Our goal is to allows users to capture a photo using their mobile phone camera and then add annotations to it.

We’ll start by setting up a basic HTML form, we’re not going to reinvent the wheel so let’s use Pintura a JavaScript image editor SDK to handle the image annotation process.

Setting Up The Initial Code

We’ll start with a file input field, as that’s the most common way to request an image file from the user. We add the accept attribute to limit the file selection to images.

<input type="file" accept="image/*" />

Now to catch the image we listen for the 'change' event to fire, when it fires we get the first image file from the file input element.

<input type="file" accept="image/*" />

<script>
    document.querySelector('input').addEventListener('change', (e) => {
        const imageFile = e.target.files[0];

        // No image file selected, so nothing to edit
        if (!imageFile) return;

        // We have an image file, but what to do now?
        // ...
    });
</script>

Note that when the user clicks the cancel button in the browse file system dialog, the change event will still fire but the files property will be an empty FileList, that’s why we check if imageFile is actually defined.

This is the result, it doesn’t do anything, yet.

With our HTML file input ready we can now add Pintura to handle the image annotation process.

Loading The Image Editor

We’ll only load the Pintura module after an image file has been selected. This speeds up the initial page load as the editor won’t be needed when a user skips our file upload field.

<input type="file" accept="image/*" />
<script>
    document.querySelector('input').addEventListener('change', (e) => {
        const imageFile = e.target.files[0];
        if (!imageFile) return;

        // We have an image file, let's dynamically load Pintura
        import('./pintura.js').then(({ openDefaultEditor }) => {
            // Pintura has loaded, let's edit the image
            const editor = openDefaultEditor({
                src: imageFile,
            });

            // Pintura returns the resulting image and we store it in the file input
            editor.on('process', ({ dest }) => {
                const dataTransfer = new DataTransfer();
                dataTransfer.items.add(dest);
                e.target.files = dataTransfer.files;
            });
        });
    });
</script>

We’re going to have to improve the file input UX a tiny bit.

Note that if you just want get on with annotating images skip ahead to the image annotation section

Improving The File Input UX

This is what currently happens:

When an image file is selected the Pintura JavaScript module will be loaded.
When the module is finished loading Pintura will open the image file in a modal.
When the user is finished editing the file it is saved back to the file input.

This “works” but creates a problem where if the editor module takes a bit longer to load in step 1, the interface doesn’t give any feedback and the user is left wondering about the state of things.

To fix this we need to add an image loading indicator, it’ll let the user know what’s going on while waiting for the editor to load.

<input type="file" accept="image/*" />
<script>
    document.querySelector('input').addEventListener('change', (e) => {
        const imageFile = e.target.files[0];
        if (!imageFile) return;

        // Show loading indicator
        const loadingState = document.createElement('span');
        loadingState.className = 'loading';
        loadingState.textContent = 'Loading image…';
        e.target.before(loadingState);

        // We have an image file, let's dynamically load Pintura
        import('./pintura.js').then(({ openDefaultEditor }) => {
            // Now ready
            loadingState.remove();

            // Pintura has loaded, let's edit the image
            const editor = openDefaultEditor({
                src: imageFile,
            });

            // Hide loading indicator when the editor modal is fully visible
            editor.on('show', () => {
                loadingState.remove();
            });

            // Pintura returns the resulting image and we store it in the file input
            editor.on('process', ({ dest }) => {
                const dataTransfer = new DataTransfer();
                dataTransfer.items.add(dest);
                e.target.files = dataTransfer.files;
            });
        });
    });
</script>
<style>
    /* Hide the file input while loading */
    .loading ~ * {
        display: none;
    }
</style>

Excellent!

There’s one final UX thing to deal with.

When we save the image back to the file input nothing changes, the file name is the same, so the file input still looks the same.

We need to show that we’ve actually edited the image.

We’ll do this by adding a tiny image thumbnail before the file input. It’ll show the currently selected image and give the user confidence that the changes have been applied successfully.

<input type="file" accept="image/*" />
<script>
    document.querySelector('input').addEventListener('change', (e) => {
        const imageFile = e.target.files[0];
        if (!imageFile) return;

        // This adds or updates the current image preview
        const showPreview = () => {
            // Create a new preview or re-use existing one
            const image =
                e.target.parentNode.querySelector('.preview') || new Image();
            image.className = 'preview';

            // We don't want our preview to be too big
            image.width = 32;

            // If already loaded a preview, need to unload
            image.src && URL.revokeObjectURL(image.src);

            // Set the src of the preview image to the file object in the file input
            image.src = URL.createObjectURL(e.target.files[0]);

            // Attach/move the preview to before the file input
            e.target.before(image);
        };

        // Render a tiny image preview of the currently selected file
        showPreview();

        // Show loading indicator
        const loadingState = document.createElement('span');
        loadingState.className = 'loading';
        loadingState.textContent = 'Loading image…';
        e.target.before(loadingState);

        // We have an image file, let's dynamically load Pintura
        import('./pintura.js').then(({ openDefaultEditor }) => {
            // Pintura has loaded, let's edit the image
            const editor = openDefaultEditor({
                src: imageFile,
            });

            // Hide loading indicator when the editor modal is fully visible
            editor.on('show', () => {
                loadingState.remove();
            });

            // Pintura returns the resulting image and we store it in the file input
            editor.on('process', ({ dest }) => {
                const dataTransfer = new DataTransfer();
                dataTransfer.items.add(dest);
                e.target.files = dataTransfer.files;

                // Update our image preview with the edited file
                showPreview();
            });
        });
    });
</script>
<style>
    /* Styles the preview to be similar to the file input button */
    .preview {
        display: inline-block;
        width: 1.5rem;
        height: 1.5rem;
        object-fit: cover;
        margin-right: 0.3125rem;
        vertical-align: bottom;
        border-radius: 0.175rem;
    }

    /* Hide the file input and image preview while loading */
    .loading ~ * {
        display: none;
    }
</style>

While we side tracked quite a bit, it gave us some greate insight into what is needed to offer a good user experience.

Add an image to the field below to show the loading state and preview thumbnail.

That. Is. Nice. We’re finally ready to annotate images.

Annotating Images

While Pintura offers a wide range of tools to edit images we’re only interested in the annotation tool, in the next step we’ll limit the toolset to the annotation tool.

Note that starting from this code snippet we’re only altering the editor code, the rest of the code is hidden.

import('./pintura.js').then(({ openDefaultEditor }) => {
    const editor = openDefaultEditor({
        src: imageFile,

        // Only show the annotation tool
        utils: ['annotate'],
    });
});

The demo below reflects our changes. We’ve only selected one tool so the editor hides the toolbar creating more space for the active tool.

Try it out in the demo below, we can annotate our image with text, draw lines, and add shapes like circles and squares.

Adding Stickers

To make our annotation editor more powerful we can add stickers.

Stickers can be emoji, images, or shapes.

import('./pintura.js').then(({ openDefaultEditor }) => {
    openDefaultEditor({
        src: imageFile,
        utils: ['annotate'],

        // Set the stickers tool as the active tool
        annotateActiveTool: 'preset',

        // Add some stickers
        annotatePresets: [
            [
                // Add image based stickers
                'Numbers',
                ['sticker-one.svg', 'sticker-two.svg', 'sticker-three.svg'],
            ],
            [
                // Add emoji stickers
                'Emoji',
                ['👍', '👎'],
            ],
            [
                // Add shape stickers
                'Shapes',
                [
                    // A speech bubble
                    {
                        thumb: '💬',
                        alt: 'Speech cloud',
                        shape: {
                            width: 256,
                            height: 128,
                            fontSize: 64,
                            backgroundColor: [1, 1, 1, 0.85],
                            color: [0, 0, 0],
                            cornerRadius: 10,
                            text: 'Hello World',
                        },
                    },
                ],
            ],
        ],
    });
});

Let’s try out the stickers below.

Dynamic Annotation Shapes

Now for our final trick we’ll add a dynamic shape.

Imagine you need an annotation tool to measure the distance in pixels between two points. We can achieve that by adding a line shape that automatically expands to a text showing the distance between the start and end point.

In the code snippet below we first add the "measure" shape preset, this is the preset that we’ll expand in the next step.

import('./pintura.js').then(({ openDefaultEditor }) => {
    openDefaultEditor({
        src: imageFile,
        utils: ['annotate'],
        annotateActiveTool: 'preset',
        annotatePresets: [
            [
                'Numbers',
                ['sticker-one.svg', 'sticker-two.svg', 'sticker-three.svg'],
            ],
            ['Emoji', ['👍', '👎']],
            [
                'Shapes',
                [
                    {
                        thumb: '💬',
                        alt: 'Speech cloud',
                        shape: {
                            width: 256,
                            height: 128,
                            fontSize: 64,
                            backgroundColor: [1, 1, 1, 0.85],
                            color: [0, 0, 0],
                            cornerRadius: 10,
                            text: 'Hello World',
                        },
                    },
                    // Add our dynamic measure shape
                    {
                        thumb: '📏',
                        alt: 'Measure',
                        shape: {
                            style: 'measure',
                            x1: 0,
                            y1: 0,
                            x2: 100,
                            y2: 100,
                            strokeWidth: '.5%',
                            strokeColor: [0.5, 0.85, 1],
                            lineEnd: 'bar',
                            lineStart: 'bar',
                        },
                    },
                ],
            ],
        ],
    });
});

Now we need to automatically expand shapes with the 'measure' style property to show a text box, for this we’ll use a custom shape preprocessor.

For brevity the example below only shows the shapePreprocessor code.

import('./pintura.js').then(
    ({ openDefaultEditor, shapeGetCenter, shapeGetLength, shapeGetLevel }) => {
        openDefaultEditor({
            // ... other editor properties here

            // Set our custom shape preprocessor
            shapePreprocessor: [
                (shape, options) => {
                    // Should return undefined if shape is not a match
                    if (!shape.style || shape.style !== 'measure') return;

                    // Calculate the font size scalar so we can always read the font size info no matter the size of the image
                    const scalar = options.isPreview
                        ? Math.min(1, options.scale * 2)
                        : 1;

                    // Calculate line midpoint
                    const center = shapeGetCenter(shape);

                    // Calculate line length
                    const length = shapeGetLength(shape);

                    // Properties for the text label
                    const text = `${Math.round(length)}px`;
                    const fontSize = 24 / scalar;
                    const width = text.length * fontSize * 0.75;
                    const lineHeight = fontSize * 1.5;

                    // Return the text shape containing the line length
                    return [
                        {
                            width,
                            lineHeight,
                            text,
                            fontSize,
                            textAlign: 'center',
                            fontFamily: 'monospace',
                            color: [1, 1, 1],
                            backgroundColor: [0, 0, 0],
                            cornerRadius: 8,

                            // This places the text box in the middle of the line
                            x: center.x - width * 0.5,
                            y: center.y - lineHeight * 0.5,

                            // This makes sure the text box isn't flipped or rotated
                            ...shapeGetLevel(shape, options),
                        },
                    ];
                },
            ],
        });
    }
);

Let’s take a look at the final code, or skip to the final demo.

<input type="file" accept="image/*" />
<script>
    document.querySelector('input').addEventListener('change', (e) => {
        const imageFile = e.target.files[0];

        // No image file selected, so nothing to edit
        if (!imageFile) return;

        // This adds or updates the current image preview
        const showPreview = () => {
            // Create a new preview or re-use existing one
            const image =
                e.target.parentNode.querySelector('.preview') || new Image();
            image.className = 'preview';

            // We don't want our preview to be too big
            image.width = 32;

            // If already loaded a preview, need to unload
            image.src && URL.revokeObjectURL(image.src);

            // Set the src of the preview image to the file object in the file input
            image.src = URL.createObjectURL(e.target.files[0]);

            // Attach/move the preview to before the file input
            e.target.before(image);
        };

        // Render a tiny image preview of the currently selected file
        showPreview();

        // Show loading indicator
        const loadingState = document.createElement('span');
        loadingState.className = 'loading';
        loadingState.textContent = 'Loading image…';
        e.target.before(loadingState);

        // We have an image file, let's dynamically load Pintura
        import('./pintura.js').then(
            ({
                openDefaultEditor,
                shapeGetCenter,
                shapeGetLength,
                shapeGetLevel,
            }) => {
                // Pintura has loaded, let's edit the image
                const editor = openDefaultEditor({
                    src: imageFile,

                    // Set the stickers tool as the active tool
                    annotateActiveTool: 'preset',

                    // Add some stickers
                    annotatePresets: [
                        [
                            // Add image based stickers
                            'Numbers',
                            [
                                'sticker-one.svg',
                                'sticker-two.svg',
                                'sticker-three.svg',
                            ],
                        ],
                        [
                            // Add emoji stickers
                            'Emoji',
                            ['👍', '👎'],
                        ],
                        [
                            // Add shape stickers
                            'Shapes',
                            [
                                // A speech bubble
                                {
                                    thumb: '💬',
                                    alt: 'Speech cloud',
                                    shape: {
                                        width: 256,
                                        height: 128,
                                        fontSize: 64,
                                        backgroundColor: [1, 1, 1, 0.85],
                                        color: [0, 0, 0],
                                        cornerRadius: 10,
                                        text: 'Hello World',
                                    },
                                },
                                // Add our dynamic measure shape
                                {
                                    thumb: '📏',
                                    alt: 'Measure',
                                    shape: {
                                        style: 'measure',
                                        x1: 0,
                                        y1: 0,
                                        x2: 100,
                                        y2: 100,
                                        strokeWidth: '.5%',
                                        strokeColor: [0.5, 0.85, 1],
                                        lineEnd: 'bar',
                                        lineStart: 'bar',
                                    },
                                },
                            ],
                        ],
                    ],

                    // Set our custom shape preprocessor
                    shapePreprocessor: [
                        (shape, options) => {
                            // Should return undefined if shape is not a match
                            if (!shape.style || shape.style !== 'measure')
                                return;

                            // Calculate the font size scalar so we can always read the font size info no matter the size of the image
                            const scalar = options.isPreview
                                ? Math.min(1, options.scale * 2)
                                : 1;

                            // Calculate line midpoint
                            const center = shapeGetCenter(shape);

                            // Calculate line length
                            const length = shapeGetLength(shape);

                            // Properties for the text label
                            const text = `${Math.round(length)}px`;
                            const fontSize = 24 / scalar;
                            const width = text.length * fontSize * 0.75;
                            const lineHeight = fontSize * 1.5;

                            // Return the text shape
                            return [
                                {
                                    width,
                                    lineHeight,
                                    text,
                                    fontSize,
                                    textAlign: 'center',
                                    fontFamily: 'monospace',
                                    color: [1, 1, 1],
                                    backgroundColor: [0, 0, 0],
                                    cornerRadius: 8,

                                    // This centers the text box to the line
                                    x: center.x - width * 0.5,
                                    y: center.y - lineHeight * 0.5,

                                    // This makes sure the text box isn't flipped or rotated
                                    ...shapeGetLevel(shape, options),
                                },
                            ];
                        },
                    ],
                });

                // Hide loading indicator when the editor modal is fully visible
                editor.on('show', () => {
                    loadingState.remove();
                });

                // Pintura returns the resulting image and we store it in the file input
                editor.on('process', ({ dest }) => {
                    const dataTransfer = new DataTransfer();
                    dataTransfer.items.add(dest);
                    e.target.files = dataTransfer.files;
                    showPreview();
                });
            }
        );
    });
</script>
<style>
    /* Styles the preview to be similar to the file input button */
    .preview {
        display: inline-block;
        width: 1.5rem;
        height: 1.5rem;
        object-fit: cover;
        margin-right: 0.3125rem;
        vertical-align: bottom;
        border-radius: 0.175rem;
    }

    /* Hide the file input and image preview while loading */
    .loading ~ * {
        display: none;
    }
</style>

The demo that implements the above code, try it out! 🚀

Conclusion

We’ve created a flexible and powerful image annotation solution. Along the way we’ve learned quite a bit about offering a good user experience.

We can extend the editor further with more stickers and custom shapes.

Additionally we can use the editor API to disable stickers or sticker groups, limit the amount of stickers that a user may apply, or customize the HTML of the sticker thumbnails.

Overlap Elements With CSS Grid Instead Of Position Absolute

2022-06-02T00:00:00Z

We can use CSS absolute positioning to overlap elements, but there’s some advantages to using CSS grid instead. Let’s explore using CSS grid as an alternative to position absolute.

Overlapping Elements With Position Absolute

Using the styles below we can position multiple child elements relative to the first parent element that has a position property, in this case the direct parent.

<div class="parent">
    <div class="child">Robert</div>
    <div class="child">Charlene</div>
    <div class="child">Baby</div>
</div>

<style>
    .parent {
        position: relative;
    }

    .child {
        position: absolute;
        top: 0;
        left: 0;
    }
</style>

Below we can see absolute positioning in action, the different children names are rendered on top of each other.

Robert

Charlene

Baby

Right. That looks objectively horrible.

Now let’s try to achieve the same result with CSS Grid.

Overlapping Elements With Grid

We set display to grid on the parent element, and we define one grid column. 1fr means 1 part of all the available space, which in this case is everything.

We instruct the children to all occupy this one grid column. ⛺️

<div class="parent">
    <div class="child">Robert</div>
    <div class="child">Charlene</div>
    <div class="child">Baby</div>
</div>

<style>
    .parent {
        display: grid;
        grid-template-columns: 1fr;
    }

    .child {
        grid-row-start: 1;
        grid-column-start: 1;
    }
</style>

Let’s check out the equally horrible result below.

Robert

Charlene

Baby

It looks the same, but there’s an important difference.

Where the children in the absolute positioning example no longer affect page flow, meaning they no longer take up any vertical space, the children in the grid example do.

The parent in the positioning example has zero height where the height of the parent in the grid example equals the max child height.

Let’s look at them together, the position absolute example has a red outline, the grid example a green one.

Robert

Charlene

Baby

Robert

Charlene

Baby

So why is this relevant?

This is very useful when we need to animate overlapping elements but want to retain normal page flow.

Imagine a tab control where tab panels crossfade. With absolute positioning we would have to fix the height of the tab control. With grid the height is automatically derived from the child elements.

Conclusion

Absolute positioning has historically been the only way to effectively overlap elements. Unfortunately this meant detaching elements from the document layout, forcing us to assign a fixed or minimum height.

Using Grid we can overlap elements while retaining height resulting in more stable and clean code.

Slim Image Cropper Alternative

2022-05-10T00:00:00Z

In this short tutorial we’ll use the PinturaInput Web Component to replace a Slim Image Cropper instance with the more powerful Pintura Image Editor SDK.

The <pintura-input> web component core functionality is similar to Slim, it handles image editing and uploading for one image.

Because the component is using Pintura image editor it offers a lot more additional functionality than the image cropping and rotation features in Slim.

Let’s take a look at a working PinturaInput component.

From Slim Image Cropper To Pintura Input

Let’s use a default Slim editor template as our starting point.

<div
    class="slim"
    data-ratio="16:9"
    data-service="async.php"
    data-size="800,600"
    data-min-size="400,300"
>
    <input type="file" name="slim[]" />
</div>

Before we continue please note that in an effort to too keep the code snippets concise the PinturaInput default template is not shown, instead we’ll show a placeholder comment.

Let’s get started.

We replace the Slim element with the <pintura-input> web component tag, we can remove the original file input element.

<pintura-input image-crop-aspect-ratio="16/9" name="image">
    <!-- template placeholder -->
</pintura-input>

All serializable editor properties can be defined as an attribute on the PinturaInput element. Other properties will have to be defined elsewhere.

Let’s see how we can convert the data-size and data-min-size attributes to Pintura.

<script>
    window.myPinturaInput = {
        imageWriter: {
            targetSize: {
                width: 800,
                height: 600,
            },
        },
        imageCropMinSize: {
            width: 400,
            height: 300,
        },
        locale: {
            labelButtonExport: 'Confirm',
        },
    };
</script>

<pintura-input id="myPinturaInput" image-crop-aspect-ratio="16/9" name="image">
    <!-- template placeholder -->
</pintura-input>

We’ve created a global variable called myPinturaInput and have also set that as the id of our PinturaInput component.

We used the imageWriter property to set the intended output size, and have set the imageCropMinSize property to defined the minimum crop size.

Additionally we used the locale property to rename the button label to match the Slim Image Cropper button label.

Let’s now look at the Slim data-service attribute.

Uploading Synchronously

Using the PinturaInput we aren’t required to upload our files asynchronously, edited images can be submitted with a normal form post. We no longer need the data-service attribute.

Skip to Uploading Asynchronously if you still want to upload asynchronously.

Let’s look at the code needed for a default form post with file upload and image edit field.

<form method="POST" action="upload.php">
    <pintura-input image-crop-aspect-ratio="16/9" name="image">
        <!-- template placeholder -->
    </pintura-input>

    <button type="submit">Upload</button>
</form>

This code above will submit the edited file to the upload.php PHP script, there it can be accessed with $_FILES["image"], see this Image Uploading With PHP tutorial for additional information.

Uploading Asynchronously

If we still want upload images asynchronously we can do so with the store attribute, files can be handled with the same upload.php script. Uploads handled this way will show a nice progress indicator.

<pintura-input image-crop-aspect-ratio="16/9" store="upload.php" name="image">
    <!-- template placeholder -->
</pintura-input>

After the file has finished uploading the PinturaInput component will create a hidden input element and set the name attribute to the name of the PinturaInput component, the server response will be set to the value attribute.

In the example below the server has returned 1234 representing the id of the file on the server.

<pintura-input image-crop-aspect-ratio="16/9" store="upload.php" name="image">
    <!-- This element is created by Pintura Input -->
    <input type="hidden" name="image" value="1234" />

    <!-- template placeholder -->
</pintura-input>

Conclusion

With a couple of code adjustments we can switch to Pintura without much trouble and get a way more powerful image editor in return.

Pintura ships with example projects for all kinds of JavaScript frameworks making the switch from Slim to Pintura even easier.

If you’ve decided to switch over and need any help transitioning from Slim Image Cropper to Pintura, get in touch, I’m always happy to lend a hand.

How To Upload An Image With PHP

2022-05-09T00:00:00Z

In this quick tutorial we set up a basic HTML form to upload images with PHP, we also explore how to secure our PHP script so it can’t be abused by malicious users.

Setting Up An Image Upload Form

We start with a basic form.

The form contains a submit button and has an action attribute. The action attribute points to the page the form will post all its contents to when the submit button is clicked.

<form action="upload.php" method="POST">
    <button type="submit">Upload</button>
</form>

The form posts to a PHP file called upload.php. This file will handle the image upload. We’ll get to that in a minute.

To allow users to select a file we add a file input field.

<form action="upload.php" method="POST" enctype="multipart/form-data">
    <input type="file" name="image" accept="image/*" />
    <button type="submit">Upload</button>
</form>

At the same time we’ve also added the enctype form attribute and set it to "multipart/form-data". This is needed if we have a file input field in our form.

Because we’re only uploading images we add the accept attribute to the file input element and set it to image/* telling it to only accept files that have a mimetype that starts with image, like image/jpeg or image/png.

Let’s write the PHP image upload handler next.

Handling the PHP Image Upload

We’ll create a new file called upload.php in the same directory as the page that contains our form.

Next we create a directory called "images", also in the same directory. This is where our script will store uploaded image files using the move_uploaded_file function.

<?php

// Get reference to uploaded image
$image_file = $_FILES["image"];

// Image not defined, let's exit
if (!isset($image_file)) {
    die('No file uploaded.');
}

// Move the temp image file to the images/ directory
move_uploaded_file(
    // Temp image location
    $image_file["tmp_name"],

    // New image location, __DIR__ is the location of the current PHP file
    __DIR__ . "/images/" . $image_file["name"]
);

We’re done. This is all that’s needed to make it work.

Unfortunately not everyone on the internet is a saint. Our script currently allows anyone to upload anything, this is a security risk. We need to make sure people upload valid images and are not trying to harm our server.

Securing The Image Upload Process

We’re going to make extra sure these three things are in order.

The file needs to be an image.
The file must be smaller than 5MB.
The file must have a valid name.

Making Sure The File Is An Image

Let’s start by making sure the uploaded file is indeed an image.

Using exif_imagetype we can get the image mimetype, the function returns false when the file is not an image.

<?php

// Get reference to uploaded image
$image_file = $_FILES["image"];

// Exit if no file uploaded
if (!isset($image_file)) {
    die('No file uploaded.');
}

// Exit if is not a valid image file
$image_type = exif_imagetype($image_file["tmp_name"]);
if (!$image_type) {
    die('Uploaded file is not an image.');
}

// Move the temp image file to the images/ directory
move_uploaded_file(
    // Temp image location
    $image_file["tmp_name"],

    // New image location
    __DIR__ . "/images/" . $image_file["name"]
);

Next we need to stop users from uploading very large files.

Limiting The File Size

In the example below we limit the image file size to 5MB, of course you can choose your own limit, but it’s a good idea to at least cap it at a certain point to prevent users from uploading gigabytes of data in an attempt to DoS attack your server.

In the directory of our upload.php script we create a .htaccess file and set its contents to the following.

LimitRequestBody 5242880

The LimitRequestBody prevents a request from exceeding 5MB, note that this includes other fields in the form.

Now let’s make sure users can’t uploading 0 byte files. We use filesize to read out the actual file size instead of rely on the ["size"] reported by $_FILES as that can be modified by the user.

<?php

// Get reference to uploaded image
$image_file = $_FILES["image"];

// Exit if no file uploaded
if (!isset($image_file)) {
    die('No file uploaded.');
}

// Exit if image file is zero bytes
if (filesize($image_file["tmp_name"]) <= 0) {
    die('Uploaded file has no contents.');
}

// Exit if is not a valid image file
$image_type = exif_imagetype($image_file["tmp_name"]);
if (!$image_type) {
    die('Uploaded file is not an image.');
}

// Move the temp image file to the images/ directory
move_uploaded_file(
    // Temp image location
    $image_file["tmp_name"],

    // New image location
    __DIR__ . "/images/" . $image_file["name"]
);

Let’s now make sure the file name of the image is valid.

Guarding Against Malicious File Names

Malicious actors can try to upload an image with named '../index.php', our PHP script would now store this “image” in 'images/../index.php' possibly overwriting our own index.php file.

We can try to sanitize the image file name, but a safer approach is to generate our own file name.

We’ll generate some random_bytes and use those as the name for our image.

<?php

// Get reference to uploaded image
$image_file = $_FILES["image"];

// Exit if no file uploaded
if (!isset($image_file)) {
    die('No file uploaded.');
}

// Exit if image file is zero bytes
if (filesize($image_file["tmp_name"]) <= 0) {
    die('Uploaded file has no contents.');
}

// Exit if is not a valid image file
$image_type = exif_imagetype($image_file["tmp_name"]);
if (!$image_type) {
    die('Uploaded file is not an image.');
}

// Get file extension based on file type, to prepend a dot we pass true as the second parameter
$image_extension = image_type_to_extension($image_type, true);

// Create a unique image name
$image_name = bin2hex(random_bytes(16)) . $image_extension;

// Move the temp image file to the images directory
move_uploaded_file(
    // Temp image location
    $image_file["tmp_name"],

    // New image location
    __DIR__ . "/images/" . $image_name
);

Our last step is to prevent code from being executed in our images directory.

Preventing Code Execution In The Images Directory

In our images directory we create a .htaccess file and set its contents to the following to prevent any uploaded PHP files from being run.

This make sure that PHP code in this folder won’t execute. So if someone still manages to upload a PHP file, for example a PHP file disguised as an image, it still won’t run.

php_flag engine off

Our file upload process is now secure. 🎉

Conclusion

We’ve written a basic form with file input element, to handle the upload we created a PHP file that moves the uploaded image to a directory on the server. To secure the upload process, we made sure the filename is valid, the file size is not too high, and the uploaded file is actually an image.

If you’re also looking to add image editing functionality to the file upload field you can use the <pintura-input> element. This Pintura powered web component automatically opens a powerful image editor when an image is added to the field and enables your users to edit images before upload.

Fix HTML Video Autoplay Not Working

2022-04-12T00:00:00Z

To optimise pages on this blog I recently replaced the animated GIFs with auto-playing videos. It required a couple tries to get it right, so here’s how it works.

The video below won’t autoplay.

<video autoplay>
    <source src="video.mp4" type="video/mp4" />
</video>

To fix this we add the muted attribute, this will disable the audio, making the video less intrusive.

<video autoplay muted>
    <source src="video.mp4" type="video/mp4" />
</video>

However the video above still won’t autoplay on iOS Safari, Safari requires us to add the playsinline attribute.

<video autoplay muted playsinline>
    <source src="video.mp4" type="video/mp4" />
</video>

We can try to hack around these autoplay limitations with some JavaScript, but that will only work if the JavaScript is run as a result of a user action.

The code below won’t work, it will throw a warning in the developer console.

document.querySelector('video').play();

The play action below will work because the code runs as a result of a user action.

<button>Play</button>

<script>
    document.querySelector('button').addEventListener('click', () => {
        document.querySelector('video').play();
    });
</script>

Press to play the first video on the page.

Convert An Image To A DataURL or Base64 String Using JavaScript

2022-03-24T00:00:00Z

In this short tutorial we explore 3 different JavaScript methods to convert an image into a Base64 string. We look at converting a File object or Blob, a canvas element, and an image tag.

In all examples below we assume we already have a <canvas>, <img>, File, or Blob object available.

We’ll be converting images to DataURLs, we can use the function below to convert a DataURL to a Base64 string.

const getBase64StringFromDataURL = (dataURL) =>
    dataURL.replace('data:', '').replace(/^.+,/, '');

Let’s get started.

Image is a File object or Blob

When the image is a File object or Blob we can use the FileReader API please see this article on converting a file to base64 string or dataURL.

We’ll also use the FileReader API when converting an image tag to a Base64 string.

Image is a Canvas element

If we have a <canvas> that we want to turn into a Base64 string we can use toDataURL on the Canvas element.

<canvas width="300" height="150" id="my-canvas"></canvas>

<script>
    const canvas = document.getElementById('my-canvas');

    // Convert canvas to dataURL and log to console
    const dataURL = canvas.toDataURL();
    console.log(dataURL);
    // Logs data:image/png;base64,wL2dvYWwgbW9yZ...

    // Convert to Base64 string
    const base64 = getBase64StringFromDataURL(dataURL);
    console.log(base64);
    // Logs wL2dvYWwgbW9yZ...
</script>

By default the canvas outputs to a lossless PNG, we can pass 'image/png', 'image/jpeg' or 'image/webp' to the toDataURL method to get a different format.

When using 'image/jpeg' or 'image/webp' we can pass the image compression as the last argument, 0 means a lot of compression, 1 means no compression.

<canvas width="300" height="150" id="my-canvas"></canvas>

<script>
    const canvas = document.getElementById('my-canvas');

    // Convert canvas to dataURL and log to console
    const dataURL = canvas.toDataURL('image/jpeg', 0.5);
    console.log(dataURL);
    // Logs data:image/jpeg;base64,wL2dvYWwgbW9yZ...

    // Convert to Base64 string
    const base64 = getBase64StringFromDataURL(dataURL);
    console.log(base64);
    // Logs wL2dvYWwgbW9yZ...
</script>

Image is an img element

If our image is an <img> element we can fetch the image src and convert that to a Base64 string.

Alternatively we can draw the image to a canvas and then convert the canvas to an image element, this would be useful if we’re looking for a specific image format.

If the image is located on a remote server the CORS configuration of the remote server must allow our local script to access the image.

Fetching the image source

Note that the MIME type returned by remote server in the Content-Type response header is reflected in the DataURL.

If the MIME type is incorrect the DataURL will be incorrect as well.

<img src="my-image.jpeg" id="my-image" />

<script>
    const image = document.getElementById('my-image');

    // Get the remote image as a Blob with the fetch API
    fetch(image.src)
        .then((res) => res.blob())
        .then((blob) => {
            // Read the Blob as DataURL using the FileReader API
            const reader = new FileReader();
            reader.onloadend = () => {
                console.log(reader.result);
                // Logs data:image/jpeg;base64,wL2dvYWwgbW9yZ...

                // Convert to Base64 string
                const base64 = getBase64StringFromDataURL(reader.result);
                console.log(base64);
                // Logs wL2dvYWwgbW9yZ...
            };
            reader.readAsDataURL(blob);
        });
</script>

Drawing the image to a canvas

Drawing the image to a canvas first allows us to convert it to a different format.

Please note that this approach is slower than simply fetching the image src as shown in the previous example.

An additional caveat is that the canvas element has a maximum size, for some browsers this size limit is very low causing problems when converting the image.

<img src="my-image.jpeg" id="my-image" />

<script>
    const image = document.getElementById('my-image');

    const toDataURL = () => {
        const canvas = document.createElement('canvas');

        // We use naturalWidth and naturalHeight to get the real image size vs the size at which the image is shown on the page
        canvas.width = image.naturalWidth;
        canvas.height = image.naturalHeight;

        // We get the 2d drawing context and draw the image in the top left
        canvas.getContext('2d').drawImage(image, 0, 0);

        // Convert canvas to DataURL and log to console
        const dataURL = canvas.toDataURL();
        console.log(dataURL);
        // logs data:image/png;base64,wL2dvYWwgbW9yZ...

        // Convert to Base64 string
        const base64 = getBase64StringFromDataURL(dataURL);
        console.log(base64);
        // Logs wL2dvYWwgbW9yZ...
    };

    // If the image has already loaded, let's go!
    if (image.complete) toDataURL(image);
    // Wait for the image to load before converting
    else image.onload = toDataURL;
</script>

Wrapping up

We converted a File, Blob, <canvas>, and <img> to DataURLs and we looked at how to convert a DataURL to a Base64 string. By looking at different methods to convert images to Base64 strings we now know the pros and cons of each approach.

Fix Google Search Console Mobile Usability Issues With A CSS Snippet

2022-03-18T00:00:00Z

Every other week Google Search Console will send me an email reporting Mobile Usability issues on this blog. I’ll log in, click “Validate Fix”, and find that everything is just peachy. What’s going on? More importantly, how do we fix this?

Usually Google Search Console reports one or all of the following issues:

Clickable elements too close together
Text too small to read
Content wider than screen

The pages it finds these issues on are seemingly random.

What’s causing this?

The origin of the issue is two-fold:

Sometimes the Googlebot is in a hurry and will not fetch all page resources when it loads your page for indexing.
One or several HTML elements on the page are wider than the mobile viewport but only so when your CSS fails to load.

Things go haywire when Googlebot skips your CSS file on a page where some content forces the viewport to scale or scroll if it doesn’t receive a CSS style.

This could for example be an <img> or <video> tag without a width attribute, or a code snippet with long lines in a <pre> (as seen in the image below).

Another culprit can be the content itself. Super long German words like Rechtsschutzversicherungsgesellschaften won’t automagically wrap to the next line.

How to fix it?

We can press “Validate Fix” and that’ll fix it the day after, but that gets old fast. Instead we need a more permanent solution.

The fix is a small set of CSS styles. We can add the following code snippet to the <head> of the page.

Preferably right before the <link> element that references our stylesheet.

<style>
    :where(body, iframe, pre, img, svg, video, canvas, select) {
        max-width: 100%;
        overflow: auto;
        word-break: break-word;
    }
</style>

This snippet makes sure that when Googlebot ignores your page resources, it at least applies these styles to the elements in the :where() selector list.

max-width: 100% prevents the elements from being wider than the viewport.
overflow: auto makes sure that content inside an element won’t push an element over its width limit.
word-break: break-word makes sure long words are wrapped to the next line when they extend beyond the viewport width.

We use the :where() selector so the styles are applied with 0 specificity. This means that we will be able to overwrite these styles in our stylesheet without having to make our selectors extra specific.

After copying the snippet to your page, ask Google Search Console, for one final time, to “Validate The Fix”, the issues should go away over the next few days and will only return if you make an actual mistake in your stylesheet.

Conclusion

Instead of gambling on the Googlebot we took matters into our own hands and secured our HTML elements against breaking the site by applying a tiny set of base styles.

While this will make Googlebot happy it will also one day make one of your visitors happy when inevitably your stylesheet fails due to unforeseen consequences or the universe aligning in a weird way.

Instead of rolling with our eyes we can now trust something is wrong when Google Search Console sends us a Mobile Usability issue report.

Generate Social Image Covers With Eleventy And Node-Canvas

2022-03-17T00:00:00Z

This static blog is generated with Eleventy and all its social images are automatically generated with node-canvas. In this tutorial we’ll set up a basic version of this script so you can use it on your blog as well.

For this tutorial we assume you already have an Eleventy site that you want to add social images to.

If you need to set up a new site you can follow the Eleventy getting started guide to set up your site.

If you’re in a hurry and just want to copy paste the code, skip to the conclusion

Installing Node-Canvas

node-canvas is an HTML Canvas implementation in Node. It allows us to draw to a canvas in Node just as we would in the browser, this makes it super easy to get started with.

Note that we use canvas instead of node-canvas to install the package.

npm install canvas

We’ll leave our canvas in the oven while we work on preparing the Eleventy script.

Configuring the Eleventy Script

We’re going to edit the .eleventy.js file. It’s the file that we use to configure our Eleventy site. If this file doesn’t exist in your project, create it and paste the contents below.

Please note that this tutorial assumes your site articles are located in the src directory and the output location is the dist directory. If your articles are in a different directory the code will still work but you might have to adjust some paths.

// .eleventy.js
module.exports = function (eleventyConfig) {
    return {
        dir: {
            input: 'src',
            output: 'dist',
        },
    };
};

Run npx @11ty/eleventy to test if the pages are generated in the dist folder.

We insert the addTransform hook to intercept the moment Eleventy generates an article so we can create our social image at the same time.

module.exports = function (eleventyConfig) {
    eleventyConfig.addTransform('social-image', async function (content) {
        // this will run each time a file is handled by Eleventy
        return content;
    });

    return {
        dir: {
            input: 'src',
            output: 'dist',
        },
    };
};

We’re only interested in articles, so let’s filter out any other files.

this.inputPath contains the location of the input file. We check if it ends with .md (for Markdown) and else we exit by returning the article contents.

module.exports = function (eleventyConfig) {
    eleventyConfig.addTransform('social-image', async function (content) {
        // only handle blog posts
        if (!this.inputPath.endsWith('.md')) return content;

        // do something with the article

        // return normal content
        return content;
    });

    return {
        dir: {
            input: 'src',
            output: 'dist',
        },
    };
};

It’s time to add the function that will generate the social image for our article.

We create the createSocialImageForArticle function that returns a Promise. It receives the location of the input article and the location of the output social image.

In the example below we use the same name as the input article but replace the extension with .jpeg.

const createSocialImageForArticle = (input, output) =>
    new Promise((resolve, reject) => {
        // this is where we'll generate the social image
    });

module.exports = function (eleventyConfig) {
    eleventyConfig.addTransform('social-image', async function (content) {
        // only handle blog posts
        if (!this.inputPath.endsWith('.md')) return content;

        try {
            await createSocialImageForArticle(
                // our input article
                this.inputPath,

                // the output image name
                this.outputPath.replace('.html', '.jpeg')
            );
        } catch (err) {
            console.error(err);
        }

        // return normal content
        return content;
    });

    return {
        dir: {
            input: 'src',
            output: 'dist',
        },
    };
};

We’ve filtered out non-articles and have set up a function to draw our canvas and output the matching social image, let’s move on to implementing the function.

We’re now ready to draw the social image cover.

In the code examples below we’ll only focus on the createSocialImageForArticle function, we won’t touch any other code so the rest of the code is hidden.

const createSocialImageForArticle = (input, output) =>
    new Promise((resolve, reject) => {
        // this is where we'll generate the social image
    });

First we need to load the node modules we’re going to use.

// for handling files
const fs = require('fs');

// for managing path information
const path = require('path');

// for creating the canvas
const { createCanvas } = require('canvas');

// our good old function
const createSocialImageForArticle = (input, output) =>
    new Promise((resolve, reject) => {
        // this is where we'll generate the social image
    });

For this part we’ll assume the title of the article is defined in the Front Matter of the file.

---
title: My article title
---

Our goal is to draw the title of the article on the cover image. To do that we’ll have to read out the file data and “parse” the YAML Front Matter.

const fs = require('fs');
const path = require('path');
const { createCanvas } = require('canvas');

const createSocialImageForArticle = (input, output) =>
    new Promise((resolve, reject) => {
        // read data from input file
        const data = fs.readFileSync(input, {
            encoding: 'utf-8',
        });

        // get title from file data
        const [, title] = data.match(/title:(.*)/);

        // `title` contains the article title
    });

Alright, we’re ready to start drawing. Let’s create a canvas with a white background and draw our article title to it in black.

const fs = require('fs');
const path = require('path');
const { createCanvas } = require('canvas');

const createSocialImageForArticle = (input, output) =>
    new Promise((resolve, reject) => {
        // read data from input file
        const data = fs.readFileSync(input, {
            encoding: 'utf-8',
        });

        // get title from file data
        const [, title] = data.match(/title:(.*)/);

        // draw cover image
        const canvas = createCanvas(1024, 512);
        const ctx = canvas.getContext('2d');

        ctx.fillStyle = 'white';
        ctx.fillRect(0, 0, canvas.width, canvas.height);

        ctx.fillStyle = 'black';
        ctx.font = '64px sans-serif';
        ctx.fillText(title, 0, 64);
    });

If you’ve worked with the Canvas API before this is all very familiar.

Now for the final act, saving the canvas data to disk.

We’re writing our image before Eleventy writes the article HTML file so we need to make sure the article directory already exists.

const fs = require('fs');
const path = require('path');
const { createCanvas } = require('canvas');

const createSocialImageForArticle = (input, output) =>
    new Promise((resolve, reject) => {
        // read data from input file
        const data = fs.readFileSync(input, {
            encoding: 'utf-8',
        });

        // get title from file data
        const [, title] = data.match(/title:(.*)/);

        // draw cover image
        const canvas = createCanvas(1024, 512);
        const ctx = canvas.getContext('2d');

        ctx.fillStyle = 'white';
        ctx.fillRect(0, 0, canvas.width, canvas.height);

        ctx.fillStyle = 'black';
        ctx.font = '64px sans-serif';
        ctx.fillText(title, 0, 64);

        // test if the output directory already exists, if not, create
        const outputDir = path.dirname(output);
        if (!fs.existsSync(outputDir))
            fs.mkdirSync(outputDir, { recursive: true });

        // write the output image
        const stream = fs.createWriteStream(output);
        stream.on('finish', resolve);
        stream.on('error', reject);
        canvas
            .createJPEGStream({
                quailty: 0.8,
            })
            .pipe(stream);
    });

We’re done. If we now run npx @11ty/eleventy we should see a JPEG pop up next to our article HTML file.

We can now reference the image in a open graph meta tag like so.

<meta
    property="og:image"
    content="https://site.domain/article-path/index.jpeg"
/>

Conclusion

Using two amazing open source tools we’ve quickly set up flexible and automated generation of social images.

The node-canvas API allows us to easily finetune our graphics. It exports useful helper methods like loadImage to quickly load and draw images on top of your canvas, and registerFont to facilitate loading and using locally hosted fonts.

Inspect the finished script below, it’s ready for some serious copy paste action.

// .eleventy.js
const fs = require('fs');
const path = require('path');
const { createCanvas } = require('canvas');

const createSocialImageForArticle = (input, output) =>
    new Promise((resolve, reject) => {
        // read data from input file
        const data = fs.readFileSync(input, {
            encoding: 'utf-8',
        });

        // get title from file data
        const [, title] = data.match(/title:(.*)/);

        // draw cover image
        const canvas = createCanvas(1024, 512);
        const ctx = canvas.getContext('2d');

        ctx.fillStyle = 'white';
        ctx.fillRect(0, 0, canvas.width, canvas.height);

        ctx.fillStyle = 'black';
        ctx.font = '64px sans-serif';
        ctx.fillText(title, 0, 64);

        // test if the output directory already exists, if not, create
        const outputDir = path.dirname(output);
        if (!fs.existsSync(outputDir))
            fs.mkdirSync(outputDir, { recursive: true });

        // write the output image
        const stream = fs.createWriteStream(output);
        stream.on('finish', resolve);
        stream.on('error', reject);
        canvas
            .createJPEGStream({
                quailty: 0.8,
            })
            .pipe(stream);
    });

module.exports = function (eleventyConfig) {
    eleventyConfig.addTransform('social-image', async function (content) {
        // only handle blog posts
        if (!this.inputPath.endsWith('.md')) return content;

        try {
            await createSocialImageForArticle(
                // our input article
                this.inputPath,

                // the output image name
                this.outputPath.replace('.html', '.jpeg')
            );
        } catch (err) {
            console.error(err);
        }

        // return normal content
        return content;
    });

    return {
        dir: {
            input: 'src',
            output: 'dist',
        },
    };
};

Crop Images Before Upload With JavaScript

2022-03-10T00:00:00Z

In this 3 minute tutorial we use CropGuide, a JavaScript image cropper, to crop images before they’re uploaded to our server without making any changes to existing file upload code.

For this tutorial we’ll assume that a form with a file upload field has already been set up.

Our goal is to add image editing to this field without having to modify any existing code.

Why help your users Crop Images?

To speed up the image upload. A lower image size results in faster uploads, improved upload stability, and less disk usage;
To receive better user generated content. With some guidance users can crop the important parts of an image;
To lower image upload friction. Users aren’t designers. If an image isn’t in our desired aspect ratio or bigger than the maximum file size they won’t always know how to fix that;

When we optimise images before uploading, we not only get better images, we also get more images because there’s less users that will exit our form out of frustration.

Using CropGuide to Crop Images

In this tutorial we’ll use CropGuide as our JavaScript image cropping solution.

CropGuide helps with:

Enforcing a crop aspect ratio;
Requiring a minimum image size;
Automatically scale images to a maximum size;
Compressing images or converting image formats;
Fixing image orientation issues;

Installation only takes a couple minutes and requires two steps:

We create a CropGuide account
We add the CropGuide <script> to our webpage
Done!

CropGuide now automatically intercepts each file upload and offers an image editor to the user. We can set our image requirements in the CropGuide dashboard.

Important: Images aren’t uploaded to CropGuide, image editing happens in the browser which is great for privacy and performance.

This is what our code looks like.

<!-- The existing file input somewhere in our form -->
<input type="file" />

<!-- The script tag we just added to our page -->
<script defer src="https://cdn.crop.guide/loader/l.js?c=123ABC"></script>

Try out the image editor by selecting an image below. Images are edited in the browser, nothing is uploaded.

While this is a very basic file input, CropGuide works just as well with advanced JavaScript file upload libraries.

NoCode Image Cropping

CropGuide can be installed and configured without any code changes, making it perfect for use with NoCode services.

It has been tested with popular tools like Bubble, Shopify, Webflow, Weebly, Squarespace, and Carrd. It just works ™

It’s also suitable for products like WordPress. Follow this WordPress tutorial on how to add the CropGuide script tag and get image editing on your WordPress form.

If a user can upload an image on your website, you can use CropGuide to offer image cropping.

Wrapping up

We’ve added image cropping to our website by inserting a single script tag on our webpage. There was no need to edit any server logic, or adjust any JavaScript, saving us lots of time.

Our users can now more easily upload images, resulting in higher quality images and more images uploaded. We save time correcting image problems on the server and helping users prepare their images.

If you’re looking for a more tightly integrated image editor solution with a bigger featureset then Pintura is be a great fit.

Total Canvas Memory Use Exceeds The Maximum Limit

2022-01-12T00:00:00Z

You’re using the HTML Canvas Element in your new web app and decide to quickly test on iOS Safari. Suddenly your canvas isn’t drawn and the console shows a yellow warning “Total canvas memory use exceeds the maximum limit”. What gives?

While you were busy building, Safari was busy stuffing itself.

Safari has a thing for hoarding <canvas> elements. When you’re done with a canvas, Safari will hold on to it for a while, even if you’re not referencing it.

It has a cute little showcase where it presents all the canvas elements it’s currently holding on to.

That’s. Just. Great.

Safari on iOS has the same hobby. It desperatly wants to keep up with its big brother on MacOs but it just doesn’t have the same storage capacity.

Once the storage box is full, it’ll throw this message and start drawing transparent canvas elements.

So how do we deal with this?

We’re going to have to help out Safari to clean up its mess. Get rid of the things it can’t or won’t throw away.

When we’re done with a <canvas> element we have to manually “release” it.

Meaning we resize the canvas to a very small size and clear its contents, this tricks Safari in to replacing the canvas in its storage with our compressed version.

The following function will do just that.

function releaseCanvas(canvas) {
    canvas.width = 1;
    canvas.height = 1;
    const ctx = canvas.getContext('2d');
    ctx && ctx.clearRect(0, 0, 1, 1);
}

Safari will still hold on to the <canvas> for a while, but at least now it won’t blow the roof of its storage depot.

Unfortunately the memory limit on iOS Safari is rather low. It’s limited to 384MB on version 15, it’s lower on earlier versions, and it’s probably device specific as well.

A canvas pixel is made up of 4 values, red, green, blue, and an alpha value. Combining this with the canvas size we can calculate the amount of memory a canvas requires.

4096 × 4096 × 4 = 67108864 Bytes = 64 Megabytes

This is also the max size of a canvas on Safari

Let’s exceed the 384MB limit by creating 8 of these canvas elements.

for (let i = 0; i < 8; i++) {
    const canvas = document.createElement('canvas');
    canvas.width = 4096;
    canvas.height = 4096;
    const ctx = canvas.getContext('2d');
    ctx && ctx.fillRect(0, 0, 100, 100);
}

If the maximum limit was exceeded earlier the getContext('2d') method will return null so that’s why we check if the ctx variable is set before calling fillRect

When we add the releaseCanvas function we force Safari to free up some memory and the warning goes away.

for (let i = 0; i < 8; i++) {
    const canvas = document.createElement('canvas');
    canvas.width = 4096;
    canvas.height = 4096;
    const ctx = canvas.getContext('2d');
    ctx && ctx.fillRect(0, 0, 100, 100);

    // Force release each canvas
    releaseCanvas(canvas);
}

What we should keep in mind is that Safari either:

caches canvas elements across sessions
or doesn’t recalculate the free memory correctly on page refresh

So a page refresh might not clean up the error immediately, it might still show and only dissapear after multiple refreshes or clearing the cache.

Canvas Area Exceeds The Maximum Limit

2022-01-12T00:00:00Z

If there’s one thing I’m sure of it’s that Safari and the HTML canvas element aren’t sitting in a tree together. It’s 2022 and Safari still can’t handle canvas elements having more than 16777216 pixels.

Safari simply cannot draw large canvas elements. The limit is set at 16.777.216 pixels. Create a canvas with more pixels and iOS Safari will tell us it exceeds the memory limit.

When we open this page on iOS Safari, it’ll show the following warning in the developer console.

That’s because the page creates a canvas that is 4097 × 4096 pixels in size and tries to use its 2d context.

const canvas = document.createElement('canvas');
canvas.width = 4097;
canvas.height = 4096;

const ctx = canvas.getContext('2d');
ctx.fillRect(0, 0, 100, 100);

All is fine until we want to fill our rectangle. That’s where Safari draws a line in the sand.

As we can see it doesn’t matter if we only use part of the canvas. The moment we try to interact with the canvas rendering context Safari warns the canvas is too big.

Well at least on MacOS Safari we don’t get the memory limit warning.

Problem is, if we want to get the ImageData in the canvas, MacOS Safari will invalidate the canvas element if the requested data amount exceeds the maximum size.

ctx.getImageData(0, 0, 4097, 4096);

If you’re on Safari, click below to run the above code.

Say hello to these errors in your developer console.

So how to deal with this limitation.

We can create canvas elements that exceed 4096 pixels in width or height as long as the total amount of pixels is below 16777216.

This will work:

const canvas = document.createElement('canvas');
canvas.width = 5120;
canvas.height = 3072;

const ctx = canvas.getContext('2d');
ctx.fillRect(0, 0, 100, 100);

To make it easier to stay below the limit we can use the following function. It returns a relatively scaled size below the maximumPixels passed.

function limitSize(size, maximumPixels) {
    const { width, height } = size;

    const requiredPixels = width * height;
    if (requiredPixels <= maximumPixels) return { width, height };

    const scalar = Math.sqrt(maximumPixels) / Math.sqrt(requiredPixels);
    return {
        width: Math.floor(width * scalar),
        height: Math.floor(height * scalar),
    };
}

Conclusion, when we’re dealing with Safari, we should always make sure to limit the size of our canvas elements before drawing to it. Other browsers have limits at a much higher level that we’re unlikely to exceed.

Our suffering doesn’t end here, the worst is yet to come.

When we create too many canvas elements we’ll run into a secondary Safari issue. We’ll explore that issue in the follow up article Total canvas memory use exceeds the maximum limit

Drawing Wrapped Text With The HTML Canvas Element

2021-11-05T00:00:00Z

The HTML canvas element can draw text but it cannot wrap text. Text wrapping is complicated so in this tutorial, instead of breaking text lines with JavaScript, we’ll lean on native browser tech to draw wrapped text lines.

Let’s try to draw the paragraph below to a canvas element.

Lorem Ipsum is simply dummy text of the printing and typesetting industry.

Using Canvas fillText

We’ll first give fillText() a go. As the native canvas text drawing method it deserves a fair chance.

// Get the 2d drawing context of our canvas
const ctx = document.getElementById('canvas').getContext('2d');

// Set the font-size and font-family to mimic our paragraph
ctx.font = '20px serif';

// Draw the text
ctx.fillText('Lorem Ipsum is … typesetting industry.', 0, 20);

As we can see below, the text won’t wrap.

The HTML canvas API exposes some other methods to draw basic shapes and paths but those aren’t of use to us when we want to draw text.

We’re left with drawImage(). The method used to draw ImageData to a canvas element.

If we can only use drawImage it means we have to get our text in a format that can be passed to the drawImage method.

The method accepts:

HTMLCanvasElement
HTMLImageElement
SVGImageElement
HTMLVideoElement
ImageBitmap
OffscreenCanvas

Let’s keep those in mind and go back to drawing wrapped text.

Text wrapping in a graphic format

What other ways can we use to draw wrapped text? We’ve already drawn wrapped text to the screen with our reference paragraph above, but unfortunatley we cannot pass HTML to the drawImage method.

We can however pass an image element, so maybe we can use SVG to draw wrapped text. Let’s try it now.

<svg width="280" height="100" xmlns="http://www.w3.org/2000/svg">
    <text x="0" y="20">Lorem Ipsum is … typesetting industry.</text>
</svg>

Nope.

The SVG <text> element seems to be related to the canvas fillText method.

Luckily our friend <foreignObject> enables us to put HTML in SVG.

<svg width="280" height="100" xmlns="http://www.w3.org/2000/svg">
    <foreignObject x="0" y="0" width="280" height="100">
        <style>
            p {
                margin: 0;
                font-weight: normal;
                font-family: serif;
                font-size: 20px;
                line-height: 32px;
            }
        </style>
        <!-- Yo! -->
        <p xmlns="http://www.w3.org/1999/xhtml">
            Lorem Ipsum is … typesetting industry.
        </p>
    </foreignObject>
</svg>

Check it out below and let’s claim this small victory!

But just like we can’t pass our HTML paragraph to the drawImage method we can’t pass this SVG code to the drawImage method.

But unlike HTML we can pass SVG to an image element and we can pass an image element to the drawImage method.

To do that we need to convert our SVG to a dataURL.

<img src="data:image/svg+xml,…" />

Loading inline SVG to an image element

We’ll load the SVG from the previous example and convert it to a dataURL which we can assign to our image src attribute.

// Get a reference to the svg element
const svgElement = document.getElementById('svg');

// Get the SVG code in string format <svg>...
const svgCode = svgElement.outerHTML;

// Remove newlines and replace double quotes with single quotes
const svgCodeEncoded = svgCode.replace(/\n/g, '').replace(/"/g, "'");

// Get the image element and use our svg as src
const imgElement = document.getElementById('svgImage');
imgElement.src = `data:image/svg+xml,${svgCodeEncoded}`;

Below we can see that the SVG is loaded in our image element.

Now for our final trick we have to draw the image element containing our inline SVG to our canvas element. We’re now three layers deep, let’s not stay too long as time flows slow down here.

Drawing our example HTML paragraph to a canvas

Let’s combine all steps together.

We’ll load the HTML paragraph and dynamically create an SVG that we’ll then load to a canvas.

// Get a reference to the example paragraph at the start of the article
const exampleParagraph = document.getElementById('exampleParagraph');

// Generate SVG code with JavaScript
// Note that we wrap the paragraph HTML in a <div>
const svgCode = `
    <svg width="280" height="100" xmlns="http://www.w3.org/2000/svg">
        <foreignObject x="0" y="0" width="280" height="100">
            <style>
            p {
                margin:0;
                font-weight: normal;
                font-family: serif;
                font-size: 20px;
                line-height: 32px;
            }
            </style>
            <div xmlns="http://www.w3.org/1999/xhtml">
                ${exampleParagraph.outerHTML}
            </div>
        </foreignObject>
    </svg>`;

// Remove newlines and replace double quotes with single quotes
const svgCodeEncoded = svgCode.replace(/\n/g, '').replace(/"/g, "'");

// Dynamically create an image element
const img = document.createElement('img');

// Wait for the image to load before drawing it to the canvas
img.onload = () => {
    // Get the output canvas context
    const ctx = document.getElementById('canvasDrawImage').getContext('2d');

    // Draw the image to the canvas
    ctx.drawImage(img, 0, 0);
};

// Load our SVG to the image
img.src = `data:image/svg+xml,${svgCodeEncoded}`;

And there we go!

The result might appear a bit blurry on high res displays. To change that we can draw the text to a higher resolution canvas and then scale down the canvas with CSS.

To use this in production you would probably rewrite this logic to a function. There are some additional caveats to keep in mind.

In the example we’re using basic characters only, we have to correctly encode all SVG content for the DataURL to work.
Any custom fonts need to be embedded in the SVG. This can be done by converting the custom font to a dataURL as well.

When done correctly this yields a very exact rendering of text. Lines are broken were you expect them to break and the resulting code is relatively small compared to writing custom line break logic that is as precise as the browser (if that’s even possible).

How To Prevent Scrolling The Page On iOS Safari 15

2021-09-28T00:00:00Z

If we show a modal on iOS we need to prevent events inside the modal from interacting with the page behind the modal. On a previous episode of “Fun with Safari” we could use preventDefault() on the "touchmove" event but on iOS 15 that no longer works. Here we go.

To make this work we need iOS to think that there is nothing to scroll.

But how do we do this?

We set the height of both the html and the body element to the window height and then set overflow on these elements to hidden so the content gets cut off.

But what does "window height" really mean. To explore this a measure is visible on the right side of the page. It'll scale with the height defined by the properties used in the examples on this page.

For now it’s set to 100px.

A height of 100vh

A vh is a viewport height unit, 1vh means 1% of the viewport height.

Great. Let’s set the measure to 100vh and observe what happens.

.measure {
    height: 100vh;
}

Nope. This is not going to work. On iOS 100vh is always the full height of the viewport, even if the footer shows.

If you’re browsing this page on iOS Safari, scroll up and down a bit to see the height stays fixed no matter of the footer is active or not.

Using -webkit-fill-available

Let’s try the -webkit-fill-available property instead.

This is a -webkit- thing, so if you’re on Firefox the measure will now snap to 0

.measure {
    height: -webkit-fill-available;
}

This will do the trick. But it results in a modal that is not filling up all available space.

-webkit-fill-available will fill the “safe” space, so it excludes the room the footer will take up if it’s active.

We want all the space.

It turns out that window.innerHeight reflects the actual available space. So what we want is this.

.measure {
    height: window.innerHeight;
}

But you and I both know that this won’t fly because window.innerHeight is a JavaScript property.

Syncing window.innerHeight

Luckily we can use CSS Custom Properties to make this tick.

.measure {
    height: var(--height);
}

Now we switch to JavaScript land where we update the custom property when the window is resized.

The 'resize' event is trigged when the iOS Safari footer changes in height, so this nicely aligns our measure with the page height.

window.addEventListener('resize', () => {
    measure.style.setProperty('--height', `${window.innerHeight}px`);
});

I know we could also “just” set measure.style.height but as we’re going to use Custom Properties for our modal in a minute so we might as well go the extra mile here.

If you’re on iOS, see if the measure scales correctly by scrolling up and down a bit.

We’re almost out of the woods. Our measure is now be the right size no matter if the iOS Safari footer is visible or not.

Now we’re going to apply this height to the html and body elements when our modal is activated. This prevents the page from scrolling.

We’ll add an is-locked class to our html element when we show the modal.

// get reference to the modal
const modal = document.querySelector('.modal');

function showModal() {
    // assign lock to html element
    document.documentElement.classList.add('is-locked');

    // open modal
    modal.classList.add('is-open');
}

function hideModal() {
    // remove lock from html element
    document.documentElement.classList.remove('is-locked');

    // close modal
    modal.classList.remove('is-open');
}

When the is-locked class is assigned we use it to set the required styles so the page cannot be scrolled.

html.is-locked,
html.is-locked body {
    /* want to fix the height to the window height */
    height: calc(var(--window-inner-height) - 1px);

    /* want to block all overflowing content */
    overflow: hidden;

    /* want to exclude padding from the height */
    box-sizing: border-box;
}

/* very basic modal styles for brevity */
.modal {
    position: fixed;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
    background: black;
    display: none;
}

.model.is-open {
    display: block;
}

Wait a minute, what is that calc() doing there?!

Let me try to explain. If the iOS Safari footer is hidden when the modal opens, iOS will reveal the footer if the user makes a vertical pan gesture, the 1px prevents this from happening.

I don’t know why, I just know that I’m so tired. 🤷‍♂️

Let’s just move on.

Now we listen for the 'resize' event to keep the --window-inner-height CSS Custom Property synced with the window.innerHeight in JavaScript land.

function syncHeight() {
    document.documentElement.style.setProperty(
        '--window-inner-height',
        `${window.innerHeight}px`
    );
}

window.addEventListener('resize', syncHeight);

To prevent iOS from hiding the footer when the modal is visible and the footer is visible we need to prevent the default action of the 'pointermove' event.

If we want to support iOS 14 we need to add 'touchmove' as well.

const modal = document.querySelector('.modal');

// helper function to run preventDefault
function preventDefault(e) {
    e.preventDefault();
}

function showModal() {
    document.documentElement.classList.add('is-locked');

    modal.classList.add('is-open');

    // block pointer events
    modal.addEventListener('pointermove', preventDefault);
}

function hideModal() {
    document.documentElement.classList.remove('is-locked');

    modal.classList.remove('is-open');

    // resume pointer events
    modal.removeEventListener('pointermove', preventDefault);
}

We’re nearly done. 🫠

Because we’re resizing the document the user scroll position is lost when the modal opens. So we need to remember that position before it opens and restore it when the modal closes.

let scrollY; // we'll store the scroll position here

const modal = document.querySelector('.modal');

function preventDefault(e) {
    e.preventDefault();
}

function showModal() {
    // remember scroll position
    scrollY = window.scrollY;

    document.documentElement.classList.add('is-locked');

    modal.classList.add('is-open');

    modal.addEventListener('pointermove', preventDefault);
}

function hideModal() {
    document.documentElement.classList.remove('is-locked');

    modal.classList.remove('is-open');

    modal.removeEventListener('pointermove', preventDefault);

    // restore scroll position
    window.scrollTo(0, scrollY);
}

There we go! 😅

Try it out on iOS Safari 15 by clicking the “Open modal” button below. It’s been tested with the address bar at the bottom of the viewport (which is the default) and at the top. We can move it to the top by tapping “aA” and then “Show Top Address Bar”.

The modal is slightly transparent on purpose so we can see that the page is scrolled to the top. We can assign the backdrop-filter: blur(20px) style to the modal root element to make this less obvious.

I sincerely hope the Apple Safari dev team will fix this mess in the next upate, but I’m not holding my breath.

Use The JavaScript EyeDropper API To Select Colors On The Web

2021-09-07T00:00:00Z

The EyeDropper API just landed in Chrome Canary. In this is a mini tutorial we’ll quickly look at how to use it in our web apps to select colors.

Let’s get to it, the API is fairly straightforward.

We create a new EyeDropper instance and can then ask it to open the eye dropper with the open method.

The open method returns a Promise that resolves when a color is selected, it rejects if the user cancels the color selection by pressing escape.

const eyeDropper = new EyeDropper();

try {
    const selectedColor = await eyeDropper.open();
    console.log(selectedColor);
    // logs: { sRGBHex: '#ff0000' }
} catch (err) {
    console.log('color selection cancelled');
}

You can test for support of EyeDropper using the following snippet, if you’re browsing with a browser that supports the EyeDropper API a button will be rendered below the code snippet.

if ('EyeDropper' in window) {
    // supported
}

There we go! Fingers crossed we can start using this in the near future.

Styling Password Fields To Get Better Dots

2021-09-06T00:00:00Z

Make the dots in a password field bigger with this basic CSS style. It’ll make it easier to see the number of dots in the field, helping both yourself and the visually impaired.

Depending the font used the dots in the password field look like this. The font-family on the field below is set to sans-serif

We can use the Verdana font to scale the dots to a more comfortable size.

input[type='password'] {
    font-family: Verdana;
}

That’s better already, now let’s separate the individual dots.

input[type='password'] {
    font-family: Verdana;
    letter-spacing: 0.125em;
}

Much better. It’s now a lot easier to see the individual dots, and the dots nicely take up space in the field.

This works on Mac Firefox / Mac Chrome / Mac Safari / Win Chrome (+Edge). Android doesn’t have Verdana so shows dots that are a bit smaller.

Create A Fade Out Overflow Effect Using CSS Mask-Image

2021-07-02T00:00:00Z

Learn how to create an overflow fade out effect using CSS mask-image. This helps indicate to the user that there’s more content to be seen. Masking is very useful when overflowing content that’s placed over an image or a non-uniform background.

Let’s take a look at the example below. When scrolling the custom scrollbar we can see that the content area overlows and the content is faded out.

Lorem Ipsum What is Lorem Ipsum?

Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book.

It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.

Where does it come from?

Contrary to popular belief, Lorem Ipsum is not simply random text. It has roots in a piece of classical Latin literature from 45 BC, making it over 2000 years old. Richard McClintock, a Latin professor at Hampden-Sydney College in Virginia, looked up one of the more obscure Latin words, consectetur, from a Lorem Ipsum passage, and going through the cites of the word in classical literature, discovered the undoubtable source.

Lorem Ipsum comes from sections 1.10.32 and 1.10.33 of "de Finibus Bonorum et Malorum" (The Extremes of Good and Evil) by Cicero, written in 45 BC. This book is a treatise on the theory of ethics, very popular during the Renaissance. The first line of Lorem Ipsum, "Lorem ipsum dolor sit amet..", comes from a line in section 1.10.32.

The HTML used for this effect is a normal block-level element that can have any kind of content.

<div class="masked-overflow">
    <p>What is Lorem Ipsum?</p>
</div>

Then using CSS we apply the mask.

.masked-overflow {
    /* scroll bar width, for use in mask calculations */
    --scrollbar-width: 8px;

    /* mask fade distance, for use in mask calculations */
    --mask-height: 32px;

    /* If content exceeds height of container, overflow! */
    overflow-y: auto;

    /* Our height limit */
    height: 300px;

    /* Need to make sure container has bottom space,
  otherwise content at the bottom is always faded out */
    padding-bottom: var(--mask-height);

    /* Keep some space between content and scrollbar */
    padding-right: 20px;

    /* The CSS mask */

    /* The content mask is a linear gradient from top to bottom */
    --mask-image-content: linear-gradient(
        to bottom,
        transparent,
        black var(--mask-height),
        black calc(100% - var(--mask-height)),
        transparent
    );

    /* Here we scale the content gradient to the width of the container 
  minus the scrollbar width. The height is the full container height */
    --mask-size-content: calc(100% - var(--scrollbar-width)) 100%;

    /* The scrollbar mask is a black pixel */
    --mask-image-scrollbar: linear-gradient(black, black);

    /* The width of our black pixel is the width of the scrollbar.
  The height is the full container height */
    --mask-size-scrollbar: var(--scrollbar-width) 100%;

    /* Apply the mask image and mask size variables */
    mask-image: var(--mask-image-content), var(--mask-image-scrollbar);
    mask-size: var(--mask-size-content), var(--mask-size-scrollbar);

    /* Position the content gradient in the top left, and the 
  scroll gradient in the top right */
    mask-position: 0 0, 100% 0;

    /* We don't repeat our mask images */
    mask-repeat: no-repeat, no-repeat;
}

Note that you should either use autoprefixer or prepend the mask properties with -moz- and -webkit- to make them work.

We need these two mask images because when a mask is applied, transparent pixels in the mask are the pixels that become masked. When applying only the content mask the scrollbar gets masked as well because the pixels behind it are transparent.

While the scrollbar still works, visually it’s not that attractive.

Our --mask-image-scrollbar paints a set of black opaque pixels behind the scroll area making the scrollbar always visible.

The custom scrollbar is created with this CSS, we use the current text color as scrollbar color.

/* Firefox */
.masked-overflow {
    scrollbar-width: thin; /* can also be normal, or none, to not render scrollbar */
    scrollbar-color: currentColor transparent; /* foreground background */
}

/* Webkit / Blink */
.masked-overflow::-webkit-scrollbar {
    width: var(--scrollbar-width);
}

.masked-overflow::-webkit-scrollbar-thumb {
    background-color: currentColor;
    border-radius: 9999px; /* always round */
}

.masked-overflow::-webkit-scrollbar-track {
    background-color: transparent;
}

What Do HTML Elements Sound Like?

2021-07-01T00:00:00Z

A video overview of HTML elements and how they sound when being navigated with assistive technology like the screenreader VoiceOver.

What does a fieldset sound like?

A <fieldset> can be used to group similar fields together. Think radiobuttons, checkboxes, or a billing and shipping address. Use the <legend> element to describe the group.

Assistive technology can now tell what group the inner fields belong to.

Retweet “what a fieldset sounds like” and help raise accessibility awareness

Fieldsets can be nested, please show restraint as the NVDA screenreader will read out the fieldset legend for each focussed field.

On first sight, the radios might seem like a list because they are. It might be tempting to wrap them in a list element. Note that in the video above the assistive tech announces the total radio buttons and the current index without a list. If you wrap the radio buttons in a list the screenreader will announce the index and amount twice.

What does an img sound like?

The <img> element describes an image on the page. Always add the alt atrtribute. Set the alt attribute to an empty value if the image is decorative, it is decorative if it doesn’t add any additional information to the content. If it does add information to the content, add a description of the image contents to the alt attribute instead of leaving it empty.

Assistive technology will read out the alt attribute value. If the alt attribute is not set it will read out the image filename, which should be avoided at all costs.

Retweet “what an img sounds like” and help raise accessibility awareness

As you can see, CSS background images are ignored by screenreaders as they should only be used for decorative purposes, the screenreader also skips over the image element with the empty alt attribute.

What does a list sound like?

The <ul> element describes a list of items in no particular order. Use an <ol> if the list items wouldn’t make sense when re-ordered (e.g. steps in an IKEA manual, search results, article comments).

Assistive technology will inform the user of the list length, the focussed item symbol name or number, and its index.

Retweet “what a list sounds like” and help raise accessibility awareness

Sometimes when writing HTML every bit of content starts to look like a list. A good question to ask yourself to truly know if you’re looking at a list is: “Should a screenreader announce the number of items?” If that’s a yes, then you got yourself a list.

What does a br sound like?

A <br> element forces a line break but should only be used when the location of the break is semantically important, for example when formatting a poem or address.

Assistive technology will insert an appropriate pause when encountering the break.

Retweet “what a br sounds like” and help raise accessibility awareness

What does a time sound like?

Use the <time> element with a datetime attribute to describe dates, times, and durations. A time, date, or a datetime are all supported as long as supplied in ISO 8601 format, so 09:45 will work and 9:45 won’t.

Timezones don’t seem to work, when set, VoiceOver ignores the datetime attribute.

Assistive technology can now tell the user the time or duration in their native language.

Retweet “what a time sounds like” and help raise accessibility awareness

Conclusion

I hope this list of VoiceOver soundbites helps you understand how visually impaired users might be using your web product. Check back later, I plan to extend the list with additional videos regularly.

Integrating Uppy With Pintura Image Editor A JavaScript Image Editor

2021-06-22T00:00:00Z

In this tutorial we’ll integrate Uppy with Pintura Image Editor to visually optimise and compress images before they’re uploaded to the server.

Compressing and cropping images before they’re send to the server can save bandwidth, save manual cropping work, and allows the user to have more control over their own content.

Use the techniques described in this article to enable your users to edit profile pictures, photo albums, or any other imagery that they upload to your server. All while still being able to set content restrictions, like crop aspect ratio, minimum image size, and available filters.

We’ll start with the default Uppy implementation. Once we have that up and running we’ll add the Pintura Image Editor integration.

Please note that Uppy doesn’t currently support editing remote files, so Pintura won’t be able to edit images provided by Uppy Companion plugins.

Setting up Uppy

Let’s begin by adding the Uppy stylesheet and script to the page.

<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8" />
        <title>Uppy</title>

        <!-- add the Uppy styles to the head -->
        <link
            href="https://transloadit.edgly.net/releases/uppy/v1.2.0/uppy.min.css"
            rel="stylesheet"
        />
    </head>
    <body>
        <!-- add the Uppy script to right before the closing body element -->
        <script src="https://transloadit.edgly.net/releases/uppy/v1.2.0/uppy.min.js"></script>
    </body>
</html>

Now we’ll add the HTML element that will contain the Uppy instance.

Note that I’ve shortened the style and script tags to keep the code snippet readable.

<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8" />
        <title>Uppy</title>
        <link href="uppy.min.css" rel="stylesheet" />
    </head>
    <body>
        <!-- add the Uppy HTML element -->
        <div id="drag-drop-area"></div>

        <script src="uppy.min.js"></script>
    </body>
</html>

All right, let’s extend the script to load Uppy.

<body>
    <div id="drag-drop-area"></div>

    <script src="uppy.min.js"></script>

    <!-- add the Uppy script init logic -->
    <script type="module">
        var uppy = Uppy.Core()
            .use(Uppy.Dashboard, {
                inline: true,
                target: '#drag-drop-area',
            })
            .use(Uppy.Tus, { endpoint: 'https://master.tus.io/files/' });

        uppy.on('complete', (result) => {
            console.log(
                'Upload complete! We’ve uploaded these files:',
                result.successful
            );
        });
    </script>
</body>

Refresh your browser window and Uppy should now appear like shown below:

You can drop files and upload them as well, it’ll all work automagically.

Let’s move on to the Pintura Image Editor integration.

Integrating Pintura Image Editor with Uppy

To allow editing of the image we need to load Pintura when an image is dropped. We can do this by leveraging the onBeforeFileAdded function.

First however we’ll need to add the Pintura styles and scripts.

<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8" />
        <title>Uppy</title>
        <link href="uppy.min.css" rel="stylesheet" />

        <!-- Add the Pintura style tag -->
        <link href="pintura.css" rel="stylesheet" />
    </head>
    <body>
        <div id="drag-drop-area"></div>

        <script src="uppy.min.js"></script>

        <!-- Add the Pintura bridge function tag -->
        <script src="useEditorWithUppy.js"></script>

        <!-- Uppy script init logic -->
        <script type="module"></script>
    </body>
</html>

Now we’ll link up with the Uppy onBeforeFileAdded function. We’ll zoom in on the JavaScript code to make things easier to read.

The onBeforeFileAdded function allows us to validate the dropped file. If we return false the file will be rejected, if we return true, it will be added to the list. We need to edit the file and then add the result of the user edit to the list of files.

It’s the best location to integrate our image editing flow.

Let’s set up the script so it prevents files from being added.

<script type="module">
    // initialise Uppy
    var uppy = Uppy.Core({
        onBeforeFileAdded: function (file) {
            // prevent the file from being added
            return false;
        },
    })
        .use(Uppy.Dashboard, {
            inline: true,
            target: '#drag-drop-area',
        })
        .use(Uppy.Tus, { endpoint: 'https://master.tus.io/files/' });
</script>

Now we need to edit the file we just rejected with Pintura. We’ll add the useEditorWithUppy bridge and load pintura.

// import the function to open the editor
import { openDefaultEditor } from './pintura/pintura.js';

// initialise Uppy
var uppy = Uppy.Core({
  onBeforeFileAdded: useEditorWithUppy({
    // Method used to create Pintura Image Editor
    openDefaultEditor,

    // The editor options
    {
      imageCropAspectRatio: 1,
    },

    // Reference to Uppy addFile API
    () => uppy.addFile
  }),
})
  .use(Uppy.Dashboard, {
    inline: true,
    target: "#drag-drop-area",
  })
  .use(Uppy.Tus, { endpoint: "https://master.tus.io/files/" });

You can now use the Uppy file upload library together with Pintura to handle image uploads.

See the results below. Please note that this animation shows version 6 of the editor.

Find out more about Pintura Image Editor on the product site

If you’re using DropZoneJS you might also be interested in Integrating DropzoneJS with a JavaScript Image Cropper to Optimise Image Uploads

Resize Images Proportionally While Keeping The Aspect Ratio

2021-04-22T00:00:00Z

Sometimes images are just too big to display on the web page. We don’t need JavaScript to fix this. We can resize images proportionally with HTML image tags or CSS background styles. Let’s look at the different options we have to size images while keeping their aspect ratio in check.

Resizing HTML image tags

Our first choice is to set only one size property, either width or height, the browser will automatically calculate the size of the other edge.

Imagine we have a cat picture with an aspect ratio of 4:3, in other words, it’s dimensions are 4032 × 3024, that’s a lot of cat.

If we want it to show a bit smaller we can set the width to 240, the browser will then automatically calculate the height to be 180.

<img src="cat.jpeg" width="240" />

There’s a caveat. Images aren’t immediately available.

The browser will render the page, wait for the image source to load, and then update the height of the image element. This will most likely cause the browser to render the page twice, because after the height of the image is updated all items below the image are pushed down.

This is bad news for your page performance.

Best to set the intended size so the browser can reserve space.

<img src="cat.jpeg" width="240" height="180" />

But what if we don’t know the aspect ratio of the image and we get a square cat picture? Won’t our cat be squished? Yes, yes it would, poor cat.

But fear not, we can fix this with CSS.

img {
    object-fit: contain;
}

Pass cover instead of contain to tell the browser to fill the entire image tag with cat pixels.

img {
    object-fit: cover;
}

What if our image needs to be limited to the width of a parent element? In that situation we can use CSS max-width or width to fit the image.

Use max-width: 100% to limit the size but allow smaller image sizes, use width: 100% to always scale the image to fit the parent container width.

<div>
    <img src="cat.jpeg" width="240" height="180" />
</div>

div {
    width: 240px;
    border: 1px solid pink;
}

img {
    max-width: 100%;
    object-fit: contain;
}

We can further use CSS to fix the aspect ratio of the image, learn more about presenting images in a specific aspect ratio.

Resizing CSS background images

By default a background-image will be repeated over the background of an element if it’s smaller, if it’s bigger it won’t be scaled but parts of the image won’t be visible. In the example below, the bottom and right part of our cat aren’t rendered.

<div style="width:200px; height:200px;"></div>

div {
    background: url('cat.jpeg') no-repeat;
    border: 1px solid pink;
}

We can fix this by setting the background-size property. To fit the image inside the element we use the contain value. The browser will fit the image inside the element bounds and scale it proportionally.

<div style="width:200px; height:200px;"></div>

div {
    background: url('cat.jpeg') no-repeat;
    background-size: contain; /* scales the image */
    background-position: center; /* centers the image */
    border: 1px solid pink;
}

Similar to object-fit we can also use the cover value to tell the browser to cover the element with cat pixels. As you can see below, this will cause it to scale down just enough to fit the vertical space, now only the right side of our cat is cropped.

<div style="width:200px; height:200px;"></div>

div {
    background: url('cat.jpeg') no-repeat;
    background-size: cover;
    border: 1px solid pink;
}

We can also supply a singular width value to the background-size property. Similar to the img element, the height will be automatically calculated.

<div style="width:200px; height:200px;"></div>

div {
    background: url('cat.jpeg') no-repeat;
    background-size: 200px;
    border: 1px solid pink;
}

That’s it!

Edit Images Before Uploading Them To Your WordPress Media Library

2021-03-23T00:00:00Z

In this short tutorial we’ll use a custom <pintura-input> element to add image editing and uploading to any WordPress website front-end.

Let’s take a look below at what we’re building. Select a file to start editing, click done and the file will be uploaded. The image edit functionality and custom field are provided by Pintura Image Editor.

For privacy reasons the file upload in this demo is simulated.

Let’s get started!

To help our visitors edit and upload images we need to make three small changes to our website.

Load the pintura, and pintura-input styles and scripts.
Copy a PHP script to handle the upload to the media library.
Add the pintura-input element to the page we want to upload from.

We’ll go over them step by step.

#1 Loading the pintura, and pintura-input styles and scripts

First we download the files, we need to download Pintura and download the Pintura Input component files.

Let’s navigate to our themes functions.php file. We can find it in the admin menu by clicking Appearance -> Theme Editor -> Theme Functions.

Alternatively we can open the theme folder and find the functions.php file using an FTP client.

We’ll start by adding the following two lines to the functions.php file of the theme. This will load the editor styles and scripts. We can add the snippet to the top of the file.

Note that this setup assumes that:

pintura.css and pintura-iife.js are located in theme-folder-name/pintura/
pinturainput-iife.js is located in theme-folder-name/pintura-input/

// This function will load the pintura scripts
function pintura_enqueue() {

    // This loads the Pintura styles
    wp_enqueue_style(
        'pintura-input-style',
        get_template_directory_uri() . '/pintura/pintura.css',
        array(), false
    );

    // This loads the Pintura scripts
    wp_enqueue_script(
        'pintura-input-script',
        get_template_directory_uri() . '/pintura/pintura-iife.js',
        array(), false, true
    );

    // This loads the Pintura Input custom element
    wp_enqueue_script(
        'pintura-input-script',
        get_template_directory_uri() . '/pintura-input/pinturainput-iife.js',
        array(), false, true
    );
}

// This action will call the Pintura script loader on the front-end
add_action('wp_enqueue_scripts', 'pintura_enqueue')

We’ll need to make some more changes to the functions.php file in the next step.

#2 Set up the PHP script that handles the image upload

Copy the PHP snippet below and paste it just below the code we added in step 1.

This code will handle the image upload and move uploaded images to the WordPress media library.

Note that in this example "my_field" is the name of the file input field being handled, we’ll use it again in step #3. If your field is named differently, or you want to use a different name, make sure to change it everywhere.

add_action( 'wp_ajax_image_upload', 'handle_input_image' );
add_action( 'wp_ajax_nopriv_image_upload', 'handle_input_image' );

function handle_input_image() {

    // Allow this image to be uploaded?
    if (!wp_verify_nonce( $_POST['nonce'], 'my_field' )) {

        // Log error message to console so we know what's up
        echo 'Image upload not allowed';

        // Respond with a 403 forbidden error
        http_response_code(403);
        die();
    }

    // These files need to be included to upload the image
    require_once(ABSPATH . 'wp-admin/includes/image.php');
    require_once(ABSPATH . 'wp-admin/includes/file.php');
    require_once(ABSPATH . 'wp-admin/includes/media.php');

    // Let WordPress handle the upload
    $image_id = media_handle_upload( 'my_field', 0 );

    // Test if upload succeeded
    if (is_wp_error($image_id)) {

        // Log error message to console so we know what's up
        echo $image_id->get_error_message();

        // Respond with a 500 error
        http_response_code(500);
        die();
    }

    // Finished upload, return the image id
    echo $image_id;
    http_response_code(200);
    die();
}

#3 Add the pintura-input HTML element

We’re nearly done, all that is left is adding the pintura-input HTML element to a page.

We’ll open the webpage we want to allow visitors of our website to upload from and add the following HTML to the page.

<pintura-input
  name="my_field"
  store="<?php echo admin_url('wp_ajax.php') ?>"
  post-action="image_upload"
  post-nonce="<?php echo wp_create_nonce('my_field') ?>">
</pintura-input>

If we can’t find wp_ajax.php we can use admin_ajax.php instead.

The image_upload name in the post-action attribute links our field to the add_action hooks both ending with image_upload.

The name of the field my_field is also used in the PHP code to know which field to look for in the sent data.

Finally the post-nonce is used to check if the data was sent in a secure manner.

After refreshing the webpage we’re ready to upload our first image!

If you want to change the behaviour of the editor you can find more information on the pintura-input element here.

TypeScript Interface Merging And Extending Modules

2021-03-22T00:00:00Z

FilePond is split up in a core library and a wide range of plugins. The plugins add properties to the core. But how do we extend the core TypeScript Interface to show the plugin properties?

Let’s take a look.

We have a core library, in this case FilePond, and we have a plugin that dynamically adds a property called allowFilePoster to the core instance.

import { create } from 'filepond';

import FilePondPluginFilePoster from 'filepond-plugin-file-poster';

const instance = create(inputElement, {
    allowFilePoster: true, // error!
});

If the 'filepond-plugin-file-poster' module doesn’t extend the core interface, TypeScript will throw this error:

/* Property 'allowFilePoster' does not exist on type 'FilePond'. ts(2339) */

And rightly so, because this property isn’t available on the core interface.

To quickly work around this we could define the property in the core interface, but that would make third-party plugin development impossible as they wouldn’t have access to the core interface.

Instead we need a way to extend the core interface with additional declarations.

Searching “extend interface” doesn’t yield a lot of answers as extending interfaces is also possible with TypeScript but it’s not what we want, we want to add declarations to an existing interface.

Adding declarations to an interface

The FilePond module exports the FilePondOptions interface, it’s located in the types/index.d.ts folder of the repository.

export interface FilePondOptions {
    /** Enable or disable drag n’ drop */
    allowBrowse?: boolean;

    // Other FilePond core options here...
}

In the plugin repository types we set things up like shown below.

We import 'filepond' and then, declare a module under the same name, and then extend the core FilePondOptions interface.

// @ts-ignore
import { FilePondOptions } from "filepond";

declare module "filepond" {
  export interface FilePondOptions {
    /** Enable or disable file poster */
    allowFilePoster?: boolean;

    // Other FilePond plugin options here...
  }
}

Note that in my development environment I had to add the @ts-ignore statement to prevent it from throwing the following warning.

/* 'FilePondOptions' is declared but its value is never read. ts(6133) */

Now if both the core and the plugin modules have been imported, the allowFilePoster property is recognized on the FilePond instance and we can set it without it throwing an error.

You can read more on this in the official TypeScript documentation in this entry about extending modules.

Convert A Blob To A File Using JavaScript

2021-03-10T00:00:00Z

Sometimes you get a Blob object when instead you would like to have a File. For example, when you use blob() on a fetch response object. In this quick tutorial we’ll explore how to turn a Blob into a File.

Fetch

The script below converts a fetch response into a Blob.

fetch('./image.jpeg')
    .then((res) => res.blob())
    .then((myBlob) => {
        console.log(myBlob);
        // logs: Blob { size: 1024, type: "image/jpeg" }
    });

But what if we want a File?

The main difference between a Blob and a File is that the File has a name and lastModified property, it inherits all it’s other properties from Blob.

We can take two routes, either we add these two properties to the Blob to make it seem like a File. Or we create an actual File instance.

Making a Blob quack like a File

Let’s add the two properties to our Blob instance (the one from our fetch request above).

myBlob.name = 'image.jpeg';
myBlob.lastModified = new Date();

Our Blob now seems like a File but it’s not a real File, we can easily check this:

console.log(myBlob instanceof File);
// logs: false

console.log(myBlob);
// logs: Blob { name: "image.jpeg", lastModified: ..., size: 1024, type: "image/jpeg" }

This might cause a problem if we use this with a third-party script which requires an actual File object.

Creating an actual File

This is the better approach, it’ll give us an actual File object.

const myFile = new File([myBlob], 'image.jpeg', {
    type: myBlob.type,
});

console.log(myFile);
// logs: File { name: "image.jpeg", lastModified: ..., size: 1024, type: "image/jpeg" }

Now when we check the instance it’ll be a File.

console.log(myFile instanceof File);
// logs: true

But, as it inherits from Blob it’ll also be a Blob.

console.log(myFile instanceof Blob);
// logs: true

Why did we discuss the quack likes a duck method? Because IE11 doesn’t support the File constructor so if you still need to support Internet Explorer, that’s the way to go.

How To Prompt The User To Download A File

2021-02-12T00:00:00Z

Sometimes we just want to download an image file instead of opening it in the browser. For these situations we can use the download attribute. In this article we’ll learn how to use it and how we can automate its behavior with JavaScript.

The download attribute tells the browser to download a link target when it’s clicked.

<a href="/media/cat.jpeg" download>cat.jpeg</a>

Try it here: cat.jpeg

We can also supply the name of the file by setting the value of the download attribute, in this example we set it to 'my-cat.jpeg'.

<a href="/media/cat.jpeg" download="my-cat.jpeg">cat.jpeg</a>

Try it here: cat.jpeg

Automating the download

Suppose we’ve generated a file in the browser, how can we serve that file to the user without having to ask the user to click a link.

JavaScript to the rescue!

function downloadFile(file) {
    // Create a link and set the URL using `createObjectURL`
    const link = document.createElement('a');
    link.style.display = 'none';
    link.href = URL.createObjectURL(file);
    link.download = file.name;

    // It needs to be added to the DOM so it can be clicked
    document.body.appendChild(link);
    link.click();

    // To make this work on Firefox we need to wait
    // a little while before removing it.
    setTimeout(() => {
        URL.revokeObjectURL(link.href);
        link.parentNode.removeChild(link);
    }, 0);
}

We can use it like this:

// Dynamically create a File
const myFile = new File([`${new Date()}: Meow!`], 'my-cat.txt');

// Download it using our function
downloadFile(myFile);

Click on the button below to give it a go.

Convert A File To A Base64 String Or DataURL Using JavaScript

2021-01-18T00:00:00Z

Converting JavaScript file objects or blobs to Base64 strings can be useful. For example when we can only send string based data to the server. In this tutorial we’ll explore how to use JavaScript to generate a Base64 string and a DataURL from a file object.

In both examples we’ll use a file obtained from a file input field.

Encoding a File as a DataURL

We use FileReader to convert the file object to a dataUR this is done by using the readAsDataURL method.

<input type="file" />

<script>
    // Get a reference to the file input
    const fileInput = document.querySelector('input');

    // Listen for the change event so we can capture the file
    fileInput.addEventListener('change', (e) => {
        // Get a reference to the file
        const file = e.target.files[0];

        // Encode the file using the FileReader API
        const reader = new FileReader();
        reader.onloadend = () => {
            console.log(reader.result);
            // Logs data:<type>;base64,wL2dvYWwgbW9yZ...
        };
        reader.readAsDataURL(file);
    });
</script>

Encoding the File as a Base64 string

The snippet below creates a base64 string, it’s identical to the previous example but it uses a regular expression to remove the Data URL part.

<input type="file" />

<script>
    // Get a reference to the file input
    const fileInput = document.querySelector('input');

    // Listen for the change event so we can capture the file
    fileInput.addEventListener('change', (e) => {
        // Get a reference to the file
        const file = e.target.files[0];

        // Encode the file using the FileReader API
        const reader = new FileReader();
        reader.onloadend = () => {
            // Use a regex to remove data url part
            const base64String = reader.result
                .replace('data:', '')
                .replace(/^.+,/, '');

            console.log(base64String);
            // Logs wL2dvYWwgbW9yZ...
        };
        reader.readAsDataURL(file);
    });
</script>

Generating a URL that points to a File object

Sometimes we just want to use an File object as an image source. But how to add the file object to the <img> src attribute?

The URL.createObjectURL() method can help here.

The following code snippet will update the image source to the file that is loaded in the file input.

<input type="file" accept="image/*" />

<img src="" alt="" />

<script>
    // Get a reference to the file input
    const imageElement = document.querySelector('img');

    // Get a reference to the file input
    const fileInput = document.querySelector('input');

    // Listen for the change event so we can capture the file
    fileInput.addEventListener('change', (e) => {
        // Get a reference to the file
        const file = e.target.files[0];

        // Set file as image source
        imageElement.src = URL.createObjectURL(file);
    });
</script>

We need to make sure to revoke the URL if we no longer need the file. If we don’t this causes memory leaks.

URL.revokeObjectURL(fileUrl);

That’s it!

Applying A Circular Crop Mask To An Image

2021-01-17T00:00:00Z

Profile pictures are often masked by a circle. How can we present our images in such a circle. Lets explore two options, one where we use CSS and one where we actually mask the image data.

Applying the mask using CSS

Applying a circular mask to an image using CSS is quite straightforward. We only have to set the border-radius property and we’re done.

<style>
    img {
        border-radius: 50%;
    }
</style>

<img src="/media/cat.jpeg" alt="" />

But what if our image isn’t a square?

To prevent elliptic cats we have to make sure our image is a square.

<style>
    img {
        width: 128px;
        height: 128px;
        border-radius: 50%;
    }
</style>

<img src="/media/cat.jpeg" alt="" />

Okay, but now our cat is squished. Let’s unsquish it using CSS object-fit.

<style>
    img {
        width: 128px;
        height: 128px;
        object-fit: cover;
        border-radius: 50%;
    }
</style>

<img src="/media/cat.jpeg" alt="" />

Done!

Applying a Circular Mask using Canvas

To modify the actual image data we can use the <canvas> element and apply the circular mask to the image itself.

Let’s use a file input element and apply the mask to the added file.

<input type="file" accept="image/*" />

<canvas hidden></canvas>

<script>
    // get a reference to the file input
    const fileInput = document.querySelector('input');

    // get a reference to the output canvas
    const canvas = document.querySelector('canvas');

    // listen for the change event so we can capture the file
    fileInput.addEventListener('change', (e) => {
        // get a reference to the file
        const file = e.target.files[0];

        // let's load the image data
        const image = new Image();
        image.onload = () => {
            // use min size so we get a square
            const size = Math.min(image.naturalWidth, image.naturalHeight);

            // let's update the canvas size
            canvas.width = size;
            canvas.height = size;

            // draw image to canvas
            const ctx = canvas.getContext('2d');
            ctx.drawImage(image, 0, 0);

            // only draw image where mask is
            ctx.globalCompositeOperation = 'destination-in';

            // draw our circle mask
            ctx.fillStyle = '#000';
            ctx.beginPath();
            ctx.arc(
                size * 0.5, // x
                size * 0.5, // y
                size * 0.5, // radius
                0, // start angle
                2 * Math.PI // end angle
            );
            ctx.fill();

            // restore to default composite operation (is draw over current image)
            ctx.globalCompositeOperation = 'source-over';

            // show canvas
            canvas.hidden = false;
        };
        image.src = URL.createObjectURL(file);
    });
</script>

Try it below!

Drawing Decorative Lines With CSS

2021-01-07T00:00:00Z

In this short article we’ll explore drawing decorative lines with CSS using Pseudo Elements, Background Images, and SVG. After reading you’ll have learned a couple of interesting techniques for drawing section separators or other decorative line elements with CSS.

Pseudo elements

We can generate a pseudo-element using the ::before or ::after selectors. This adds a new child to our targeted element that we can then style as if it was a normal element.

To get the browser to render the pseudo-element we need to set the content property.

.my-element::before {
    content: "I'm a pseudo-element!";
    background: pink;
    padding: 0.25rem;
}

The result:

Now to create a decorative line we position our pseudo-element inside the element we want to draw a line in.

In the demos below I’ve centered the text and given the element a height so we can clearly see the horizontal line running behind the text, note that these properties are not shown in the example CSS.

.my-element {
    position: relative;
    z-index: 0;
}

.my-element::before {
    /* we want to draw a line, so no content needed */
    content: '';

    /* this sets the position and size of the pseudo-element */
    position: absolute;
    top: 50%;
    width: 100%;
    height: 2px;
    background-color: pink;

    /* draw behind child elements */
    z-index: -1;
}

The result:

The .my-element node

This method gives us a lot of flexibility but uses absolute positioning which requires the parent element to have relative positioning. This is because an element with position absolute is positioned relative to the first parent element found that has positioning explicitely set to relative.

This works pretty well but can cause issues when other child elements have z-indexes applied or want to be positioned relative to an element further up in the DOM tree.

We can avoid the positioning issue by using a border like this.

.my-element {
    box-shadow: inset 0 0 0 1px #777;
    color: #777;
}

.my-element::before {
    content: '';
    display: block;
    padding-top: 2.5rem;
    margin-bottom: -2.5rem;
    border-bottom: 2px solid pink;
}

The result:

The .my-element node

Still it feels a bit like a hack to create an element to draw a line and now we need to know the height of the parent element.

Background images

We can use linear-gradient, radial-gradient, and conic-gradient to “generate” background images. Combined with background-size, background-position, and background-repeat we can use these gradients to “cheat” and draw a simple line.

.my-element {
    background-image: linear-gradient(pink, pink);
    background-repeat: no-repeat;
    background-size: 100% 1px;
    background-position: 0 center;
}

The result:

The .my-element node

This is a lot cleaner already, we can make this even better by creating a separate decorative-line class and defining a couple CSS properties.

<p class="my-element decorative-line">Hello!</p>

.decorative-line {
    background-image: linear-gradient(var(--line-color), var(--line-color));
    background-repeat: no-repeat;
    background-size: 100% var(--line-height);
    background-position: 0 center;
}

.my-element {
    --line-color: pink;
    --line-height: 2px;
}

Now we can apply the decorative-line class to an element and set the --line-color and --line-height properties to style it.

We can now also fade-in and fade-out lines.

.my-element {
    background-image: linear-gradient(
        to right,
        pink,
        white 35%,
        white 65%,
        pink
    );
    background-repeat: no-repeat;
    background-size: 100% 2px;
    background-position: 0 center;
}

The result:

The .my-element node

We can still set a background color and have multiple other background images on the target element.

.my-element {
    background-color: lavenderblush;
    background-image: linear-gradient(pink, pink), linear-gradient(palevioletred, palevioletred);
    background-size: 100% 2px, 2px 100%;
    background-position: 0 center, 25% 0;
    background-repeat: no-repeat;
}

The result:

The .my-element node

SVG data URIs

We can also set background images using SVGs but unfortunately we cannot use CSS variables inside the SVG data URI.

.my-element {
    background-image: url('data:image/svg+xml,\
    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100% 100%">\
      <rect x="0" y="50%" width="100%" height="2px" fill="pink"/>\
    </svg>');
}

The result:

The .my-element node

I haven’t tested this but I suspect using SVGs is slower than linear-gradient as it requires the browser to decode and draw the SVG. nonetheless SVG is very powerful so might be the way to go if you need to draw very exotic lines.

Conclusion

There’s multiple ways we can draw decorative lines with CSS. We found pseudo elements give us a lot of flexibility but also require positioning that could introduce side effects.

Using generated background images instead can be a nice work around and doesn’t introduce the positioning problems that pseudo-elements can cause.

SVGs are also a nice alternative but can’t be styled with CSS Custom Properties and might be a bit slower than linear gradients.

Pintura Image Editor Lifetime Hobby License Giveaway

2021-01-06T00:00:00Z

I want to start 2021 with a positive vibe so I’m joining Zell Liews JavaScript course giveaway. I’m giving away 5 Lifetime Pintura Image Editor Hobby licenses. The usual price for the Hobby license subscription is $149 yearly.

Not familiar with Pintura Image Editor? You can find a demo here

Zell is giving away 10 copies of his fantastic Learn JavaScript course, this course normally costs $495.

How to join the Pintura Image Editor giveaway?

Subscribe to the PQINA newsletter below to enter the contest. I’ll randomly pick the 5 winners from the subscriber list on Wednesday, 13 January, 2021.

The giveaway has ended.

To be notified about giveaways and product updates please subscribe to the newsletter below and follow me on Twitter.

How to join the Learn JavaScript giveaway?

Navigate to the giveaway announcement page and subscribe to Zells newsletter.

Applying Watermarks To Images With FilePond

2020-09-16T00:00:00Z

Watermarking photos can be a tedious task. In this quick tutorial we’ll use FilePond and the FilePond Image Transform Plugin to automatically add watermarks to images. FilePond is free and is compatible with most popular frameworks, you can use the result of this tutorial in your React, Vue, Svelte, Angular, or jQuery projects.

If you’re in a rush and want to skip to the result, you can play with the demo on Codesandbox.

Installation

Let’s get started by installing FilePond. We’ll go with NPM. If you want to use Yarn that’s fine as well. If you’re not familiar with NPM you can also manually download and reference the FilePond library files.

If you want to use NPM but you’re not familiar with NPM, you can find more info on NPM here.

In this tutorial we’ll use the plain JavaScript version of FilePond. If you’re using a client-side framework you can find the required code on each FilePond framework adapter GitHub repository, the links can be found in the intro paragraph.

In your project folder, run the following to install FilePond as a dependency.

npm i filepond --save

Since we’re also going to use the Image Transform, Image Preview, and File Metadata plugins we’ll add those as well.

npm i filepond-plugin-image-transform filepond-plugin-image-preview filepond-plugin-file-metadata --save

Setting up FilePond

Okay, our dependencies are ready, let’s set up FilePond.

We add a file input element to the page and we set the multiple attribute so it can handle more than one file.

<input type="file" multiple />

In your JavaScript file import the FilePond styles and scripts.

import 'filepond/dist/filepond.min.css';
import * as FilePond from 'filepond';

Let’s turn the file input into a FilePond element. We can do this by calling the create method and supplying the input element.

FilePond.create(document.querySelector('input[type="file"]'));

FilePond is now ready. You should see a drop area similar to the one shown below.

This is a live demo so you can add files to it.

Please note that for privacy reasons demos on this page don’t upload anything.

It doesn’t yet show image previews or apply watermarks, that’s what we need the plugins for, let’s add them.

Adding plugins

Let’s get back to JavaScript.

We can use the registerPlugin method to add plugins to FilePond.

Our code snippet now looks like this:

// Import FilePond and its styles
import 'filepond/dist/filepond.min.css';
import * as FilePond from 'filepond';

// Import the FilePond plugins
import 'filepond-plugin-image-preview/dist/filepond-plugin-image-preview.min.css';
import FilePondPluginImagePreview from 'filepond-plugin-image-preview';
import FilePondPluginImageTransform from 'filepond-plugin-image-transform';
import FilePondPluginFileMetadata from 'filepond-plugin-file-metadata';

// Register the plugins with FilePond, so
// FilePond knows they're available
FilePond.registerPlugin(
    FilePondPluginImagePreview,
    FilePondPluginImageTransform,
    FilePondPluginFileMetadata
);

The plugins are now loaded and registered.

The Image Transform and File Metadata plugin won’t do anything yet. If we now add an image file to FilePond the preview plugin shows the image in the drop area.

For the final step, let’s add the watermark.

Setting up our Watermark

The watermark is added to the image by the Image Transform plugin, the watermark instructions are supplied by the File Metadata plugin. The File Metadata plugin automatically adds additional information to files loaded by FilePond. This information can be used after uploading or can be used by other plugins.

We can configure our watermark using markup elements. This markup is usually defined by Pintura Image Editor (an image editor plugin for FilePond) but FilePond can also render it.

Since we only need to update the FilePond.create method, we’ll skip over the imports.

FilePond.create(document.querySelector('input[type="file"]'), {
    // This property describes the metadata object that will be added to each file
    fileMetadataObject: {
        // The `markup` property is how we define our watermark
        markup: [
            // We'll draw a 60ox rectangle aligned with
            // the bottom of the image
            [
                'rect',
                {
                    left: 0,
                    right: 0,
                    bottom: 0,
                    height: '60px',
                    backgroundColor: 'rgba(0,0,0,.5)',
                },
            ],
            // Then we'll draw an image in the bottom right,
            // in this case the FilePond logo
            [
                'image',
                {
                    right: '10px',
                    bottom: '10px',
                    width: '128px',
                    height: '34px',
                    src: 'filepond-logo.svg',
                    fit: 'contain',
                },
            ],
        ],
    },
});

Let’s refresh our page, when dropping in image you can now see the watermark rendered on top of the image in the preview.

We’ll add the onpreparefile callback to get the output of the image transform action so we can see the actual resulting file.

FilePond.create(document.querySelector('input[type="file"]'), {
    // onpreparefile is called when the image transform plugin
    // has transformed an image, in this demo we use it to
    // show the result of the file transformation
    onpreparefile: (file, output) => {
        const result = new Image();
        result.src = URL.createObjectURL(output);
        document.body.appendChild(result);
    },

    // The `fileMetadataObject` property describes the metadata object
    // that will be added to each file
    fileMetadataObject: {
        // The `markup` property is how we define our watermark
        markup: [
            // We'll draw a 60ox rectangle aligned with
            // the bottom of the image
            [
                'rect',
                {
                    left: 0,
                    right: 0,
                    bottom: 0,
                    height: '60px',
                    backgroundColor: 'rgba(0,0,0,.5)',
                },
            ],
            // Then we'll draw an image in the bottom right,
            // in this case the FilePond logo
            [
                'image',
                {
                    right: '10px',
                    bottom: '10px',
                    width: '128px',
                    height: '34px',
                    src: 'filepond-logo.svg',
                    fit: 'contain',
                },
            ],
        ],
    },
});

When we add an image to FilePond, it will load the image, transform the image data with the watermark, and then add the resulting image to the page.

Play with the demo on Codesandbox

In a real life project we probably want to upload our file somewhere.

We can do this by setting the server property. If we set it to a URL, FilePond will automatically try to POST the image data to the server located at the URL.

FilePond.create(document.querySelector('input[type="file"]'), {
    // FilePond will POST files
    // to https://website/my-server-location/
    server: './my-server-location/',

    // Our other properties here
    // ...
});

That’s it, we’re done!

FilePond will now automatically push dropped files to our server.

Conclusion

We installed FilePond and set it up with the required plugins to render watermarks to images. We learned a tiny bit about using Pintura markup to define our watermarks and how to preview our resulting image in the browser. Finallly we quickly looked at how to upload images to our server.

Cross-Browser Alignment Of The Canvas FillText Draw Call

2020-08-11T00:00:00Z

If we use the HTML5 canvas fillText API and compare output from various browsers we see that the draw offset differs slightly. In this quick tutorial we’ll use a snippet to determine this offset and then correct the draw position.

Differences

The article banner is just an impression, but reality is not far off. We can see the actual difference in draw offset below, it’s just a few pixels, but it’s there.

When drawing image data on the client, like for example with Pintura Image Editor, we want every browser to deliver the same output.

Solution

We can solve this issue by drawing an “F” character to a canvas element and then looking for the first horizontal pixel and the first vertical pixel where it was drawn.

Let’s draw a big “F”. A size of 100px should suffice. We want to align our text from the top, so we set textBaseline top "top".

// create the canvas
const canvas = document.createElement('canvas');
canvas.width = 32;
canvas.height = 32;

// do the drawing
const ctx = canvas.getContext('2d');
ctx.font = `100px sans-serif`;
ctx.fillStyle = '#fff'; // color of our F
ctx.textBaseline = 'top'; // alignment
ctx.fillText('F', 0, 0); // finally draw the F

This will draw the “F” in the top left corner. We don’t need to know everything about this “F”. We’re only interested in the top and left pixels, that’s why our canvas is so small. See below for the result.

Now we need to find out where it was drawn. We’ll use the canvas getImageData method to get an array of pixel values to work with. Each index in the array represents a color value. A pixel consists of 4 colors, as our canvas is 32 pixels width, each “line” of the image consist of 4 * 32 indexes.

We’ll traverse the image vertically along the right most edge, and horizontally along the bottom. That should result in us bumping into our “F”.

// get pixel data so we can find the white pixels
const data = ctx.getImageData(0, 0, 32, 32).data;

// "pixel" position p in data
let p;

// find x offset (bottom row of pixels)
let from = data.length - 32 * 4;

// increase by 4 to step through the data per pixel instead of per color value
for (p = from; p < data.length; p += 4) {
    // stop when we find a value other than 0
    if (data[p]) break;
}

// calculate the x offset based on the current pixel
const x = (p - from) / 4;

// find y offset (right column of pixels)
from = 31 * 4;
for (p = from; p < data.length; p += 32 * 4) {
    if (data[p]) break;
}

// calculate the y offset based on the current pixel
const y = (p - from) / (32 * 4);

// log the position to the console (it's there, go take a look)
console.log(x, y);

Now we have the browser offset based on a 100px font size. We can convert this to another font size by multiplying our font size by 0.01 and then multiplying by our browser offset.

We’ll further invert the browser offset to compensate for the discrepancy among browsers.

Our compensated font offset for a 16px font:

const xOffset = -x * (16 * 0.01);
const yOffset = -y * (16 * 0.01);

If we use these offsets in our fillText function it’ll render the text at the correct position on each browser.

To prevent text from being drawn too far to the left we can set a default offset. A value like { x: 8, y: 4 } should be fine.

const xOffset = -x * (16 * 0.01) + 8;
const yOffset = -y * (16 * 0.01) + 4;

The uncorrected output, this should (shouldn’t but that’s reality) be different for each browser:

With correction applied, the image below should the same on every browser:

Conclusion

By measuring the actual draw position of each browser we can determine a new position to draw to and align text positions accross multiple browsers. Note that so far this has been tested on Safari, Chrome, and Firefox, there are other browsers out there that might yield different results.

Blocking Navigation Gestures On iOS Safari

2020-06-10T00:00:00Z

iOS Safari 13.4+ allows us to block back and forward navigation gestures. Super useful for media galleries and image croppers where users interact with elements on the side of the viewport and most likely don’t want to navigate to another page. Let’s take a minute and look at the code snippet.

The only thing we need to do is prevent the default action of the "touchstart" event. We can do this with the preventDefault() method.

<div style="height:100px">Our element that prevents navigation</div>

<script>
    const element = document.querySelector('div');

    element.addEventListener('touchstart', (e) => {
        // prevent swipe to navigate gesture
        e.preventDefault();
    });
</script>

Open this article on iOS 13.4+ and try it out with the element below.

This element prevents navigation, swipe from left to right from the edge of the screen, nothing will happen.

A demo on iOS

We do need to check if the "touchstart" event originated near the edge of the viewport, if we don’t the user won’t be able to scroll the view, we can do this by checking if pageX is below or above a certain value.

<div style="height:100px">Our element that prevents navigation</div>

<script>
    const element = document.querySelector('div');

    element.addEventListener('touchstart', (e) => {
        // is not near edge of view, exit
        if (e.pageX > 20 && e.pageX < window.innerWidth - 20) return;

        // prevent swipe to navigate back gesture
        e.preventDefault();
    });
</script>

That’s it!

We can now prevent users from accidentally navigating to another page. With great power comes great responsibility. We don’t want to frustrate users, so only use this where it makes sense, for example in a full width swipeable image gallery or when users interact with controls near the edge of the screen.

Rename A File With JavaScript In The Browser

2020-04-14T00:00:00Z

A super concise tutorial on using JavaScript to rename files in the browser. We’ll quickly cover how to update a file object and read its contents. Let’s get started!

Updating the File Object

Let’s create a new file using the File constructor, we’ll then rename this file in a couple seconds.

const myFile = new File(['hello-world'], 'my-file.txt');

Time to rename our file…

myFile.name = 'my-file-final-1-really.txt';

console.log(newFile);
// Browser logs: File {name: "my-file.txt", …}

Nope, didn’t work. Turns out we can’t update the name property of a file.

To rename a file we have to create a new file and pass our new name to the File constructor.

const myRenamedFile = new File([myFile], 'my-file-final-1-really.txt');

console.log(myRenamedFile);
// Browser logs: File {name: "my-file-final-1-really.txt", …}

To check if the file contents is the same we can read our file using the FileReader API.

const myReader = new FileReader();
myReader.readAsText(myRenamedFile);
myReader.onload = () => console.log(myReader.result);
// Browser logs: "hello-world"

Great, it has the same contents. ☀️

Surprise, this doesn’t work on Internet Explorer 11. ⛈

We can work around the age of IE11 by creating a Blob instead of a file object. Let’s create a tiny helper function that safely does this for us.

const createFile = (bits, name) => {
    try {
        // If this call fails, we go for Blob
        return new File(bits, name);
    } catch (e) {
        // If we reach this point a new File could not be constructed
        var myBlob = new Blob(bits);
        myBlob.lastModified = new Date();
        myBlob.name = name;
        return myBlob;
    }
};

Now we can safely create files like this:

const mySafeFile = createFile(['hello-world'], 'my-file.txt');

console.log(mySafeFile);
// Modern browser logs: File {name: "my-file.txt", …}
// Internet Explorer logs: Blob {name: "my-file.txt", …}

Yay! 🎉

Note that the File constructor also takes a third “options” argument, this can contain the type of the file and the lastModified date of the file.

Let’s update our createFile function so it also supports the “options” argument.

const createFile = (bits, name, options) => {
    try {
        // If this fails, we go for Blob
        return new File(bits, name, options);
    } catch (e) {
        // If we're here a new File could not be constructed
        var myBlob = new Blob(bits, options || {});
        myBlob.lastModified = new Date();
        myBlob.name = name;
        return myBlob;
    }
};

Now we can create an actual plain/text file.

const myTextFile = createFile(['hello-world'], 'my-file.txt', {
    type: 'plain/text',
});

A small caveat. Our files can now be of type Blob or File. When using the instanceof operator to test for types it’s best to test for Blob.

The following will be true on modern browsers but false on browsers that don’t support the File constructor (like Internet Explorer 11).

const testFile = createFile(['hello-world'], 'my-test.txt');
console.log(testFile instanceof File);
// Modern browser logs: true
// Internet Explorer logs: false

Testing for Blob instead of File will return the correct result on all browsers as File is a subclass of Blob.

const testFile = createFile(['hello-world'], 'my-test.txt');
console.log(testFile instanceof Blob);
// Modern browser logs: true
// Internet Explorer logs: true

That’s it!

Conclusion

We learned that updating a file object is not possible but that we can easily copy the contents of a file to a new file and give our new file a name.

To verify that the contents of the file was actually copied we took a quick look using the FileReader API.

Finally to help with cross browser compatibility we created a tiny function that can create a “File” object on all relevant browsers, “relevant” being relative.

Flipping Images Horizontally Or Vertically With CSS And JavaScript

2020-01-29T00:00:00Z

In this 3 minute article we’ll look at flipping images horizontally and vertically using CSS and JavaScript. We’ll explore how to flip an img element, a background-image, or flip the actual ImageData using a canvas element.

Flipping an Image Element

We can flip the img element using the CSS transform property. We can do so using the scaleX and scaleY transforms.

Our image:

<img src="/media/tulips.jpg" alt="" />

The CSS to flip it.

img {
    /* flip horizontally */
    transform: scaleX(-1);
}

img {
    /* flip vertically */
    transform: scaleY(-1);
}

img {
    /* flip both */
    transform: scale(-1, -1);
}

original

scaleX(-1)

scaleY(-1)

scale(-1, -1)

Alternatively you can use rotateX and rotateY

img {
    /* flip horizontally */
    transform: rotateY(180deg);
}

img {
    /* flip vertically */
    transform: rotateX(180deg);
}

img {
    /* flip both */
    transform: rotateX(180deg) rotateY(180deg);
}

original

rotateY(180deg)

rotateX(180deg)

rotateX(180deg)
rotateY(180deg)

The rotation transform is also a nice choice for when you want to animate the flip.

scaleX

rotateY

Note that I’ve added a slight perspective to the transform chain. Without the perspective transform the rotateY animation would be just as flat as the scaleX animation. I’ve added it to the scaleX animation as well to show that it doesn’t make a difference.

@keyframes flip-with-scale {
    0% {
        transform: perspective(400px) scaleX(1);
    }

    100% {
        transform: perspective(400px) scaleX(-1);
    }
}

@keyframes flip-with-rotate {
    0% {
        transform: perspective(400px) rotateY(0);
    }

    100% {
        transform: perspective(400px) rotateY(180deg);
    }
}

Flipping a Background Image

The only way (at this point in time) (and as far as I can tell) to flip a background-image is to flip the element containing the background image. But that would flip its contents as well.

<p class="tulips">
    Tulips form a genus of spring-blooming perennial herbaceous bulbiferous
    geophytes.
</p>

.tulips {
    background-image: url(/media/tulips.jpg);
    background-repeat: no-repeat;
    background-size: contain;
    padding-left: 5em;
}

.tulips-flipped {
    transform: scaleX(-1);
}

Tulips form a genus of spring-blooming perennial herbaceous bulbiferous geophytes.

original

Tulips form a genus of spring-blooming perennial herbaceous bulbiferous geophytes.

scaleX(-1)

Not great 🤷‍♂️

To work around this we can either move the background to a separate element or create a pseudo-element.

Let’s go with the pseudo-element.

.tulips {
    display: flex;
    width: 15em;
}

/* create our pseudo element */
.tulips-flipped::before {
    content: '';
    background-image: url(/media/tulips.jpg);
    background-repeat: no-repeat;
    background-size: cover;
    min-width: 5em;
}

/* flip our pseudo element */
.tulips-flipped::before {
    transform: scaleX(-1);
}

Tulips form a genus of spring-blooming perennial herbaceous bulbiferous geophytes.

original

Tulips form a genus of spring-blooming perennial herbaceous bulbiferous geophytes.

scaleX(-1)

Flipping an Image with JavaScript

The CSS flipping techniques only alter the presentation of an image, not the actual pixel data. We can flip the pixel data using the canvas element. This might be useful if for example we want to flip an image before it’s uploaded to a server.

We’ll use the image data in the image element below the code snippet, it’s simply an img tag with a class name set to image-tulips.

<img src="/media/tulips.jpg" class="image-tulips" alt="" />

Lets get a reference to the image. That allows us to load it to a canvas element for manipulation.

const inputImage = document.querySelector('.image-tulips');

// need to check if the image has already loaded
if (inputImage.complete) {
    flipImage();
}
// if not, we wait for the onload callback to fire
else {
    inputImage.onload = flipImage;
}

// this function will flip the imagedata
function flipImage() {
    // create a canvas that will present the output image
    const outputImage = document.createElement('canvas');

    // set it to the same size as the image
    outputImage.width = inputImage.naturalWidth;
    outputImage.height = inputImage.naturalHeight;

    // get the drawing context, needed to draw the new image
    const ctx = outputImage.getContext('2d');

    // scale the drawing context negatively to the left (our image is 400 pixels wide)
    // resulting change to context: 0 to 400 -> -400 to 0
    ctx.scale(-1, 1);

    // draw our image at position [-width, 0] on the canvas, we need
    // a negative offset because of the negative scale transform
    ctx.drawImage(inputImage, -outputImage.width, 0);

    // insert the output image after the input image
    inputImage.parentNode.insertBefore(
        outputImage,
        inputImage.nextElementSibling
    );
}

The above code just ran, and you can view the result below. The first image is the inputImage and the second image is the outputImage canvas element.

Conclusion

We learned three methods to flip images for various purposes. We can flip images using the CSS transform property. The scaleX and scaleY transforms work but the rotateX and rotateY transforms allow for nicer animation (if needed). We quickly explored flipping background images using pseudo elements and ended the article with manipulating the actual image data using JavaScript and a canvas element.

Animating CSS Width And Height Without The Squish Effect

2020-01-27T00:00:00Z

Being able to animate the CSS width and height properties would be super useful. Unfortunately at the moment it’s a sure-fire way to get your browser to scream in agony. In this 5 minute tutorial we’ll explore using the transform property to simulate animating the width of an element.

Don’t Animate the Width and Height Properties

Browsers don’t like it when they have to calculate the positions and sizes of elements on the webpage. Most elements in some way impact the rendering of other elements, they push siblings to another position, or when their size is changed a parent element also changes size. Modifying the dimensions of one element can therefore have lots of unforeseen consequences.

Changing the width and/or height of an element will trigger the browser to determine which other elements (children, siblings, or parents) are impacted by the change and how those elements should be updated. This process is called a reflow and it will be followed by a repaint.

These operations are very taxing on the CPU, so to keep a website fast we should avoid triggering them as much as possible.

Using Transforms Instead

To run performant animations we need to use the CSS transform or opacity properties. In this article we’ll focus on transform

The transform property instructs the GPU to make some last minute updates to the texture of an element before drawing it to the screen. These updates can for instance be rotating, moving, and scaling of an element.

You can compare the GPU texure of an element with a picture you took of the element with your mobile phone. This picture only consists of pixels, all other information about the element is gone.

The GPU only has to deal with the pixels that present the element. Because GPUs are very good at dealing with pixels, the transform operations are super fast.

This also has a downside. We can only manipulate the pixels, not the contents of the element. Remember we only have the picture of the element, all other information is gone.

You can see below how this difference impacts the border-radius property. In the transform example the radius is not redrawn (like in the width example), it is simply scaled. Redrawing would require a repaint, the GPU cannot do that, it only deals with pixels.

Original

width: 100px

transform: scaleX(.5)

.square {
    width: 200px;
    height: 200px;
    border-radius: 40px;
}

.square-resized {
    width: 100px;
}

.square-transformed {
    transform: scaleX(0.5);
}

Animating the transform property is a million times faster than animating width, height, or any of the other properties that impact layout and will trigger a reflow

But if we animate it, the result will be that weirdly stretched shape. It might be fast, but it doesn’t look great. It always reminds me of those aliens in Duke Nukem 3D getting squished by a door.

Stretched corners

9-Slice Scaling To The Rescue

Before border-radius was a thing we had to create an image for each corner and/or edge of an element to “fake” border radius. Depending on the design that could yield up to 8 images for a single element. These images would be layed out like this:

This is called the 9-slice scaling method. Tis method allows you to scale the element and stretch image 2, 4, 6, and 8, while linking 1, 3, 7, and 9 to their respective corners using absolute positioning.

Now our corners aren’t stretched when scaled, see below:

Luckily we live in a day and age where browsers support border-radius, we no longer have to rely on this technique for drawing rounded corners.

We can however use this technique to resize elements using the transform property. For the sake of brevity this example will only explore scaling the width of the element.

We’ll start with a structure like this:

Let’s apply this to our square. We’ll need one container and three child elements to represent the square left (1), center (2), and right (3) parts.

<div class="square">
    <div class="left"></div>
    <div class="center"></div>
    <div class="right"></div>
</div>

Let’s look at the CSS

/* children will be positioned relativly to this element */
.square {
    position: relative;
    height: 100px;
}

.left,
.center,
.right {
    position: absolute;
    top: 0;
    bottom: 0;
}

.left {
    background: red;
}
.center {
    background: yellow;
}
.right {
    background: blue;
}

/* we need room for a 20 pixel border radius (on one side) */
.left,
.right {
    width: 20px;
}

.left {
    border-radius: 20px 0 0 20px;
}
.right {
    border-radius: 0 20px 20px 0;
}

/* child layout definitions */
.center {
    /* center needs to be 20 pixels from the left, 
    so it doesn't overlap with the .left element */
    left: 20px;

    /* needs a width of 1 pixel, this causes 
    scaleX(60) is equal to 60 pixels */
    width: 1px;
    transform: scaleX(60);

    /* we need to scale the texture from the left side 
    for it to align correctly, default is center */
    transform-origin: left;
}

.right {
    /* we need to move the right element to align with
    the right side of the .center element 
    20px + 60px = 80px */
    transform: translateX(80px);
}

The result is a nicely colored square.

I’ve colored to element parts to make them individually recognizeable.

Now for our next trick, we can animate the .center and .right elements of the square.

.center {
    animation: center-animate 1s ease infinite alternate;
}

.right {
    animation: right-animate 1s ease infinite alternate;
}

@keyframes right-animate {
    0% {
        transform: translateX(140px);
    }
    100% {
        transform: translateX(20px);
    }
}

@keyframes center-animate {
    0% {
        transform: scaleX(120);
    }
    100% {
        transform: scaleX(0);
    }
}

Looks good to me, let’s set the background color back to black.

If you’re on Firefox, this should look great. If you’re using Safari or Chrome you might notice a slight flickering between the center and right part.

I’m not sure why this happens. It might be a problem with alpha blending OR rounding of pixels. Anyway. By slightly overlapping the center element with the right element we can resolve this render issue. We’ll make sure the element is at least 1 pixel wide and scales to 121 pixels.

@keyframes center-animate {
    0% {
        transform: scaleX(121);
    }
    100% {
        transform: scaleX(1);
    }
}

Huray! We got ourselves an animatable non-squishy square!

We could take this further and make it more flexible by moving the animation to JavaScript, creating a web component, or by using CSS variables, but for the purpose of this article this example should suffice.

View a demo of end result on CodePen

Hold Your Horses

Before you run of and start using this technique everywhere, please note that:

We’re still scaling the center square over the X axis so background images applied to the square will be stretched.
A box-shadow can be done but is a bit tricky to pull off.
The square cannot cut off other elements, as in, overflow: hidden won’t work.

Still, with a bit of trickery, you can use this to create some awesome effects. The file items and the drop area of the FilePond file upload library all use this technique to smoothly animate their height.

Pintura Image Editor used this technique on both the x and y axis to render and animate the white crop rectangle on top of the image. This has since been partly replaced with WebGL.

Conclusion

The default width and height CSS properties are (along with most other properties) not suitable for animation. They impact render performance too much because updating them triggers the browser to re-evaluate related element positions and sizes.

If we use the transform property instead we can performantly animate our square on the GPU. While super fast this also introduces some limitations because the GPU only deals with pixels.

By applying the 9-slice technique we can work around some of these limitations and create an element that we can animate in a performant way.

Presenting Images In A Specific Aspect Ratio With CSS

2019-11-04T00:00:00Z

In this 2 minute tutorial we’ll learn how to use CSS to present images in a predefined aspect ratio. Useful for when you want to show images with various dimensions in (for example) a square box without skewing them.

If you want to actually modify the image data, for example when you need to make sure images uploaded by visitors all adhere to a square aspect ratio, you can visit this tutorial on cropping images to an aspect ratio with JavaScript.

Fixed Size Images

If we need to show an image in a fixed size we can set the size using the width and height attributes. Now if we don’t know the dimensions and the aspect ratio of the image that will be shown here we can use object-fit to make sure that the image is never “skewed”.

<img width="200" height="200" src="/path/to/image.jpeg" alt="" />

img {
    object-fit: cover;
}

See the resulting image below. Note that the source image used is in landscape format and doesn’t get skewed but is “cropped” in the center.

The object-fit property accepts fill, contain, cover, none, and scale-down, the Object fit properties are described perfectly on MDN.

Flexible Size Images

To forces images that scale with their parent containers to a specific aspect ratio we have to create an element around the image. The image wrapper makes sure it always fits a certain aspect ratio, we’ll then tell the image element to fit the size of the wrapper element.

<div class="aspect-ratio-box">
    <img src="/media/desk.jpg" alt="" />
</div>

/* Position child elements relative to this element */
.aspect-ratio-box {
    position: relative;
}

/* Create a pseudo element that uses padding-bottom to take up space */
.aspect-ratio-box::after {
    display: block;
    content: '';
    /* 16:9 aspect ratio */
    padding-bottom: 56.25%;
}

/* Image is positioned absolutely relative to the parent element */
.aspect-ratio-box img {
    /* Image should match parent box size */
    position: absolute;
    left: 0;
    top: 0;
    width: 100%;
    height: 100%;
}

The result, a flexible box that adheres to a 16:9 aspect ratio.

The padding-bottom value is a percentage of the width of the container. If the container is 400 pixels wide, the resulting height will be 56.25% of 400 equals 225.

To know what padding-bottom value to use for each aspect ratio we can divide the height by the width.

Let’s look at the 16:9 aspect ratio.

9 / 16 = .5625

We need a percentage, so we multiply by 100

.5625 * 100 = 56.25

That’s it!

Future

In the near future it’ll be possible to use the CSS aspect-ratio property instead of the padding-bottom trick. At the moment browser support is still lacking.

Conclusion

We’ve learned how to present images in different aspect ratios without skewing them. Having tools to work with fixed and flexible containers should cover most use-cases you’ll encounter.

Cropping Images To A Specific Aspect Ratio With JavaScript

2019-10-31T00:00:00Z

In this 3 minute tutorial we’ll write a tiny JavaScript function that helps us crop images to various aspect ratios. Super useful for cropping photos before posting to social media timelines or uploading profile pictures as these are often required to be of a certain aspect ratio.

In this tutorial we’ll by modifying image data. For example, when a user is about to upload a an image we crop it to a certain aspect ratio. If we just want to present images in a certain aspect ratio we can use a CSS only solution.

Loading the Image Data

To get started we’ll need a source image. Let’s use a generic image URL as our source.

const imageURL = 'path/to/our/image.jpeg';

To crop an image we need to access the actual image data. We can get to this data by loading the URL to an <img> element.

const inputImage = new Image();
inputImage.src = imageURL;

Our next step is drawing the image to a <canvas>, the canvas will allow us to modify the image data. We’ll add the onload callback right before setting the src so we can capture the moment the image has loaded.

// this image will hold our source image data
const inputImage = new Image();

// we want to wait for our image to load
inputImage.onload = () => {
    // create a canvas that will present the output image
    const outputImage = document.createElement('canvas');

    // set it to the same size as the image
    outputImage.width = inputImage.naturalWidth;
    outputImage.height = inputImage.naturalHeight;

    // draw our image at position 0, 0 on the canvas
    const ctx = outputImage.getContext('2d');
    ctx.drawImage(inputImage, 0, 0);

    // show both the image and the canvas
    document.body.appendChild(inputImage);
    document.body.appendChild(outputImage);
};

// start loading our image
inputImage.src = imageURL;

Running this code results in a <canvas> that is presenting the same image as the image located at our imageURL.

Cropping The Image to a Square Aspect Ratio

Now that we have gained access to the image data we can start manipulating it.

Let’s start with a square crop. A square crop has an aspect ratio of 1:1. This means each side of the output image has the same length. We can represent this numerically as an aspect ratio of 1. The aspect ratio of a 200x200 image is 1, the aspect ratio of a 400x300 image can be calculated by dividing the width and height, which equals 1.333 (400/300).

Let’s edit our code and view the results.

// the desired aspect ratio of our output image (width / height)
const outputImageAspectRatio = 1;

// this image will hold our source image data
const inputImage = new Image();

// we want to wait for our image to load
inputImage.onload = () => {
    // let's store the width and height of our image
    const inputWidth = inputImage.naturalWidth;
    const inputHeight = inputImage.naturalHeight;

    // get the aspect ratio of the input image
    const inputImageAspectRatio = inputWidth / inputHeight;

    // if it's bigger than our target aspect ratio
    let outputWidth = inputWidth;
    let outputHeight = inputHeight;
    if (inputImageAspectRatio > outputImageAspectRatio) {
        outputWidth = inputHeight * outputImageAspectRatio;
    } else if (inputImageAspectRatio < outputImageAspectRatio) {
        outputHeight = inputWidth / outputImageAspectRatio;
    }

    // create a canvas that will present the output image
    const outputImage = document.createElement('canvas');

    // set it to the same size as the image
    outputImage.width = outputWidth;
    outputImage.height = outputHeight;

    // draw our image at position 0, 0 on the canvas
    const ctx = outputImage.getContext('2d');
    ctx.drawImage(inputImage, 0, 0);

    // show both the image and the canvas
    document.body.appendChild(inputImage);
    document.body.appendChild(outputImage);
};

// start loading our image
inputImage.src = imageURL;

The result is a square image, great! But let’s take a closer look. It seems our crop is not positioned in the center of the input image. This is because we have not update the drawImage call. The drawImage call takes 3 (or more) arguments, the inputImage, and the x and y position to draw the image at.

Our input image is still drawn at location 0, 0 we need to adjust this so we get a center crop instead of a top left crop.

To do this we need to move the image slightly to the left. Suppose our input image is 400 pixels wide and our output image is 300 pixels wide, to center it we’d need to move the input image 50 pixels to the left (negative 50 pixels). -50 pixels is 300 minus 400 divided by 2. This results in the following code snippet.

const outputX = (outputWidth - inputWidth) * .5

Let’s update the code snippet, we can use the same code for both the x and the y offset.

// the desired aspect ratio of our output image (width / height)
const outputImageAspectRatio = 1;

// this image will hold our source image data
const inputImage = new Image();

// we want to wait for our image to load
inputImage.onload = () => {
    // let's store the width and height of our image
    const inputWidth = inputImage.naturalWidth;
    const inputHeight = inputImage.naturalHeight;

    // get the aspect ratio of the input image
    const inputImageAspectRatio = inputWidth / inputHeight;

    // if it's bigger than our target aspect ratio
    let outputWidth = inputWidth;
    let outputHeight = inputHeight;
    if (inputImageAspectRatio > outputImageAspectRatio) {
        outputWidth = inputHeight * outputImageAspectRatio;
    } else if (inputImageAspectRatio < outputImageAspectRatio) {
        outputHeight = inputWidth / outputImageAspectRatio;
    }

    // calculate the position to draw the image at
    const outputX = (outputWidth - inputWidth) * 0.5;
    const outputY = (outputHeight - inputHeight) * 0.5;

    // create a canvas that will present the output image
    const outputImage = document.createElement('canvas');

    // set it to the same size as the image
    outputImage.width = outputWidth;
    outputImage.height = outputHeight;

    // draw our image at position 0, 0 on the canvas
    const ctx = outputImage.getContext('2d');
    ctx.drawImage(inputImage, outputX, outputY);

    // show both the image and the canvas
    document.body.appendChild(inputImage);
    document.body.appendChild(outputImage);
};

// start loading our image
inputImage.src = imageURL;

With this update our crop is now centered on the input image.

Creating a Reusable JavaScript Crop Function

As a final step let’s turn our code into a reusable function so we can quickly crop images with various crop aspect ratios. Our JavaScript snippet is already suitable to be used for any aspect ratio, not just squares.

/**
 * @param {string} url - The source image
 * @param {number} aspectRatio - The aspect ratio
 * @return {Promise<HTMLCanvasElement>} A Promise that resolves with the resulting image as a canvas element
 */
function crop(url, aspectRatio) {
    // we return a Promise that gets resolved with our canvas element
    return new Promise((resolve) => {
        // this image will hold our source image data
        const inputImage = new Image();

        // we want to wait for our image to load
        inputImage.onload = () => {
            // let's store the width and height of our image
            const inputWidth = inputImage.naturalWidth;
            const inputHeight = inputImage.naturalHeight;

            // get the aspect ratio of the input image
            const inputImageAspectRatio = inputWidth / inputHeight;

            // if it's bigger than our target aspect ratio
            let outputWidth = inputWidth;
            let outputHeight = inputHeight;
            if (inputImageAspectRatio > aspectRatio) {
                outputWidth = inputHeight * aspectRatio;
            } else if (inputImageAspectRatio < aspectRatio) {
                outputHeight = inputWidth / aspectRatio;
            }

            // calculate the position to draw the image at
            const outputX = (outputWidth - inputWidth) * 0.5;
            const outputY = (outputHeight - inputHeight) * 0.5;

            // create a canvas that will present the output image
            const outputImage = document.createElement('canvas');

            // set it to the same size as the image
            outputImage.width = outputWidth;
            outputImage.height = outputHeight;

            // draw our image at position 0, 0 on the canvas
            const ctx = outputImage.getContext('2d');
            ctx.drawImage(inputImage, outputX, outputY);
            resolve(outputImage);
        };

        // start loading our image
        inputImage.src = url;
    });
}

Our new and shiny crop function can be called like so:

crop('path/to/our/image.jpeg', 1);

Or, to get a “16:9” crop:

crop('path/to/our/image.jpeg', 16 / 9);

As the function returns a Promise we can get the results like this:

crop('path/to/our/image.jpeg', 16 / 9).then((canvas) => {
    // `canvas` is the resulting image
});

Or, using async/await:

const canvas = await crop('path/to/our/image.jpeg', 16 / 9);

View a demo of the end result on CodePen

Conclusion

By using the HTML canvas API and some basic math we build a tiny crop helper function that makes it easy to quickly crop images in various aspect ratios. This helps us prepare images for social media posts, profile pictures, familiar document sizes, or other popular media formats.

To keep the article concise our current solution does not cover these edge cases:

Browsers being confused by mobile photos EXIF orientation header.
Canvas memory overflowing on mobile devices for very big images.
Poor image quality when downscaling images.

If you need a solution for these issues you could explore Pintura Image Editor, an easy to use image editor that solves these edge cases and features a wide range of additional functionality.

The Trouble With Editing And Uploading Files In The Browser

2019-09-10T00:00:00Z

With the introduction of the File API we gained the ability to edit files in the browser. We could finally resize images, unzip files, and generate new files based on interactions in the browser. One caveat though, you couldn’t upload these files.

Well you could, but you had to resort to either XMLHttpRequest or fetch, see, it’s not possible to set the value of a file input element. This means you can’t submit a custom file along with a classic form submit, you have to asynchronously upload the file. This really put the brakes on any progressive enhancement solutions to file editing. If you decide to modify a file on the client, then you also have to make sure you make changes on the server so you can receive the modified file.

As a product developer building image editing products this really grinds my gears. I’d love to offer my products as client-side only solutions. But that’s impossible because asynchronous file uploads require server-side modifications. WordPress, Netlify, Shopify, Bubble.io, they all offer default file input elements, but there’s no straightforward way to support them without writing a client-side and server-side plugin. In the case of WordPress this means offering a plugin for each and every form builder out there. Not very realistic.

But a couple months ago something changed.

Setting a custom file to a file input

It’s really quite logical that we can’t set the value of the file input element. Doing so would allow us to point it at files on the visitors file system.

<input type="file" />

<script>
    document.querySelector('input').value = 'some/file/i/want/to/have';
</script>

Obviously this would be a huge security risk.

Setting the file input value property is off the table.

What about the file input files property? If we could somehow update the files property or update the files in it, that would solve the issue.

The files property holds a reference to a FileList. Great! Let’s create a new FileList() and overwrite the one on the file input. Unfortunately there’s no FileList constructor. There is also no “add a file” method exposed on the FileList instance. On top of that the File object doesn’t have a method to update the file data in place, so we can’t update the individual file objects in the files list.

Well that’s it then.

And it was untill a couple months a go Hidde de Vries pointed me to this issue on the WHATWG, Turns out there’s a different API we can use to achieve our goal.

Firefox, Chrome, and Safari have recently added support for the DataTransfer constructor. The DataTransfer Class is most commonly used when dragging and dropping files from the user device to the webpage.

It has a files property of type FileList 🎉

It also has an items.add method for adding items to this list 🎉

Oh la la!

<input type="file" />

<script>
    // Create a DataTransfer instance and add a newly created file
    const dataTransfer = new DataTransfer();
    dataTransfer.items.add(new File(['hello world'], 'This_Works.txt'));

    // Assign the DataTransfer files list to the file input
    document.querySelector('input').files = dataTransfer.files;
</script>

If you’re browser can run the code above the file input below will show “This_Works.txt” as the input value. Starting from version 14.1 Safari also supports setting the files property in this manner but it won’t update the label next to the input.

It just works. Fantastic! We now have a method to send files created on the client to the server without having to make any changes to the server-side API.

This doesn’t work on IE, non Chromium Edge, and Safari versions before 14.1.

Alternatives for other browsers

If we want to submit our file data along with the form post, what can we offer users on these other browsers? There are currently two alternate solutions I can think of. One requires changes on the server, the other might be buggy depending on your use case.

Let’s take alook.

Encode the file data

We can encode the file data as a base64 string or dataURL, store the resulting string in a hidden input element and then send it on its way when the form is submitted. This will require changes to the server, the server will have to be aware an encoded file might be submitted as well. The server will also have to decode the dataURL and turn it back into a File object.

We can use the FileReader API to turn a File into a dataURL.

<input type="file" />
<input type="hidden" />

<script>
    document.querySelector('input[type="file"]').onchange = (e) => {
        const reader = new FileReader();
        reader.onloadend = () => {
            document.querySelector('input[type="hidden"]').value =
                reader.result;
        };
        reader.readAsDataURL(e.target.files[0]);
    };
</script>

A couple of issues my clients reported when using this method.

Security related scripts running on the server that monitor traffic might flag the form post as suspicious as it contains a lot of string based data.
When submitting large files, that means files above 1MB, it’s highly likely the browser will crash with a “ran out of memory” error. This differs per browser, but I’ve seen it happen on both mobile and desktop browsers.
You don’t see a change in the file input. So it’s a good idea to reset, disable, or hide it when submitting the form.

Encoding files is a fine solution if you’re dealing with small images, anything bigger than 1MB and I’d steer clear.

Capture the form submit

We can add custom files when submitting a form asynchronously. So another solution is capturing the entire form submit and asynchronously submitting the form to the same end point (action attribute) using XMLHttpRequest or fetch.

This is what I’ve tried to do with Poost (this is very much a prototype, also I’m bad at naming things on the spot). Poost captures the form submit, and then posts the form asynchronously instead. This allows us to build a custom FormData object, adding our custom file (stored in the _value property) instead of the files in the files property.

<input type="file" />

<script>
    // Create a new File object
    const myFile = new File(['Hello World!'], 'myFile.txt', {
        type: 'text/plain',
        lastModified: new Date(),
    });

    // Assign File to _value property
    const target = document.querySelector('input[type="file"]');
    target._value = [myFile];
</script>

This actually works quite well. We post the same data to the same end point. Things start to get tricky when you realise that the returned page also needs to be rendered to the screen (normally the browser navigates to it). Where are we going to render it, what to do with the navigator history, how to deal with script tags on the page, what about IE (no surprise there).

Again, when setting _value you don’t see a change in the file input. So it’s a good idea to reset, disable, or hide it when submitting the form.
We’re taking over a lot of default browser behavior, that is always a recipe for disaster.

Still, for very basic forms this works nicely. You don’t have to modify the server and it could even be loaded conditionally as a fallback for when a browser doesn’t support new DataTransfer().

The state of things

So our file upload situation, while it has improved, is still all but fantastic.

We’re still stuck with these bandaid solutions because of IE, Edge, and Safari. If you have the luxury it’s probably easier to make changes on the server to facilitate async transfers. If you’re in a situation where that’s impossible I hope the solutions offered above might just fit your situation perfectly and help you out.

How To Upload Images To The WordPress Media Library

2019-05-28T00:00:00Z

This quick guide shows you how to set up a form to upload images to your media library using the free WordPress plugin Snippy.

Creating a File Upload Handler

First step, let’s open your themes functions.php file, and add the code snippet below. This will create a location for us to send our files to.

function handle_my_file_upload() {

    // will return the attachment id of the image in the media library
    $attachment_id = media_handle_upload('my_file_field', 0);

    // test if upload succeeded
    if (is_wp_error($attachment_id)) {
        http_response_code(400);
        echo 'Failed to upload file.';
    }
    else {
        http_response_code(200);
        echo $attachment_id;
    }

    // done!
    die();
}

// allow uploads from users that are logged in
add_action('wp_ajax_my_file_upload', 'handle_my_file_upload');

// allow uploads from guests
add_action('wp_ajax_nopriv_my_file_upload', 'handle_my_file_upload');

There are a couple things to take note of:

handle_my_file_upload is the name of the function that will deal with the upload, both add_action calls reference it.
wp_ajax_ and wp_ajax_noprive_ are default hooks, we add my_file_upload to them to allow communication with our form which we’ll set up next.
Comment out the nopriv call to prevent file uploads from guests.

Creating the Form

Alright now we need to add a <form> to give the user a location to select the images they want to upload.

We’ll use the free WordPress plugin Snippy to create a shortcode that we can use everywhere on our WordPress website.

With Snippy installed we’ll start by creating an HTML bit. Click on the “Snippy/Add Bit” menu item. Name your HTML bit “file-form”. Set type to “HTML”. And paste the code below in the textfield.

<form
    action="{{admin_url}}"
    method="POST"
    enctype="multipart/form-data"
>
    <input type="hidden" name="action" value="my_file_upload" />
    <label for="image">Select file:</label>
    <input type="file" id="image" name="my_file_field" accept="image/*" />
    <button type="submit">Upload</button>
</form>

my_file_upload corresponds to the value used in the add_action calls.
my_file_field corresponds to the value used in the media_handle_upload call.

Now we’ll create our custom shortcode.

Click “Snippy/Add Shortcode” and use “file-upload” as the name. In the “Available bits” list we select our “file-form”. Click Save.

That’s it! We now have a form shortcode at our disposal.

[file-upload/]

Add it to a page (using the page editor), refresh the page, your file upload form should now appear.

Bonus: Editing the Image

Let’s upgrade our form to allow our users to edit dropped images using Pintura

We can use Snippy to add the Pintura files to the page.

Create a new local resource bit and select the Pintura CSS file (pintura.css).
Create another local resource bit and select the Pintura JavaScript file (pintura-iife.js).
Create a JavaScript bit and add the following code.

document.addEventListener('change', function (e) {
    // Store reference to the field to make later code easier to read
    const field = e.target;

    // Only intercept fields of type file that accept images and contain a file
    if (
        field.type !== 'file' ||
        !field.files[0] ||
        !/image\/*/.test(field.accept)
    )
        return;

    // Get reference to parent form
    const form = field.form;

    // Edit dropped image with Pintura
    const editor = pintura.openDefaultEditor({
        // The image to load
        src: field.files[0],

        // Set up custom file upload
        imageWriter: {
            store: {
                // Where to post to
                url: form.getAttribute('action'),

                // Which fields to post
                dataset: (state) => [
                    // Copy file field name and set value to output image
                    [field.name, state.dest, state.dest.name],

                    // Copy action field value
                    ['action', form.querySelector('[name="action"]').value],
                ],
            },
        },
    });
});

Now we can link these newly created bits to our “file-upload” shortcode by clicking the “Snippy/Shortcodes” menu item and editing our “file-upload” shortcode. Select the bits we just created and click “Save”.

Refresh the page and select an image, Pintura should open the image and when clicking done the edited image should appear in the WordPress Media Library. Please note that the animation below shows version 6 of the editor.

Security

To make this solution a little bit more secure we can add a WordPress nonce field.

Edit the HTML form like this:

<form
    action="{{admin_url}}"
    method="POST"
    enctype="multipart/form-data"
>
    {{nonce_field:my_file_upload, my_nonce_field}}

    <!-- ...This part of the form remains untouched -->
</form>

And add the following if statements to the functions.php file so it checks if the form post is valid and came from your own site.

function handle_my_file_upload() {

    if (empty($_POST)) {
        http_response_code(400);
        echo 'Nothing data received.';
        die();
    }

    if (!wp_verify_nonce($_POST['my_nonce_field'], 'my_file_upload')) {
        http_response_code(400);
        echo 'Unknown error.';
        die();
    }

    /* The rest of the function stays the same */

}

Conclusion

That’s it! We’re done. These code snippets should give you a good idea of what is required for uploading files with WordPress and how to build uppon it. If you were not familiar with Snippy this should’ve been a nice introduction on how it can help you manage small parts of your WordPress site.

That said. This is still a bare bone solution that can be further build uppon with redirects, upload progress indicators, sending additional form data, and more. I’ll leave that for a future article.

CSS Smooth Scrolling

2019-02-14T00:00:00Z

Last year, while building the FilePond product page I stumbled upon the scrollIntoView API. It’s a handy method to instruct the browser to scroll an element into the viewport.

The scrollIntoView API can be instructed to animate the scrolling part by adding the behavior property on the scrollIntoViewOption object.

element.scrollIntoView({ behavior: 'smooth' });

I quickly jumped on my JavaScript horse and wrote a tiny script to automatically detect clicks on anchors so the browser would animate the jump towards the anchor target. This jump can be really disorienting, so animating this process would improve the user experience quite a bit.

scrollIntoViewOption currently only works on Firefox and Chrome.

// Everytime someone clicks on something
document.body.addEventListener('click', (e) => {
    const href = e.target.href;

    // no href attribute, no need to continue then
    if (!href) return;

    const id = href.split('#').pop();
    const target = document.getElementById(id);

    // no target to scroll to, bail out
    if (!target) return;

    // prevent the default quick jump to the target
    e.preventDefault();

    // set hash to window location so history is kept correctly
    history.pushState({}, document.title, href);

    // smooooooth scroll to the target!
    target.scrollIntoView({
        behavior: 'smooth',
        block: 'start',
    });
});

Live demo

This works wonderfully.

I posted it on Twitter and called it a day.

Then, Hans Spieß points out that this can also be done with CSS, WHAT!?

Turns out there’s a scroll-behavior CSS property that we can set to smooth, it’s literally that literal. It’s almost like awesome: yes-please. We can set the scroll-behavior property to the container we want to exhibit smooth scroll behavior and we’re done.

I created a new demo on CodePen using only CSS.

Before we go nuts and apply this to all our sites, there are a couple of things to keep in mind.

Scroll distance matters

If there is a lot of content to scroll, Firefox will skip content to keep the scroll time-limited, while Chrome has a max velocity and will just take its time to get to the target.

Live Demo on CodePend

We could use Smart CSS to detect long pages and conditionally apply the smooth scroll style.

Accessibility

People might get motion sickness when watching the animation. To circumvent this you can wrap the CSS property in a prefers-reduced-motion media query. Unfortunately, Chrome does not support this. Safari supports it, but Safari doesn’t support smooth scrolling.

.my-smooth-container {
    scroll-behavior: smooth;
}

@media (prefers-reduced-motion: reduce) {
    .my-smooth-container {
        scroll-behavior: auto;
    }
}

Conclusion

When deciding on a new functionality we shouldn’t reach out to JavaScript immediately. We should do a quick search first to find out if it can be done with CSS as well. The scroll-behavior property can be a nice UX improvement, do make sure you disable it on very long pages and offer an option to disable it to keep your pages accessible.

Using Smart CSS To Time Your Newsletter Popup

2019-01-29T00:00:00Z

In the previous article on Smart CSS we used the user’s scroll position to trigger a floating navigation header.

Let’s take it a step further and see if we can use this technique to determine if a user is interested in subscribing to our newsletter. Imagine this is a newsletter on a website that presents the user with an article like the one you’re reading now. The goal is to trigger the user into subscribing so we can send a notification if a new article is published in the future.

We’ll assume the marketing department has us at gunpoint and orders us to show a popup with a subscription form.

Imagine you’re shopping in real life, you wander into a random shop, you haven’t even crossed the doorstep and the shop keeper jumps in your face and asks you if you want to receive their monthly newsletter. This would be weird, right?

On the internet, the above behavior is somehow the norm.

Maybe it would be a good start to gauge the user’s interest in our newsletter before we ask. How do we determine this potential interest? Let’s go back to our random shop.

Suppose the following:

I’ve visited the shop before
I’ve spent some time wandering the shop
I’ve actually purchased something
I’ve had a positive interaction with the shop keeper

If a couple of these had a green light, I would still not welcome the shop keeper jumping in front of me, but I certainly would not mind them asking me at the counter, and if that would happen, I might even subscribe.

Are there equivalents to this in our online environment? I can think of a couple of data points, but do let me know in the comments if you have any other suggestions.

The user spent some time on the site
The user has been reading the page
The user has spent some time on the current page
The user has made a purchase

Translating these data points to variables

To determine if the user has visited the site before we can store the time she spent on our site in a session variable using localStorage. By calculating the time spent on each page and storing it at a certain interval we can know how long the user has been browsing the site. And thus, we can determine how familiar the user is with our platform, are we a random shopkeeper? Or have we met before?

By measuring how far the user has scrolled down on the page we can determine if he is interacting with the site. If the page presents an article this might give us some information on how far along the article the user has read. Combine this with the time user has spent on the page and we could guestimate the user has read the article or is nearly done reading it. If the user has taken the time to read the article, then that might mean he’s interested in our content, he’s “purchased” our content so to speak. Of course, if you run a webshop you could keep track of actual purchases as well.

The techniques used in the demo below are mostly the same as in the earlier article. I’ve introduced a function that serves as an updater for the data attributes. And another addition is the stack function.

const stack = (value, step) => {
    // round the value to the nearest value divisible by step
    // if value is 37 and step is 10 the result is 30
    value = Math.floor(value / step) * step;

    // 30 will be our first value
    const parts = [value];

    // now we subtract 10 each iteration till we reach 0
    while (value > 0) {
        value -= step;
        parts.push(value);
    }

    // reverse the array so it goes from 0 to 30 insted of 30 to 0
    return parts.reverse();
};

This function receives a value and a step parameter. Suppose the value is set to 50 and the step is set to 10, the function will return this array: [0, 10, 20, 30, 40, 50]. We use this array to store multiple values in our data attributes.

For example, suppose the user has scrolled 50% of the page. The data-vertical-scroll-progress attribute is then set to "0 10 20 30 40 50". This allows us to use CSS attribute selectors to determine if the user has scrolled at least 30 percent of the page. The ~= comparison checks if the set value contains in a white space separated list of items.

<html data-vertical-scroll-progress="0 10 20 30 40 50">
    <!-- Your website here -->
</html>

html[data-vertical-scroll-progress~='30'] {
    /* user has scrolled down 30% */
}

Let’s combine all our tests and make this a reality. The below demo will show the popup when you’ve scrolled down 50% and have been on the page for 30 seconds.

Live Demo on CodePen

Applying Styles Based On The User Scroll Position With Smart CSS

2019-01-25T00:00:00Z

By mapping the current scroll offset to an attribute on the html element we can style elements on the page based on the current scroll position. We can use this to build, for example, a floating navigation component.

This is the HTML we’ll work with, a nice <header> component that we want to float on top of the content when we scroll down.

<header>I'm the page header</header>
<p>Lot's of content here...</p>
<p>More beautiful content...</p>
<p>Content...</p>

As a start, we’ll listen for the 'scroll' event on the document and we’ll request the current scrollY position each time the user scrolls.

document.addEventListener('scroll', () => {
    document.documentElement.dataset.scroll = window.scrollY;
});

We have the scroll position stored in a data attribute on the html element. If you view the DOM using your dev tools it would look like this <html data-scroll="0">.

Now we can use this attribute to style elements on the page.

/* Make sure the header is always at least 3em high */
header {
    min-height: 3em;
    width: 100%;
    background-color: #fff;
}

/* Reserve the same height at the top of the page as the header min-height */
html:not([data-scroll='0']) body {
    padding-top: 3em;
}

/* Switch to fixed positioning, and stick the header to the top of the page */
html:not([data-scroll='0']) header {
    position: fixed;
    top: 0;
    z-index: 1;

    /* This box-shadow will help sell the floating effect */
    box-shadow: 0 0 0.5em rgba(0, 0, 0, 0.5);
}

This is basically it, the header will now automatically detach from the page and float on top of the content when scrolling down. The JavaScript code doesn’t care about this, it’s task is simply putting the scroll offset in the data attribute. This is nice as there is no tight coupling between the JavaScript and the CSS.

There are still some improvements to make, mostly in the performance area.

But first, we have to fix our script for situations where the scroll position is not at the top when the page loads. In those situations, the header will render incorrectly.

When the page loads we’ll have to quickly get the current scroll offset. This ensures we’re always in sync with the current state of affairs.

// Reads out the scroll position and stores it in the data attribute
// so we can use it in our stylesheets
const storeScroll = () => {
    document.documentElement.dataset.scroll = window.scrollY;
};

// Listen for new scroll events
document.addEventListener('scroll', storeScroll);

// Update scroll position for first time
storeScroll();

Next we’re going to look at some performance improvements. If we request the scrollY position the browser will have to calculate the positions of each and every element on the page to make sure it returns the correct position. It’s best if we not force it to do this each and every scroll interaction.

To do this, we’ll need a debounce method, this method will queue our request till the browser is ready to paint the next frame, at that point it has already calculate the positions of all the elements on the page so it won’t do it again.

// The debounce function receives our function as a parameter
const debounce = (fn) => {
    // This holds the requestAnimationFrame reference, so we can cancel it if we wish
    let frame;

    // The debounce function returns a new function that can receive a variable number of arguments
    return (...params) => {
        // If the frame variable has been defined, clear it now, and queue for next frame
        if (frame) {
            cancelAnimationFrame(frame);
        }

        // Queue our function call for the next frame
        frame = requestAnimationFrame(() => {
            // Call our function and pass any params we received
            fn(...params);
        });
    };
};

// Reads out the scroll position and stores it in the data attribute
// so we can use it in our stylesheets
const storeScroll = () => {
    document.documentElement.dataset.scroll = window.scrollY;
};

// Listen for new scroll events, here we debounce our `storeScroll` function
document.addEventListener('scroll', debounce(storeScroll));

// Update scroll position for first time
storeScroll();

By marking the event as passive we can tell the browser that our scroll event is not going to be canceled by a touch interaction (for instance when interacting with a plugin like Google Maps). This allows the browser to scroll the page immediately as it now knows that the event won’t be canceled.

document.addEventListener('scroll', debounce(storeScroll), { passive: true });

With the performance issues resolved we now have a stable way to feed data obtained with JavaScript to our CSS and can use this to start styling elements on the page.

Live Demo on CodePen

Async Form Posts With A Couple Lines Of Vanilla JavaScript

2019-01-24T00:00:00Z

In this tutorial we’ll write a tiny JavaScript event handler that will post our HTML forms using fetch instead of the classic synchronous form post. We’re building a solution based on the Progressive Enhancement strategy, if JavaScript fails to load, users will still be able to submit our form.

With this approach, when JavaScript is available, the form submit will be a lot smoother. While building this solution we’ll explore JavaScript DOM APIs, handy HTML structures, and accessibility related topics.

Let’s get started and set up our form.

Setting up the HTML

Our goal is to build a newsletter subscription form.

The form will have an optional name field and an email field that we’ll mark as required. We assign the required attribute to our email field so the form can’t be posted if this field is empty. Also, we set the field type to email which triggers email validation and shows a nice email keyboard layout on mobile devices.

<form action="subscribe.php" method="POST">
    Name
    <input type="text" name="name" />

    Email
    <input type="email" name="email" required />

    <button type="submit">Submit</button>
</form>

Our form will post to a subscribe.php page, which in our situation is nothing more than a page with a paragraph that confirms to the user that she has subscribed to the newsletter.

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <title>Successfully subscribed!</title>
    </head>
    <body>
        <p>Successfully subscribed!</p>
    </body>
</html>

Let’s quickly move back to our <form> tag to make some tiny improvements.

If our stylesheet somehow fails to load it currently renders like this:

This isn’t horribly bad for our tiny form, but imagine this being a bigger form, and it’ll be quite messy as every field will be on the same line. Let’s wrap each label and field combo in a <div>.

<form action="subscribe.php" method="POST">
    <div>
        Name
        <input type="text" name="name" />
    </div>

    <div>
        Email
        <input type="email" name="email" required />
    </div>

    <button type="submit">Submit</button>
</form>

Now each field is rendered on a new line.

Another improvement would be to wrap the field names in a <label> element so we can explicitly link each label to its sibling input field. This allows users to click on the label to focus the field but also triggers assistive technology like screen readers to read out the label of the field when the field receives focus.

<form action="subscribe.php" method="POST">
    <div>
        <label for="name">Name</label>
        <input type="text" name="name" id="name" />
    </div>

    <div>
        <label for="email">Email</label>
        <input type="email" name="email" id="email" required />
    </div>

    <button type="submit">Submit</button>
</form>

A tiny effort resulting in big UX and accessibility gains. Wonderful!

With our form finished, let’s write some JavaScript.

Writing the Form Submit Handler

We’ll write a script that turns all forms on the page into asynchronous forms.

We don’t need access to all forms on the page to set this up, we can simply listen to the 'submit' event on the document and handle all form posts in a single event handler. The event target will always be the form that was submitted so we can access the form element using e.target

To prevent the classic form submit from happening we can use the preventDefault method on the event object, this will prevent default actions performed by the browser.

If you only want to handle a single form, you can do so by attaching the event listener to that specific form element.

document.addEventListener('submit', (e) => {
    // Store reference to form to make later code easier to read
    const form = e.target;

    // Prevent the default form submit
    e.preventDefault();
});

Okay, we’re now ready to send our form data.

This action is two-part, the sending part and the data part.

For sending the data we can use the fetch API, for gathering the form data we can use a super handy API called FormData.

document.addEventListener('submit', (e) => {
    // Store reference to form to make later code easier to read
    const form = e.target;

    // Post data using the Fetch API
    fetch(form.action, {
        method: form.method,
        body: new FormData(form),
    });

    // Prevent the default form submit
    e.preventDefault();
});

Yes, I kid you not, it’s this straightforward.

The first argument to fetch is a URL, so we pass the form.action property, which contains subscribe.php. Then we pass a configuration object, which contains the method to use, which we get from the form.method property (POST). Lastly, we need to pass the data in the body property. We can blatantly pass the form element as a parameter to the FormData constructor and it’ll create an object for us that resembles the classic form post and is posted as multipart/form-data.

Michael Scharnagl suggested moving the preventDefault() call to the end, this makes sure the classic submit is only prevented if all our JavaScript runs.

We’re done! To the pub!

Of course, there are a couple of things we forgot, this basically was the extremely happy flow, so hold those horses and put down that pint. How do we handle connection errors? What about notifying the user of a successful subscription? And what happens while the subscribe page is being requested?

The Edge Cases

Let’s first handle notifying the user of a successful newsletter subscription.

Showing the Success State

We can do this by pulling in the message on the subscribe.php page and showing that instead of the form element. Let’s continue right after the fetch statement and handle the resolve case of the fetch call.

First, we need to turn the response into a text based response. Then we can turn this text-based response in an actual HTML document using the DOMParser API, we tell it to parse our text and regard it as text/html, we return this result so it’s available in the next then

Now we have an HTML document to work with (doc) we can finally replace our form with the success status. We’ll copy the body.innerHTML to our result.innerHTML, then we replace our form with the newly created result element. Last but not least we move focus to the result element so it’s read to screen reader users and keyboard users can resume navigation from that point in the page.

document.addEventListener('submit', (e) => {
    // Store reference to form to make later code easier to read
    const form = e.target;

    // Post data using the Fetch API
    fetch(form.action, {
        method: form.method,
        body: new FormData(form),
    })
        // We turn the response into text as we expect HTML
        .then((res) => res.text())

        // Let's turn it into an HTML document
        .then((text) => new DOMParser().parseFromString(text, 'text/html'))

        // Now we have a document to work with let's replace the <form>
        .then((doc) => {
            // Create result message container and copy HTML from doc
            const result = document.createElement('div');
            result.innerHTML = doc.body.innerHTML;

            // Allow focussing this element with JavaScript
            result.tabIndex = -1;

            // And replace the form with the response children
            form.parentNode.replaceChild(result, form);

            // Move focus to the status message
            result.focus();
        });

    // Prevent the default form submit
    e.preventDefault();
});

Connection Troubles

If our connection fails the fetch call will be rejected which we can handle with a catch

First, we extend our HTML form with a message to show when the connection fails, let’s place it above the submit button so it’s clearly visible when things go wrong.

<form action="subscribe.php" method="POST">
    <div>
        <label for="name">Name</label>
        <input type="text" name="name" id="name" />
    </div>

    <div>
        <label for="email">Email</label>
        <input type="email" name="email" id="email" required />
    </div>

    <p role="alert" hidden>Connection failure, please try again.</p>

    <button type="submit">Submit</button>
</form>

By using the hidden attribute, we’ve hidden the <p> from everyone. We’ve added a role="alert" to the paragraph, this triggers screen readers to read out loud the contents of the paragraph once it becomes visible.

Now let’s handle the JavaScript side of things.

The code we put in the fetch rejection handler (catch) will select our alert paragraph and show it to the user.

document.addEventListener('submit', (e) => {
    // Store reference to form to make later code easier to read
    const form = e.target;

    // Post data using the Fetch API
    fetch(form.action, {
        method: form.method,
        body: new FormData(form),
    })
        // We turn the response into text as we expect HTML
        .then((res) => res.text())

        // Let's turn it into an HTML document
        .then((text) => new DOMParser().parseFromString(text, 'text/html'))

        // Now we have a document to work with let's replace the <form>
        .then((doc) => {
            // Create result message container and copy HTML from doc
            const result = document.createElement('div');
            result.innerHTML = doc.body.innerHTML;

            // Allow focussing this element with JavaScript
            result.tabIndex = -1;

            // And replace the form with the response children
            form.parentNode.replaceChild(result, form);

            // Move focus to the status message
            result.focus();
        })
        .catch((err) => {
            // Some form of connection failure
            form.querySelector('[role=alert]').hidden = false;
        });

    // Make sure connection failure message is hidden
    form.querySelector('[role=alert]').hidden = true;

    // Prevent the default form submit
    e.preventDefault();
});

We select our alert paragraph with the CSS attribute selector [role=alert]. No need for a class name. Not saying we might not need one in the future, but sometimes selecting by attribute is fine.

I think we got our edge cases covered, let’s polish this up a bit.

Locking Fields While Loading

It would be nice if the form locked all input fields while it’s being sent to the server. This prevents the user from clicking the submit button multiple times, and also from editing the fields while waiting for the process to finish.

We can use the form.elements property to select all form fields and then disable each field.

If you have a <fieldset> in your form, you can disable the fieldset and that will disable all fields inside it

document.addEventListener('submit', (e) => {
    // Store reference to form to make later code easier to read
    const form = e.target;

    // Post data using the Fetch API
    fetch(form.action, {
        method: form.method,
        body: new FormData(form),
    })
        // We turn the response into text as we expect HTML
        .then((res) => res.text())

        // Let's turn it into an HTML document
        .then((text) => new DOMParser().parseFromString(text, 'text/html'))

        // Now we have a document to work with let's replace the <form>
        .then((doc) => {
            // Create result message container and copy HTML from doc
            const result = document.createElement('div');
            result.innerHTML = doc.body.innerHTML;

            // Allow focussing this element with JavaScript
            result.tabIndex = -1;

            // And replace the form with the response children
            form.parentNode.replaceChild(result, form);

            // Move focus to the status message
            result.focus();
        })
        .catch((err) => {
            // Show error message
            form.querySelector('[role=alert]').hidden = false;
        });

    // Disable all form elements to prevent further input
    Array.from(form.elements).forEach((field) => (field.disabled = true));

    // Make sure connection failure message is hidden
    form.querySelector('[role=alert]').hidden = true;

    // Prevent the default form submit
    e.preventDefault();
});

form.elements needs to be turned into an array using Array.from for us to loop over it with forEach and set the disable attribute on true for each field.

Now we got ourselves into a sticky situation because if fetch fails and we end up in our catch all form fields are disabled and we can no longer use our form. Let’s resolve that by adding the same statement to the catch handler but instead of disabling the fields we’ll enable the fields.

.catch(err => {

  // Unlock form elements
  Array.from(form.elements).forEach(field => field.disabled = false);

  // Show error message
  form.querySelector('[role=alert]').hidden = false;

});

Believe it or not, we’re still not out of the woods. Because we’ve disabled all elements the browser has moved focus to the <body> element. If the fetch fails we end up in the catch handler, enable our form elements, but the user has already lost her location on the page (this is especially useful for users navigating with a keyboard, or, again, users that have to rely on a screen reader).

We can store the current focussed element document.activeElement and then restore the focus with element.focus() later on when we enable all the fields in the catch handler. While we wait for a response we’ll move focus to the form element itself.

document.addEventListener('submit', (e) => {
    // Store reference to form to make later code easier to read
    const form = e.target;

    // Post data using the Fetch API
    fetch(form.action, {
        method: form.method,
        body: new FormData(form),
    })
        // We turn the response into text as we expect HTML
        .then((res) => res.text())

        // Let's turn it into an HTML document
        .then((text) => new DOMParser().parseFromString(text, 'text/html'))

        // Now we have a document to work with let's replace the <form>
        .then((doc) => {
            // Create result message container and copy HTML from doc
            const result = document.createElement('div');
            result.innerHTML = doc.body.innerHTML;

            // Allow focussing this element with JavaScript
            result.tabIndex = -1;

            // And replace the form with the response children
            form.parentNode.replaceChild(result, form);

            // Move focus to the status message
            result.focus();
        })
        .catch((err) => {
            // Unlock form elements
            Array.from(form.elements).forEach(
                (field) => (field.disabled = false)
            );

            // Return focus to active element
            lastActive.focus();

            // Show error message
            form.querySelector('[role=alert]').hidden = false;
        });

    // Before we disable all the fields, remember the last active field
    const lastActive = document.activeElement;

    // Move focus to form while we wait for a response from the server
    form.tabIndex = -1;
    form.focus();

    // Disable all form elements to prevent further input
    Array.from(form.elements).forEach((field) => (field.disabled = true));

    // Make sure connection failure message is hidden
    form.querySelector('[role=alert]').hidden = true;

    // Prevent the default form submit
    e.preventDefault();
});

I admit it’s not a few lines of JavaScript, but honestly, there are a lot of comments in there.

Showing a Busy State

To finish up it would be nice to show a busy state so the user knows something is going on.

Please note that while fetch is fancy, it currently doesn’t support setting a timeout and it also doesn’t support progress events, so for busy states that might take a while there would be no shame in using XMLHttpRequest, it would be a good idea even.

With that said the time has come to add a class to that alert message of ours (DAMN YOU PAST ME!). We’ll name it status-failure and add our busy paragraph right next to it.

<form action="subscribe.php" method="POST">
    <div>
        <label for="name">Name</label>
        <input type="text" name="name" id="name" />
    </div>

    <div>
        <label for="email">Email</label>
        <input type="email" name="email" id="email" required />
    </div>

    <p role="alert" class="status-failure" hidden>
        Connection failure, please try again.
    </p>

    <p role="alert" class="status-busy" hidden>
        Busy sending data, please wait.
    </p>

    <button type="submit">Submit</button>
</form>

We’ll reveal the busy state once the form is submitted, and hide it whenever we end up in catch. When data is submitted correctly the entire form is replaced, so no need to hide it again in the success flow.

When the busy state is revealed, instead of moving focus to the form, we move it to the busy state. This triggers the screen reader to read it out loud so the user knows the form is busy.

We’ve stored references to the two status messages at the start of the event handler, this makes the code later on a bit easier to read.

document.addEventListener('submit', (e) => {
    // Store reference to form to make later code easier to read
    const form = e.target;

    // get status message references
    const statusBusy = form.querySelector('.status-busy');
    const statusFailure = form.querySelector('.status-failure');

    // Post data using the Fetch API
    fetch(form.action, {
        method: form.method,
        body: new FormData(form),
    })
        // We turn the response into text as we expect HTML
        .then((res) => res.text())

        // Let's turn it into an HTML document
        .then((text) => new DOMParser().parseFromString(text, 'text/html'))

        // Now we have a document to work with let's replace the <form>
        .then((doc) => {
            // Create result message container and copy HTML from doc
            const result = document.createElement('div');
            result.innerHTML = doc.body.innerHTML;

            // Allow focussing this element with JavaScript
            result.tabIndex = -1;

            // And replace the form with the response children
            form.parentNode.replaceChild(result, form);

            // Move focus to the status message
            result.focus();
        })
        .catch((err) => {
            // Unlock form elements
            Array.from(form.elements).forEach(
                (field) => (field.disabled = false)
            );

            // Return focus to active element
            lastActive.focus();

            // Hide the busy state
            statusBusy.hidden = false;

            // Show error message
            statusFailure.hidden = false;
        });

    // Before we disable all the fields, remember the last active field
    const lastActive = document.activeElement;

    // Show busy state and move focus to it
    statusBusy.hidden = false;
    statusBusy.tabIndex = -1;
    statusBusy.focus();

    // Disable all form elements to prevent further input
    Array.from(form.elements).forEach((field) => (field.disabled = true));

    // Make sure connection failure message is hidden
    statusFailure.hidden = true;

    // Prevent the default form submit
    e.preventDefault();
});

That’s it!

We skipped over the CSS part of front-end development, you can either use a CSS framework or apply your own custom styles. The example as it is should give an excellent starting point for further customization.

One final thing. Don’t remove the focus outline.

Conclusion

We’ve written a semantic HTML structure for our form and then built from there to deliver an asynchronous upload experience using plain JavaScript. We’ve made sure our form is accessible to users with keyboards and users who rely on assistive technology like screen readers. And because we’ve followed a Progressive Enhancement strategy the form will still work even if our JavaScript fails.

I hope we’ve touched upon a couple new APIs and methodologies for you to use, let me know if you have any questions!

FilePond.js Launch Day Post-mortem

2018-03-06T00:00:00Z

Last Thursday I decided to finally launch FilePond.js, a JavaScript file upload library I’d been working on for six months. This is a summary of how I prepared for launch day and why having only a single sale did not make me a sad panda.

I like to endlessly work on a polished user experience. It’s both a strength as a weakness, as you can keep polishing it forever, things will never be as shiny as you want them to be. So two weeks back, I stopped all polishing activities and started working towards an official release.

I decided that FilePond was as feature complete as it was going to be in the next couple of months. Any additional features would simply delay the launch too much. It still did not have manual editing of images, chunk uploading, or a React wrapper. While those features would make it stand out from the competition, they would also push the release months into the future. Releasing those features independently would allow me to create renewed attention after the main release, which would be valuable as well.

Before I could launch I had restructure the promotion page to be a proper product page.

Finishing the Product Page

I started work on the product page and tried to follow these Landing Page tips by Julian Shapiro as close as possible. All the while I shared my progress on Twitter, Dribbble, and WIP.chat to validate I was heading in the right direction.

A couple days before launch I opened a topic on Indie Hackers to get final feedback. The 28th of February, the day before launch, I was still tweaking the title and tagline.

Launch Plan

The day before launch, I set up a launch plan. The launch plan would remind me of all the activities I should be doing during launch day. I was going to need this as I knew that if things would heat up, my adrenaline would start racing and I would forget stuff.

The plan contained a timeline with info on when to post what to which network. I also added popular Twitter accounts to the list and determined when it would be best to contact them using personal messages ( check at what time of day they are mostly active on Twitter ).

The day started with posting FilePond on Product Hunt. It’s best to post at the start of the day, as that allows you to collect as many upvotes as possible. Luckily midnight at Product Hunt HQ is a comfortable 9 AM in The Netherlands ☀️ I already prepared a description, animated icon and first comment so I could post quickly. Then it’s fingers crossed 🤞🏻

I developed FilePond in the open on WIP.chat, so I marked FilePond as launched and shared with everyone that FilePond was also live on Product Hunt.

Then a couple hours later I posted FilePond on Reddit, IndieHackers, Designer News and Hacker News. It received a lot of attention on Reddit and IndieHackers. It quickly dropped off the page on Designer News and Hacker News, oh well 🙂

I spent the day replying to comments on all these networks and answering peoples questions as honest and detailed as possible. It was intense but so rewarding.

FilePond climbed to spot #2 on the Product Hunt homepage and at the end of the day finished at spot #5. Quite happy with that!

The Indie Hackers post was upvoted quite a bit so received a lot of attention as well ( around 1000 views ). The post on r/webdesign held the top position the entire day and got around 5300 views.

User sessions during launch day.

A Single Sale

I had set up a purchase code to offer potential clients a 15% discount if they purchased FilePond during launch day. Having high hopes I initially was taken aback by the fact that no sales were happening.

Then it hit me. It should’ve hit me a lot earlier, but better late than never.

FilePond is not a product that solves an immediate problem in everyone’s developer lives. It’s a product that solves a problem for a certain part of a project. A lot of comments would be phrased like this “Amazing product, can’t wait to use it” or “Will use this in my next project for sure”.

The chance that during launch day someone was working on a project that needed a file upload library right then and there was slim.

My main goal should’ve been to get FilePond under the eyes of as many developers as possible. So from that moment on I shifted my focus to getting the FilePond GitHub repository in the trending JavaScript repositories overview.

At the end of Friday, it was holding steady at position #2.

It’s currently still on the list at position #7. It’s gone from 15 GitHub stars at launch to 1110 at the time of this writing.

Around 6 PM during dinner I made my first sale. 🎉

What’s Next

I’ve decided to first write this post-mortem and then take a step back and refocus my efforts.

The plan right now is to start work on the quick wins first. It would be nice to have jQuery and React wrappers available so people can more easily integrate FilePond in their projects. The next step would be to offer manual image editing capabilities.

I’m really enjoying the attention FilePond is getting and hope to eventually see sales rise as awareness of its existence increases. I’m content with it not making a gazillion sales during launch day as I’m in it for the long haul.

Use JavaScript Plugins With WordPress

2017-06-21T00:00:00Z

You’ve found that perfect plugin for your site, but dang, it’s not available for WordPress, it’s a jQuery plugin. Fear not, the following guide will help you set up any jQuery or JavaScript plugin on WordPress.

For this tutorial we’ll look into how to setup Flip, a JavaScript Countdown plugin, for use with WordPress using Snippy a free WordPress plugin.

If you’d rather watch a video of this tutorial, then follow step one below and then open the Snippy tutorial on YouTube.

Step 1. Download and install WordPress plugin Snippy

Snippy is open source and available on GitHub, you can download Snippy from the WordPress plugin page.

With Snippy you can build your own shortcodes and define which resources (bits) are required when the shortcode is used on a page.

A bit can be a Stylesheet, a JavaScript file or a snippet of HTML, CSS or inline JavaScript.

You are probably familiar with shortcodes already. Shortcodes can embed files or create objects that would normally require lots of complicated, ugly code in just one line. Snippy allows you to create your own custom shortcodes. A custom Snippy shortcode consists of one or more bits.

Step 2. Adding Bits

We start by adding our Stylesheet, JavaScript and HTML bits. Without bits, no shortcode.

Click the Snippy menu item. Then click on “Add bit”.

We’ll call our JavaScript bit “Tick JavaScript”, so it’s easy to find it later.
Set type to “Resource”, as we want to upload a file.
Click on the file upload control and select the “tick.js” file.
Click Save!

When we return to the overview we can now see our bit is listed.

Follow the same same steps for our Stylesheet. Name the bit “Tick Stylesheet” and this time pick the “tick.css” file. Save!

Okay, we’ve added two bits to our bit list. We can now add the final bit, the HTML snippet required for Tick to work. Again click on “Add bit”.

Name the bit “Tick Countdown Preset” and set type to “HTML”.
Open the countdown preset in your favorite text editor and copy past the preset snippet to the value field.
We can now add a placeholder value. Replace the Tick.count.down() part with Tick.count.down('{{due}}'). The due value is now automatically turned into a placeholder and we can use it later in our shortcode.
Click Save to finalize this bit.

Okay, we’ve setup all our bits. Ready to move on to the shortcode.

Step 3. Our very own Shortcode

Click “Add shortcode” to open the Shortcode editor.

We’ll name our shortcode “countdown”, all lowercase letters.

Below the name field we can see a list of all available bits. Let’s select all the bits we’ve just created. When done, click Save.

We’ve now created a custom shortcode. Let’s move to the text editor to add it to a page.

Step 4. Adding the Shortcode to a page

Edit one of your pages, best to make sure it’s a wide page so the counter has enough room.

Okay, you found one. Open the text editor, make sure the view tab is selected and click on a location in the view where you want to shortcode to be placed.

Now, click on the little Snippy icon. It’ll show a list of available custom shortcodes.
Select our “countdown” short code. It will now unfold at the location you had selected showing the available attributes. In this case “due”.
Enter a value for the due date of the counter. Flip dates are defined in ISO8601 format so a value like “2018-07-01T12:00:00” would count down to 12 o’clock on July the first of 2018.

Let’s hit the update button and refresh the page. The Flip counter should now be visible on the page. It’s possible that it requires some style adjustments based on the font size and space of your theme. Change the set font sizes in the preset to make it fit perfectly.

Upload Multiple Files With Slim Image Cropper

2016-12-22T00:00:00Z

Slim Image Cropper is a nifty way to let users upload cropped images to your server. but it doesn’t offer an out of the box solution to upload multiple images at once. In this article we’ll setup a script that works together with Slim to setup basic multiple file upload.

If you’re not familiar with Slim you can read more about it on the Slim Image Cropper Product Page.

Alright, let’s get started.

First things first, we’ll need a place to drop multiple images. We’ll create a simple <div> element for that. Inside the div we will add a text so the user knows where to drop the images. For this text we can use a <label> element. If we then bind this label element to a <input> of type file (using the for attribute with the input id as value), we’re good to go! Oh, if you add the multiple attribute to the input the user can select multiple files.

This label / input combo will help us out in a couple of situations. The first advantage is this, if our JavaScript fails, we’ll still have our classic file upload.

<div class="file-drop-area">
    <label for="files">Drop your files here</label>
    <input name="files[]" id="files" type="file" multiple />
</div>

Alright, with the HTML setup we can now move on to add a some style. We style the label to look like the drop area. We also give it a cursor that looks like a pointer, when the user hovers over the label the browser reveals that it’s clickable.

Now for the second advantage of our label / input combo. Because we’ve bound or <label> to our <input> our eventual solution will work both when the user drops images on the drop area and when the user clicks the label.

.file-drop-area label {
    display: block;
    padding: 2em;
    background: #eee;
    text-align: center;
    cursor: pointer;
}

On to JavaScript!

We’ll have to handle the file drag and drop events. drag needs to be defaultPrevented (I don’t know if that’s even a word) for drop to work. Also, we’ll bind the change event on the file input so manual file selection also works.
For each dropped or selected item we’ll have figure out if it’s an actual file and if it matches our expectations.
Create an Image Cropper for each of the dropped files that met our expectations.
If all our script ran successfully we can hide the file input element.

// 1. Handling the various events
// - get references to different elements we need
// - listen to drag, drop and change events
// - handle dropped and selected files

// get a reference to the file drop area and the file input
var fileDropArea = document.querySelector('.file-drop-area');
var fileInput = fileDropArea.querySelector('input');
var fileInputName = fileInput.name;

// listen to events for dragging and dropping
fileDropArea.addEventListener('dragover', handleDragOver);
fileDropArea.addEventListener('drop', handleDrop);
fileInput.addEventListener('change', handleFileSelect);

// need to block dragover to allow drop
function handleDragOver(e) {
    e.preventDefault();
}

// deal with dropped items,
function handleDrop(e) {
    e.preventDefault();
    handleFileItems(e.dataTransfer.items || e.dataTransfer.files);
}

// handle manual selection of files using the file input
function handleFileSelect(e) {
    handleFileItems(e.target.files);
}

// 2. Handle the dropped items
// - test if the item is a File or a DataTransferItem
// - do some expectation matching

// loops over a list of items and passes
// them to the next function for handling
function handleFileItems(items) {
    var l = items.length;
    for (var i = 0; i < l; i++) {
        handleItem(items[i]);
    }
}

// handles the dropped item, could be a DataTransferItem
// so we turn all items into files for easier handling
function handleItem(item) {
    // get file from item
    var file = item;
    if (item.getAsFile && item.kind == 'file') {
        file = item.getAsFile();
    }

    handleFile(file);
}

// now we're sure each item is a file
// the function below can test if the files match
// our expectations
function handleFile(file) {
    /*
  // you can check if the file fits all requirements here
  // for example:
  // if file is bigger then 1 MB don't load
  if (file.size > 1000000) {
    return;
  }
  */

    // if it does, create a cropper
    createCropper(file);
}

// 3. Create the Image Cropper
// - create an element for the cropper to bind to
// - add the element after the drop area
// - creat the cropper and bind the remove button so it
//   removes the entire cropper when clicked.

// create an Image Cropper for each passed file
function createCropper(file) {
    // create container element for cropper
    var cropper = document.createElement('div');

    // insert this element after the file drop area
    fileDropArea.parentNode.insertBefore(cropper, fileDropArea.nextSibling);

    // create a Slim Cropper
    Slim.create(cropper, {
        ratio: '16:9',
        defaultInputName: fileInputName,
        didInit: function () {
            // load the file to our slim cropper
            this.load(file);
        },
        didRemove: function () {
            // detach from DOM
            cropper.parentNode.removeChild(cropper);

            // destroy the slim cropper
            this.destroy();
        },
    });
}

// 4. Disable the file input element

// hide file input, we can now upload with JavaScript
fileInput.style.display = 'none';

// remove file input name so it's value is
// not posted to the server
fileInput.removeAttribute('name');

To run the script either:

Paste the script after the file drop area or just before the closing body tag;
Run the script in a DOMContentLoaded callback;
Run the script in a jQuery ready() handler;

For the above script to function you’ll have to embed Slim Image Cropper on your web page. Of course with some tweaks to the createCropper function the above script can be used with other croppers as well.

In this example I use the global version of the script, but the createCropper function can easily be rewritten to work with jQuery as you can see below.

Literally replace Slim.create(cropper, with $(cropper).slim( and you’re good to go.

Create Thumbnails With PHP

2016-11-03T00:00:00Z

If you’ve got photo galleries on your website or need to generate avatars from uploaded profile pictures you’ll most likely want to create thumbnails. In this article we’ll look at a function that handles various image types and resizes them to a set width and height.

Want to get the code and get back to your project? Download the script here.

For this article I’ll assume you’ve got some images uploaded on your PHP server. The tutorial will not discuss uploading files to the server. Alright. Images ready? Launch your editor and let’s do some coding!

PHP has a long list of functions that can load images. It has one function for each image type. As it’s really cumbersome to have a thumbnail function per image type our mission is to write one function to handle all the usual image types.

We’ll go with JPEGs, PNGs and Cats. I mean GIFs. For those we’ll need the following PHP methods:

imagecreatefromjpeg & imagejpeg
imagecreatefrompng & imagepng
imagecreatefromgif & imagegif

Our steps:

Load the image (using the correct PHP function)
Create a thumbnail by duplicating the image and resizing it
Save the thumbnail to disk (using the correct PHP function)

This gives us the following script. It’s well documented so each sub-step is explained.

// Link image type to correct image loader and saver
// - makes it easier to add additional types later on
// - makes the function easier to read
const IMAGE_HANDLERS = [
    IMAGETYPE_JPEG => [
        'load' => 'imagecreatefromjpeg',
        'save' => 'imagejpeg',
        'quality' => 100
    ],
    IMAGETYPE_PNG => [
        'load' => 'imagecreatefrompng',
        'save' => 'imagepng',
        'quality' => 0
    ],
    IMAGETYPE_GIF => [
        'load' => 'imagecreatefromgif',
        'save' => 'imagegif'
    ]
];

/**
 * @param $src - a valid file location
 * @param $dest - a valid file target
 * @param $targetWidth - desired output width
 * @param $targetHeight - desired output height or null
 */
function createThumbnail($src, $dest, $targetWidth, $targetHeight = null) {

    // 1. Load the image from the given $src
    // - see if the file actually exists
    // - check if it's of a valid image type
    // - load the image resource

    // get the type of the image
    // we need the type to determine the correct loader
    $type = exif_imagetype($src);

    // if no valid type or no handler found -> exit
    if (!$type || !IMAGE_HANDLERS[$type]) {
        return null;
    }

    // load the image with the correct loader
    $image = call_user_func(IMAGE_HANDLERS[$type]['load'], $src);

    // no image found at supplied location -> exit
    if (!$image) {
        return null;
    }


    // 2. Create a thumbnail and resize the loaded $image
    // - get the image dimensions
    // - define the output size appropriately
    // - create a thumbnail based on that size
    // - set alpha transparency for GIFs and PNGs
    // - draw the final thumbnail

    // get original image width and height
    $width = imagesx($image);
    $height = imagesy($image);

    // maintain aspect ratio when no height set
    if ($targetHeight == null) {

        // get width to height ratio
        $ratio = $width / $height;

        // if is portrait
        // use ratio to scale height to fit in square
        if ($width > $height) {
            $targetHeight = floor($targetWidth / $ratio);
        }
        // if is landscape
        // use ratio to scale width to fit in square
        else {
            $targetHeight = $targetWidth;
            $targetWidth = floor($targetWidth * $ratio);
        }
    }

    // create duplicate image based on calculated target size
    $thumbnail = imagecreatetruecolor($targetWidth, $targetHeight);

    // set transparency options for GIFs and PNGs
    if ($type == IMAGETYPE_GIF || $type == IMAGETYPE_PNG) {

        // make image transparent
        imagecolortransparent(
            $thumbnail,
            imagecolorallocate($thumbnail, 0, 0, 0)
        );

        // additional settings for PNGs
        if ($type == IMAGETYPE_PNG) {
            imagealphablending($thumbnail, false);
            imagesavealpha($thumbnail, true);
        }
    }

    // copy entire source image to duplicate image and resize
    imagecopyresampled(
        $thumbnail,
        $image,
        0, 0, 0, 0,
        $targetWidth, $targetHeight,
        $width, $height
    );


    // 3. Save the $thumbnail to disk
    // - call the correct save method
    // - set the correct quality level

    // save the duplicate version of the image to disk
    return call_user_func(
        IMAGE_HANDLERS[$type]['save'],
        $thumbnail,
        $dest,
        IMAGE_HANDLERS[$type]['quality']
    );
}

Using this script you can now for example generate square 160 by 160 pixel thumbnails with the following command.

createThumbnail('profile.jpg', 'profile_thumb.jpg', 160);

If you don’t mind your image being skewed you can also supply the fourth argument (which is the output height). The script will then force the output size to the given given width & height values. See the example below.

createThumbnail('sunset.jpg', 'sunset_thumb.jpg', 160, 160);

That’s it!