Matthew Shields | Leeds based Web Developer

Using Optional Chaining and Nullish Coalescing Operator in JavaScript

info@matthewshields.co.uk — Sun, 15 Aug 2021 00:00:00 GMT

Optional chaining is a great feature in order for you to streamline checks that you need to have in your code, or looking for the presence of elements and data, especially nested data multiple levels in!

It's still a relatively new feature and only got more widespread browser support around early 2020. As my work has included more API driven and JAMstack development, it's really shown how useful it is to me personally. Since then my mind has been blown away with just how much cleaner it can make your code, and make it easier to write too 🤯

What is so good about Optional Chaining?

In short I think the best things about Optional Chaining are:

Write less code
Code is easier to read

I think though to really see how neat this feature is, let's first take a look at what you might have to do without it. Let's take the example of a made up JavaScript object that you may be working with / be provided with, in this case me pretending that I'm back at university and enrolled in a course (if only...).

const api_response = {
  user: {
    name: {
      firstName: "Matthew",
      lastName: "Shields"
    },
    currentCourse: {
      courseDetails: {
        name: "Visual Communication",
        location: "Leeds Art University"
      },
      tutorDetails: {
        name: "Mr G Tansley",
        email: "g.t@leedsmadeupemail.com"
      }
    }
  }
};

Now, if we wanted to get my tutor's name and email out of this data for use somewhere else, we could do something like this:

const tutorName = api_response.user.currentCourse.tutorDetails.name;
// returns: "Mr G Tansley"

const tutorEmail = api_response.user.currentCourse.tutorDetails.email;
// returns: "g.t@leedsmadeupemail.com"

This would work for my example. We have data that matches what's needed, so no horrible browser console errors, yay! But what if I wasn't currently enrolled in any courses? That will quickly change, and you will end up with something along the lines of 'Uncaught TypeError: Cannot read property 'Property Names' of undefined'.

const api_response = {
  user: {
    name: {
      firstName: "Matthew",
      lastName: "Shields"
    },
    currentCourse: false
  }
};

const tutorName = api_response.user.currentCourse.tutorDetails.name;
// Uncaught TypeError: Cannot read property 'name' of undefined

const tutorEmail = api_response.user.currentCourse.tutorDetails.email;
// Uncaught TypeError: Cannot read property 'email' of undefined

The reason that we are getting this error is because when I was pulling the details before, I was doing this in a very fragile way that was working under the presumption that the data would always be there. As a general rule this isn't the best practice and you should put checks in to make sure your code will work across all different situations - like me being a graduate rather then a student.

How could we stop these errors from happening?

One way to stop these errors would be to check for the presence of every level in the data before we finally access the nested property. This does work and does make your checks a lot more robust - you aren't going to catch that Uncaught TypeError from the last example.

However as you can see, it comes at the price of code legibility and well, having to code more! If you were to have a whole bunch of these throughout your codebase and an API structure change happened, you can imagine how much of a pain that could be.

let tutorName = false;

if(
  api_response && 
  api_response.user && 
  api_response.user.currentCourse && 
  api_response.user.currentCourse.tutorDetails && 
  api_response.user.currentCourse.tutorDetails.name
) {
  tutorName = api_response.user.currentCourse.tutorDetails.name;
}

It's worth noting that there are actually alternatives to writing code like this independent to Optional Chaining. For example, Lodash's _.get() utility - this example is just for demonstrative purposes and purposefully Vanilla JavaScript and library-less.

Optional Chaining to the rescue!

Now we've set the scene of what you may need to do without it, let's dig into how optional chaining could help us. This works by replacing our . chaining with ?. optional chaining. Wherever this is used it creates something along the lines of an inline if-statement, where it will only continue if there is a none-null reference preceding it. In the event that it fails at any of the optional chaining points, it will exit there and return undefined.

As you can see in the next two examples, whether the properties exist in the data or not, we are either returning the value that we are after (my current tutor's name), or a consistent `undefined` value if not. This allows you to then do simple checks later against the tutorName variable before using it.

const api_response = {
  user: {
    name: {
      firstName: "Matthew",
      lastName: "Shields"
    },
    currentCourse: {
      courseDetails: {
        name: "Visual Communication",
        location: "Leeds Art University"
      },
      tutorDetails: {
        name: "Mr G Tansley",
        email: "g.t@leedsmadeupemail.com"
      }
    }
  }
};

const tutorName = api_response?.user?.currentCourse?.tutorDetails?.name;
// returns: "Mr G Tansley"


const api_response = {
  user: {
    name: {
      firstName: "Matthew",
      lastName: "Shields"
    },
    currentCourse: false
  }
};

const tutorName = api_response?.user?.currentCourse?.tutorDetails?.name;
// returns: undefined

In my opinion, this has really helped neaten this up and made it a lot easier to write, read and maintain in the future when compared to the large chained if statement. It's definitely a lot better than writing code which will receive errors by not doing these sorts of checks.

Nullish Coalescing Operator as your backup

I mentioned how the optional chaining operator would return undefined if it failed at any of its checks, but what if you don't want undefined to be your backup value?

You could do a check after that point and set it to be a different value, however this may conflict with your use of a constant variable and adds more code. What you could do though is pair the Optional Chaining Operator with the Nullish Coalescing Operator like so:

const api_response = {
  user: {
    name: {
      firstName: "Matthew",
      lastName: "Shields"
    },
    currentCourse: false
  }
};

const tutorName = api_response?.user?.currentCourse?.tutorDetails?.name ?? "Current Tutor N/A";
// returns: "Current Tutor N/A"

In this event when the Optional Chaining Operator fails and returns undefined, the Nullish Coalescing Operator kicks in and so your backup value is set.

You might be thinking though - this looks similar to the Or operator || - why can't I just use that? The key difference is that the Nullish Coalescing Operator responds to a smaller set of conditions, specifically only when the value is null or undefined. If you were to use the Or Operator and the value on the left was valid, but equated to 0, "", false etc then you may still end up using your backup value unintentionally.

It doesn't mean that you may not ever use the Or Operator, in some situations that might be what you require. As a general default though I would use the Nullish Coalescing Operator first and change only when required.

But what if I don't work with APIs or data?

The data situation that we have looked at so far is just a context that I think demonstrates the concept of Optional Chaining in an easy to understand way. Even if you don't work with API responses I can guarantee that there are still ways that it can help you.

If you remember the concept is in the event of a null reference preceding it it will stop and not continue, there are multiple ways that you can use this:

Get element attribute

// -------------------------------
// With Optional Chaining
// -------------------------------
const heroImageSrc = document.getElementById('hero-image')?.getAttribute('src');
// If the #hero-image element exists then get its src attribute else undefined


// -------------------------------
// Without Optional Chaining
// -------------------------------
const heroImage = document.getElementById('hero-image');
const heroImageSrc = heroImage ? heroImage.getAttribute('src') : undefined;
// First get the #hero-image element then check if that exists before getting its src attribute or undefined

Get first element in array

Note: Notice that you aren't just adding a ? preceding a usual . the optional chaining operator is ?. - so add both before your square brackets!

// -------------------------------
// With Optional Chaining
// -------------------------------
const firstItemInArray = array_data?.[0];
// Return the first item in array if exists or undefined


// -------------------------------
// Without Optional Chaining
// -------------------------------
const firstItemInArray = (array_data.length > 0) ? array_data[0] : undefined;
// First check if there are any items in the array, then if so get the first item else undefined

Call function only if it exists

const api_response = {
  user: {
    name: {
      firstName: "Matthew",
      lastName: "Shields"
    },
    currentCourse: {
      courseDetails: {
        name: "Visual Communication",
        location: "Leeds Art University"
      },
      tutorDetails: {
        name: "Mr G Tansley",
        email: "g.t@leedsmadeupemail.com"
      }
    }
  },
  helloWorld() {
    console.log('hello world');
  }
};

// -------------------------------
// With Optional Chaining
// -------------------------------
api_response?.helloWorld?.();
// If the object method exists then call it inline


// -------------------------------
// Without Optional Chaining
// -------------------------------

if(api_response && typeof api_response.helloWorld === "function"){
  api_response.helloWorld();
}
// First check if the method exists then seperately call that function

What can't you do with it?

One of the biggest things that you cannot do with this comes down to the rule that you cannot use it on the left hand side of any statements! So what does that mean? You can't set a property value only if it exists without doing a check first. Let's see an example of something that you can't do:

const api_response = {
  user: {
    name: {
      firstName: "Matthew",
      lastName: "Shields"
    },
    currentCourse: false
  }
};

api_response?.user?.name?.firstName = "Matt";
// returns: Uncaught SyntaxError: Invalid left-hand side in assignment

What you can do is still use the optional chaining for a much tidier if statement condition. Then, safe in the knowledge that it will only run in the event the last property exists, separately set that value.

const api_response = {
  user: {
    name: {
      firstName: "Matthew",
      lastName: "Shields"
    },
    currentCourse: false
  }
};

if(api_response?.user?.name?.firstName) {
  api_response.user.name.firstName = "Matt";
}
// returns: "Matt"

Requirements and Browser Support

The support coverage for this feature has a really good coverage at this time, covering all major browsers with the exception of Internet Explorer.

Optional Chaining

Nullish Coalescing Operator

If your support requirements aren't covered by this (I sometimes am still supporting IE myself), it's important to note that Babel can transpile Optional Chaining and so you can still use this despite that!

If you are working with Node then you will require Node 14 minimum to utilise this.

Tip: Are you using Netlify Serverless Functions?

As a little pointer as I discovered myself recently, Netlify Serverless Functions by default are at the time of writing using Node 12, however you can easily change this by adding a variable to site settings trough the Netlify UI as described here.

AWS_LAMBDA_JS_RUNTIME = nodejs14.x

Wrapping it up on this one

Apart from the fact that I've said Optional Chaining outloud proof-reading this enough times that they don't even sound like real words anymore - I am genuinely excited about using this feature more.

As I said at the beginning of this, my work has started to integrate with APIs more, and so the variable data that comes with that has become more a part of my work as well. Even over the last couple of months this has made a marked improvement to my experience.

But what about you? Have you had differing experiences or are there any gotchas that I am yet to come across? Let me know if there are!

How to ask for help debugging the right way

info@matthewshields.co.uk — Fri, 08 May 2020 00:00:00 GMT

If anyone was to tell me that they've never needed help debugging something in their career, I think a suspicious glare would be my only response. We've all needed to ask someone to help us at some time or other, this is healthy as it allows you to learn new approaches to problems and become a better developer. There are however good ways to ask for this help, and bad ways.

I think the foundations of what makes a good way to ask for help is the same as asking for help in life, understanding that it is a two-way relationship and having respect for each other.

Respect for each other

In debugging I believe this mutual respect includes being aware of the other person's time. I've found people in the development community, specific to my team or the community as a whole, are a helpful bunch and will try to help where they can.

People however are still busy and have their own projects, clients and a life outside coding. You can show respect for this in three key ways:

Ask for their help – don't assume that they are able to, preface this as a question where they are able to respond honestly if they can't currently help.
Provide a time frame – is this an urgent issue, or is it something that could be responded to in the next few days or weeks? Providing this information will help them know if they can help when required.
Provide context of the issue – by giving as much context of the issue as possible, this will allow time to be spent solving the problem at hand rather than gathering the information, making it more efficient for everyone involved.

How to provide context of the issue

What do I mean by providing context of the issue? Sometimes I have been asked unspecific questions like 'This [insert thing] isn't working - can you help?'. The questions I have to go back with is the context that I mean. Where possible, this should be provided upfront to help with efficiency and create less work for the person you're asking.

Obviously the range of things that you might need help debugging is near infinite, but here is my general guide to the type of information that you can give which will help both of you come to a solution as quickly as possible.

What is the functionality you are having issues with?
Is it a specific component? A particular function? Or even a singular line of code? Make sure that the person you are asking for help from knows the exact scope of what it is that you need help with.
What is the expected behaviour?
Try to give details of how you expect this to behave, whether that's in a script or responding to user behaviour. Sometimes its easy to forget what is obvious when you know something, but the other person will probably be coming into this completely cold, so I always go with the approach of being specific and cut out the chance of assumptions.
What is the behaviour that you are currently experiencing?
As much information as possible the better, console errors, debugging information, code snippets. Use your best judgement about what you can give to try to help them help you, more information won't hurt at this point. One that I always try to share if I'm looking at a function or component is also sharing what's passed into it as well.
What have you tried to solve this so far?
This will demonstrate your thought process and in my experience has been the question that has provided the most learning potential, as the person helping may be able to demonstrate why previous attempts didn't solve the issue. It also shows that you have tried to solve it yourself before asking for help.
Where can I see the issue?
Providing a staging link and link to a code repo etc, along with a pointer to the specific files or functions to start looking at, rather than having to trace the issue back themselves, will speed things up greatly.

An example of asking for help, the right way

Using a recent real world issue where I was asked for help, I have turned it into an example that would have helped me speed up solving the issue.

I have purposefully chosen an example that isn't a very narrow issue. With specific debugging information, this could be fixed just from reading the message. I want to share an example of where when you are struggling with an approach even some base level information can really help.

Hey Matt.

I was wondering if you had any time to help me debug an issue I was having with a carousel I am currently working on. It is scheduled to go into testing at the start of next week, so if there is any chance that you could take a look in the next couple of days it would be much appreciated, if this isn't possible then just let me know and I can reach out to other members of the team.

It is supposed to skip to the specific slide when you click on the navigation item and reset the autoplay timer so that it doesn't progress automatically for another 8 seconds for just the carousel being navigated on, however currently when I click on the navigation the autoplay timer is being reset for all carousels on the page.

I have tried moving the global variable with the setInterval within the each loop when I create it, however this stopped the clearInterval from working at all as I no longer had access to the global variable to clear it. This gave me the error: Uncaught ReferenceError: globalTimer is not defined

I have also tried storing the setIntervals in an array but I couldn't figure out how to refer back to the corrosponding setInterval depending on the carousel being navigated.

I know that I need a way of having a variable in scope to call this clearInterval against but I'm unsure of how to achieve this.

You can see the current behaviour on the staging site http://example.com/, and you can see the carousel modules in the repo here http://example.com/repo/assets/js/modules/carousel.js. The example where I tried to move into an array is on the branch feature/carousel-array-method.

I hope this is enough information but if there is anything else that you would need to know before being able to take a look then please just let me know and I will get it prepared.

Thanks,
Erm... Matt?

If I had received this message without any additional information gathering, I would have known what the issue was, what we needed to achieve, what had previously been tried, where I could see the issue and when they needed a solution for.

In this real world example, I actually couldn't help the person immediately, but this initial ask and information provided would have allowed me to start looking at the issue without them needing to be available at the same time. Alternatively if the time frame had been immediate, I would have known that I couldn't help and they would have been able to approach an alternative person.

Making time for understanding

The final step of any help that you have received debugging is to invest some of your time into understanding the solution. The problem you were having has (hopefully) now been solved, and you may have the urge to move onwards, however you must fight this and make sure that you take time for this step.

This is the part that makes sure that you use the opportunity to learn and take on the knowledge shared, otherwise you may well end up at the same issue in the future. Personally I also think this is the final way of showing appreciation to those who have invested time into helping you, making the most out of the time they invested.

Whenever people help me I always make sure that I take time to do this, and wherever possible I will drop them a note after the fact to say thanks and let them know that it has helped and how. Whenever someone has told me that my help has made something make more sense to them, however big or small, it has been really rewarding to know that, so I always try to make sure I do the same for people who help me.

Side note update

After showing this post to my girlfriend, who is an amazing writer and helps me by proofreading my writing, it became clear that this isn't just an approach that can be used with development. I sometimes think in a very specific development led mindset, but the foundations of this approach are also helpful when asking for assistance with any aspects of life. If this helps you with your debugging queries, try using it in other aspects of your life as well.

Using React Helmet to Manage the Document Head and SEO tags

info@matthewshields.co.uk — Mon, 13 Apr 2020 00:00:00 GMT

One of the first things that I had to figure out when working with React was how to be able to manage the elements outside the React application, namely the contents of the . As you build targeting an element within the body, how do you easily manage the elements from within React?

The document head serves some very important uses:

Providing context as you move between different pages.
Search Engine Optimisation (SEO) through elements such as the title and meta description.
Avoiding Google duplicate content penalties with an appropriate canonical tag.
Controlling the images used when your page is shared on social media for maximum impact.
Providing additional information to services through schema data.
As well as so many more that I can't list them all - luckily Josh Buchea has!

A common issue with React sites in production sites is the lack of unique meta titles and descriptions, with generic text being applied throughout the site.

I work at an agency which specialises in SEO, so there's always been an importance for this in my professional work and I knew this was something that I would require if I was to bring React into our commercial stack. This meant it was something that I needed to be able to easily manage, but also have pass the SEO requirements.

The NFL to the rescue: react-helmet

Although not into sports of any variety, consider me a fan for this React component from the development team at the NFL. 'react-helmet' provides a very accessible way to control any elements of the document head including title, base, meta, link, script, noscript, and style tags within any level of your React application.

You can add these tags by first importing react-helmet and then passing as child elements the tags that you are wanting to appear in the document head. You can see in this example from their GitHub page, how they are passing JSX markup as a child of the component for them to be added.

import React from "react";
import {Helmet} from "react-helmet";

class Application extends React.Component {
  render () {
    return (
        <div className="application">
            <Helmet>
                <meta charSet="utf-8" />
                <title>My Title</title>
                <link rel="canonical" href="http://mysite.com/example" />
            </Helmet>
            ...
        </div>
    );
  }
};

One of the amazing things about react-helmet is its ease of use, providing much-needed functionality for a technically performant site, without asking much from the developer to integrate.

Where do I use it?

You're not actually putting the code into the document head, so where do you put it within the React application?

You can add it into any component and react-helmet will work from there. The approach that quite a lot of sites or frameworks using react-helmet take is to create an SEO component. This component, when passed the node data for the particular page or post you are on, will take the title and description etc and have a generic component that creates the tags there.

import React, { Component } from "react";
import Helmet from "react-helmet";
import urljoin from "url-join";
import config from "../../../data/SiteConfig";

class SEO extends Component {
  render() {
    const { postNode, postPath, postSEO } = this.props;
    let title;
    let description;
    let image;
    let postURL;

    if (postSEO) {
      const postMeta = postNode.frontmatter;
      ({ title } = postMeta);
      description = postMeta.description
        ? postMeta.description
        : postNode.excerpt;
      image = postMeta.cover;
      postURL = urljoin(config.siteUrl, config.pathPrefix, postPath);
    } else {
      title = config.siteTitle;
      description = config.siteDescription;
      image = config.siteLogo;
    }

    return (
      <Helmet>
        <title>{title}</title>
        <meta name="description" content={description} />
        <meta name="image" content={image} />

        <meta property="og:url" content={postSEO ? postURL : blogURL} />
        {postSEO ? <meta property="og:type" content="article" /> : null}
        <meta property="og:title" content={title} />
        <meta property="og:description" content={description} />
        <meta property="og:image" content={image} />
      </Helmet>
    );
  }
}

export default SEO;

A simplified example from the SEO component included in gatsby-advanced-starter.

This approach has worked really well for me as it means that I don't have to have the code in each of my templates and has ensured consistency across the site. But what if you need something custom on a page which your generic component doesn't cater for?

Nested instances

A great feature of react-helmet is that it will deal with multiple instances with ease, combining them. This means that you can add additional tags in the individual template or component where you require it, such as JSON schema. Note that it will give priority to the last instance whenever there are duplicate properties, so you can overwrite anything, dictated by the order of where it was defined.

What could you use this for? If you wanted to have a different favicon to show the status of a process such as an upload being paused, or a title change when displaying content in a modal. This would give you the ability to improve user experience, giving the user additional visual cues.

In the example below, imagining a podcast player, the page would standardly display the favicon as defined in the SEO component. When the podcast player's state indicates that it is playing or paused (because they came after the SEO component), the defined favicon would be overwritten.

render() {
  return (
    <div>
      // The generic SEO component included in all templates
      <SEO />

      // Two different overwrites dependent on component state
      {this.state.player_state === 'playing' &&
        <Helmet>
          <link rel="icon" href="./playing-favicon.png" sizes="16x16" type="image/png" />
        </Helmet>
      }
      {this.state.player_state === 'paused' &&
        <Helmet>
          <link rel="icon" href="./paused-favicon.png" sizes="16x16" type="image/png" />
        </Helmet>
      }
      ...
    </div>
  );
}

Another Example: JSON Schema

When wanting to add JSON schema to your site, of which there is a huge variety, this can be done in a very similar way. If you prepare your data in a variable, you can JSON.stringify your finalised variable before passing it into the Helmet component within the script tag.

export default function Template({ data }) {

  const schema = {
    "@context": "http://schema.org/",
    "@type": "PodcastEpisode",
    "url": "https://examplepodcast.dev"+data.path,
    "name": data.title,
    "datePublished": data.formattedDate,
    "timeRequired": data.length,
    "description": data.description,
    "associatedMedia": {
      "@type": "MediaObject",
      "contentUrl": data.audio
    },
    "partOfSeries": {
      "@type": "PodcastSeries",
      "name": "Example Dev Podcast",
      "url": "https://examplepodcast.dev/"
    }
  };

  const JSONschema = JSON.stringify(schema)

  return (
    <div>
      <SEO />
      <Helmet>
        <script type="application/ld+json">{JSONschema}</script>
      </Helmet>
    </div>
  )
}

SEO Requirements for the document head

Now that you know how to manage your document head using react-helmet, what should you be adding into it? As previously stated there are a huge variety of tags that can be added, but my advice to you would be to ensure that at a minimum your site includes the following:

Meta Title - e.g. Page Title | Site Name, aim to keep it under 60 characters.
Meta Description - a more expansive description of what the page content is about. Aim to keep within about 160 characters.
Canonical Tag - set the definitive URL for the page to avoid duplicate content penalties, this can happen if your site is accessible from multiple URLs (with and without trailing slash, with query strings etc)
Favicon - this makes it easier for users to identify your site in a collection of tabs (if you browse like I do) and makes it easier to return to your site.
Robots (for some pages) - although not required across the site, you would do well to identify pages that you may not want indexing, such as contact form 'thank you' pages.
Breadcrumb JSON Schema - for sites with multiple levels, providing search engines this schema will provide greater context for the structure of your site. If this is the case I would also recommend that you provide this visually for users as well.

And an honorary mention:

Social Meta Tags - although not strictly SEO relevant, defining how your site will appear when shared on social can greatly increase the chance of people clicking through to your site and this is obviously good!

In addition to these I would also look into additional JSON schema, to provide search engines further information about your content. An example of this was the podcast episode schema data example I showed earlier. Here are some good schemas that you might want to take a look at adding if appropriate:

Organisation - This gives you the opportunity to define things like the company logo and contact details (used in company details in Google Knowledge Graph).
Product - For e-commerce sites, providing detailed information of the product to search engines will help improve search listing data.
Article - This lets you provide context around your article such as when it was published and author data.
Local Business - To help users find details about your business such as address, phone number and email address, you can use this schema.

Time to start using react-helmet

Having covered the how, what and why, I hope this has convinced you that if you aren't already using react-helmet to manage your document head, then it might be time to start. From SEO to user experience there are lots of benefits to taking the tags included in the document head into consideration, and now they should be easier for you to implement.

Netlify CMS Variable Types and Gatsby

info@matthewshields.co.uk — Wed, 08 Apr 2020 00:00:00 GMT

I have created a simplified repository based off of the gatsby-advanced-starter with a working example of this which might be helpful to refer to.

This post will cover:

Setting up Variable Types fields in Netlify CMS
Defining field types in Gatsby using createSchemaCustomization API
Querying Variable Type fields in GraphQL
Formatting markdown content with createFieldExtension
Displaying Variable Type queried data in React

My issue: The static nature of my Netlify CMS content

I have historically worked with WordPress for my CMS sites and love the flexibility provided to me by using Advanced Custom Fields, more specifically with it's 'Flexible Content' approach. This allows you to build pages using any combination of components as required, without resorting to using inefficient page builder plugins.

When building version one of my site I knew I wanted pages to have different content on them. For these bespoke pages I actually made them using a template file for each one. Longer term, I don't want to do this - if I have a CMS then I'm going to use the CMS. Not every project can have someone making a new file for every page creation after all.

TL;DR - I want to use the Netlify CMS to be able to piece together pages with a flexible use of components, without creating new template files for each combination still being built with Gatsby.js

Introducing Netlify CMS Variable Types

After looking into the widget types built into Netlify CMS I couldn't find anything that quite catered for my needs. The closest was 'List' which gives you the ability to add a repeatable set of fields, but these fields are static and the same for each repetition. I could use 'List' and add every instance of field along with ability to pick which component to use, but as there isn't any conditional logic, this would become awful to use really fast.

On the Netlify CMS site they have a list of their beta features and in there I found exactly what I was after, variable types. This feature provides the ability to use a repeater like with 'List' but assign different fields to each type.

Variable types was straight-forward to set up once I knew that it existed. Unfortunately, that came after a couple of hours of trying to build my own version of the ACF flexible content functionality as a Netlify CMS custom widget. But that's given me ideas for another challenge so nothing wasted!

 
collections:
  - name: pages
    label: "Page"
    folder: "content/pages"
    media_folder: ''
    public_folder: ''
    create: true
    slug: "{{year}}-{{month}}-{{day}}-{{slug}}.md"
    fields:
      - { label: "post_type", name: "post_type", widget: "hidden", default: "page" }
      - { label: "Title", name: "title", widget: "string" }
      - { label: "Short Description", name: "short_description", widget: "string" }
      - { label: "Publish Date", name: "date", widget: "datetime" }
      - { label: "Cover Image", name: "cover", widget: "image", required: false }
      - { label: "Slug", name: "slug", widget: "string" }
      - label: 'Page Section'
        name: 'sections'
        widget: 'list'
        types:
          - label: 'Text Block'
            name: 'text_block'
            widget: object
            fields:
              - { label: Title, name: title, widget: string }
              - { label: Text, name: text, widget: markdown }
          - label: 'Carousel'
            name: 'carousel'
            widget: object
            fields:
              - { label: Title, name: title, widget: string }
              - { label: Text, name: text, widget: markdown }
              - label: 'Images'
                name: images
                widget: list
                fields:
                  - { label: "Image", name: "image", widget: "image", required: false }
                  - { label: Image Description, name: alt, widget: string }
          - label: 'Block List'
            name: 'block_list'
            widget: object
            fields:
              - { label: Title, name: title, widget: string, required: false }
              - { label: Text, name: text, widget: markdown, required: false }
              - label: 'Blocks'
                name: blocks
                widget: list
                fields:
                  - { label: Title, name: title, widget: string }
                  - { label: Text, name: text, widget: markdown }

This then gives me the exact ability I wanted in the CMS as you can see above. Half the challenge done, now to get this back into my Gatsby build and into the site.

How to get the variable data with GraphQL?

The next step was figuring out how the GraphQL query would work with it, with the fact I don't know what fields a given page would be querying, as I wouldn't know which components had been used. Initially I thought this would be quite simple and queried for all fields across all of the various types, and it worked (for a while). Where this quickly fell down though, was that if there wasn't at least one page with an instance of a given type, Gatsby couldn't infer what type of data should be present.

A solution to this could be to have a page that had an example of all components on it, but that isn't something you want your site to be dependent on. If you were to add a new type or accidentally remove one of them your site is going to be unbuildable.

Using createSchemaCustomization API and createTypes to define field content type

What you can do to get around this issue properly is use Gatsby's createSchemaCustomization API to manually define what content type Gatsby should expect from a given field, rather than it requiring it to exist to be inferred. Honestly, I found the Gatsby documentation a little confusing on this one and it took me a while to get it but once you have it up and running it makes sense.

You can use this API in the gatsby-node.js file. You will need to make a call to the createSchemaCustomization API and define each of your fields (taking care to make sure that you note which of your fields are repeatable, i.e. List widgets), as you will need to define these as expecting to be arrays. Heads up here to remember that you are working in your gatsby-node.js file, there isn't the hot-reloading like most of the project so don't forget that you will need to restart when you make changes.

Given my example config.yml from above and the resulting markdown file I have structured my type definitions like so:

MarkdownRemarkFrontmatter - I tell it to expect an array of the fields as defined in Sections.
Sections - I tell this to expect the fields that I have used in my config.yml - note that you are defining the actual fields, I recommend referring to your created markdown file when doing this.
List Widget fields - When a List widget has been used I define these fields in their own type definition, where they can then be included within the square brackets to tell Gatsby to expect an array.

exports.createSchemaCustomization = ({ actions }) => {
    const { createTypes } = actions
    const typeDefs = `
  
      type CarouselImages {
        image: File
        alt: String
      }
      
      type BlockList {
        title: String
        text: String
      }
  
      type Sections {
        type: String
        title: String
        text: String
        images: [CarouselImages]
        blocks: [BlockList]
      }
  
      type MarkdownRemarkFrontmatter {
        sections: [Sections]
        cover: File @fileByRelativePath
      }
  
    `
    createTypes(typeDefs)
  }

Building your GraphQL query

Now that we have our type definitions in place we can build the query for the page. I preferred building this using fragments which made it a lot easier for me to organise these in my mind, ensuring that I have the fields that I wanted for each variable type. Don't worry if you have duplicate fields in each fragment, such as title or text, these will be compiled into a single query.

export const pageQuery = graphql`

  fragment Carousel on Sections {
    type
    title
    text
    images {
      image {
        childImageSharp {
          fluid(maxHeight: 700, quality: 100) {
            ...GatsbyImageSharpFluid_withWebp
          }
        }
      }
      alt
    }
  }

  fragment TextBlock on Sections {
    type
    title
    text
  }

  fragment BlockList on Sections {
    type
    title
    text
    blocks {
      title
      text
    }
  }

  query PageBySlug($slug: String!) {
    markdownRemark(fields: { slug: { eq: $slug } }) {
      html
      timeToRead
      excerpt
      frontmatter {
        title
        short_description
        date
        cover {
          childImageSharp {
            fluid(maxHeight: 700, quality: 100) {
              ...GatsbyImageSharpFluid_withWebp
            }
          }
        }
        sections {
          ...TextBlock
          ...Carousel
          ...BlockList
        }
      }
      fields {
        slug
        date
      }
    }
  }
  
`;

When this query is returned I have an array of objects, one for each entry of a variable type, as you can see in this screenshot. Perfect! We now have a flexible query that will handle as many instances as needed, in any order or without all types being present. Just what I needed!

It's all Markdown-hill from there

The eagle eyed of you might notice the lack of HTML formatting within the text field, at this point it's returning the raw markdown content, this is less than ideal but luckily can be resolved, using... Field Resolvers (ba dum tsh). What we will first need to do is install the package remark-html:

npm install remark-html

Then, include a couple of modules that will help convert the markdown into the HTML we want:

const remark = require(`remark`)
const html = require(`remark-html`)

Finally, return back to the createSchemaCustomization function in the gatsby-node.js file from earlier. Using the example from Gatsby's documentation you can see how to add a new field extension that will take the input of the field content, convert from markdown and then return the final HTML. Once your field resolver is created you can then indicate which fields to use it on by appending @md to the expected field type.

exports.createSchemaCustomization = ({ actions }) => {
  actions.createFieldExtension({
    name: "md",
    args: {
      sanitize: {
        type: "Boolean!",
        defaultValue: false,
      },
    },
    extend(options, prevFieldConfig) {
      return {
        args: {
          sanitize: "Boolean",
        },
        resolve(source, args, context, info) {
          const fieldValue = context.defaultFieldResolver(
            source,
            args,
            context,
            info
          )
          const shouldSanitize =
            args.sanitize != null ? args.sanitize : options.sanitize
          const processor = remark().use(html, { sanitize: shouldSanitize })
          return processor.processSync(fieldValue).contents
        },
      }
    },
  })

  const { createTypes } = actions
  const typeDefs = `

    type CarouselImages {
      image: File @fileByRelativePath
      alt: String
    }
    
    type BlockList {
      title: String
      text: String @md
    }
  
    type Sections {
      type: String
      title: String
      text: String @md
      images: [CarouselImages]
      blocks: [BlockList]
    }

    type MarkdownRemarkFrontmatter {
      sections: [Sections]
      cover: File @fileByRelativePath
    }

  `
  createTypes(typeDefs)
}

I'm definitely interested in finding out more about field resolvers as they seem like they could be really powerful and helpful in the future. For this particular issue (as below) we are now getting our fully formatted HTML returning and ready to be used. What you will notice is that each item in the array will have all the possible fields included in it, i.e. text_block will also have images as part of it, however the value will be null so we can work with that.

Flexible Content in React

Now we have a working GraphQL query we actually want to use it in React. To do this we will need a component that we can pass sections into. This will then figure out what component type we are wanting to use and pass the individual fields into it to display on the front end.

To do this I created a new component of FlexibleContent which takes the sections input, loops through it and then uses a switch function to determine which component to use. Passing the fields that each component requires also means that it doesn't matter about the null unnecessary fields as the component won't be doing anything with them.

By passing the fields individually rather than passing the entire object, it also means that the components will be easier for us to use outside of the content of the FlexibleContent loop. This will help ensure consistency across your site.

FlexibleContent Component

import React from "react";
import TextBlock from "../TextBlock/TextBlock";
import BlockList from "../BlockList/BlockList";
import Carousel from "../Carousel/Carousel";

class FlexibleContent extends React.Component {

  choose_section(section) {
    switch(section.type) {
      case 'text_block':
        return (
          <TextBlock title={section.title} text={section.text} />
        )
        break;
      case 'block_list':
        return (
          <BlockList title={section.title} text={section.text} blocks={section.blocks} />
        )
        break;
      case 'carousel':
        return (
          <Carousel title={section.title} text={section.text} images={section.images} />
        )
        break;
      default:
        // code block
    }
  }

  render() {
    let sections = this.props.sections;
    return (
      <div>
        {sections.map((section, index) => (
          <div className="content-block" key={section.type+'_'+index}>
            {this.choose_section(section)}
          </div>
        ))}
      </div>
    );
  }
}

export default FlexibleContent;

Using the FlexibleContent Component

import React from "react";
import { graphql } from "gatsby";
import Layout from "../layout";
import FlexibleContent from "../components/FlexibleContent/FlexibleContent";

export default class PageTemplate extends React.Component {
  render() {
    const { data, pageContext } = this.props;
    const postNode = data.markdownRemark;

    return (
      <Layout>
        <FlexibleContent sections={postNode.frontmatter.sections} />
      </Layout>
    );
  }
}

Gatsby and Variable Types - One Happy Family

And there we have it, the ability to be able to flexibly build out pages using Netlify Variable Types and a single page template. This is actually powering most of the pages of my site and am looking at building out the component collection over time. I hope that this helps any of you struggling to pick up using Variable Types for the first time, I was really struggling to find any guides with how to use it with Gatsby specifically. I feel like this is my first big challenge overcome in taking this into being able to use with client projects.

If there are any issues or improvements you can feel free to make a pull request to my demo repo or get in touch with me on Twitter, and I will update this post over time too.

Tae'lur Alexis 100 days of Vanilla JS

info@matthewshields.co.uk — Wed, 08 Apr 2020 00:00:00 GMT

Setup

info@matthewshields.co.uk — Sun, 05 Apr 2020 00:00:00 GMT

About Me

info@matthewshields.co.uk — Fri, 03 Apr 2020 00:00:00 GMT

Configuration tips for Netlify CMS

info@matthewshields.co.uk — Sat, 28 Mar 2020 00:00:00 GMT

As a new user of Netlify CMS and the JAMstack approach, I've been blown away by this simple to use static CMS.

If you aren't aware of Netlify CMS it is a no-database content management system, accessed through a single page React application, which works through the creation and editing of files in Markdown, YAML or JSON to name a few options. This is a perfect partner when it comes to any number of static site generators like Gatsby, Jekkyl or NextJS thanks to their platform agnostic approach.

I would call out that Netlify CMS is not going to be powerful enough for a complex site. If you are after a CMS to power your personal site or some brochureware though, with the aim being making it easier to manage your static content, then I would definitely add it into your options to look at.

Simple but configurable

The Netlify CMS documentation gives you a great breakdown of how to get started and even a few templates for a few different site types, super helpful. So far, my entire configuration of Netlify has happened just in its config.yml file, a mark of its simplicity to pick up. There are additional areas that you may need to touch if you were to create your own Netlify CMS widgets or previews, but thats something that I'm yet to attempt but will write it up on here when I do!

Editorial Workflow

I didn't use this feature while in the initial build phase as it slows me down, but as soon as I was dealing with a live site I loved this feature. What this does is that it will create an individual branch so each piece of content that you write and allow you to save as a draft. You can enable this feature by adding this line into your config.yml file:

publish_mode: editorial_workflow

Once you have done that you will see some more options appear in your site admin. When viewing your posts you will actually only see the ones that have been fully published, to see your in progress content you will need to go to Workflow. You now get 3 different states before you can actually publish - 'Drafts', 'In Review' and 'Ready'. Once you have marked a post as being 'Ready' you will then be able to publish it, where it will be merged back into the main branch. Super easy to use but for someone like me who never writes in a single go is pretty essential to have them tucked away somewhere till I'm finished.

For my personal site, I use this to organise my notes of ideas for posts, posts that I am actively working on and ones that are ready to be published, but this might differ if you actually have a team and an editorial process!

Editorial Workflow and Git

If you happen to be using Netlify for your hosting (which I would very much recommend) and are on the free tier, just be aware that you may want to check the settings that you have for when it comes to deploy previews, a fantastic feature but depending on the scale of updates that you are making you might not want to use up all those build minutes. (Or do what I plan to as soon as I can and pay for more, but this isn't an option for everyone!)

By default editorial workflow will branch off and merge back into master, you can however change this if you want by adding the branch definition to the config.yml file. I'm currently using a pre-production branch for mine so that I can prepare multiple commits into a single pull request for auto-deployment. This is also helpful as I am currently making a lot of additions to the CMS (and refactoring) currently.

backend:
  name: github
  repo: MatthewShields/matthewshields.co.uk
  branch: pre-production # Choose the branch to update

There isn't a built in menu manager which you will be used to getting with most CMS. You can create a collection type of Settings which gives you a place to store this type of information separate to your content but also still administrated vis the CMS. In the case of a single layer navigation a List widget will be enough to do this.

  - name: settings
    label: Settings
    files:
      - file: data/settings/navigation.yml
        label: Navigation
        name: navigation
        fields:
          - label: Navigation
            name: nav_items
            widget: list
            fields:
              - {label: Label, name: label, widget: string}
              - {label: Path, name: path, widget: string}

You can then load the YAML data directly into the component that needs it in order to build your navigation, independent of page context or other things. (Simplified example below)

import YAMLData from "../../../data/settings/navigation.yml"

class Header extends Component {
  render() {
    return (
      <ul>
        {YAMLData.nav_items.map((data, index) => {
          return (
            <li className="main-nav__item">
              <Link to={data.path}>{data.label}</Link>
            </li>
          )
        })}
      </ul>
    );
  }
}

export default Header;

Media Folders Per Collection

When starting off with Netlify CMS I was using a singular assets directory for all collections and storing the images in my static directory like below. This started causing limitations and difficulties though when wanting to use gatsby-image, which when the content and image sit side by side in the same directory is beautifully easy.

media_folder: static/assets
public_folder: assets

If you are also dealing with Gatsby, or an alternative with the same issue, I recommend that you configure it to store the images for each collection relative to each collection. This will mean that images are stored alongside the content markdown files. To do this when you are creating your collection in config.yml, define media_folder and public_folder with these values. If you have any previously uploaded image you will need to move them into the new directory.

collections:
  - name: blog
    label: "Post"
    folder: "content/writing"
    media_folder: ''
    public_folder: ''
    create: true
    slug: "{{year}}-{{month}}-{{day}}-{{slug}}.md"
    fields:
      - { label: "Title", name: "title", widget: "string" }
      - { label: "Body", name: "body", widget: "markdown" }

This however does mean that if you have uploaded an image to another collection previously, these images aren't accessible globally, so if you wanted to use it in a different collection you would have to upload again. In the case of the benefits I got from configuring it this way for use with Gatsby though, this issue is insignificant in comparison.

Post Type Hidden Value

One thing that I found useful, but cost nothing really, was adding a hardcoded hidden value into the content files to mark out what collection they came from. I've ended up using these values in a couple of way such as filtering the nodes in my gatsby-config.js, so for a one liner in your config why not add it in from the start.

  - name: blog
    label: "Post"
    folder: "content/writing"
    media_folder: ''
    public_folder: ''
    create: true
    slug: "{{year}}-{{month}}-{{day}}-{{slug}}.md"
    fields:
      - { label: "post_type", name: "post_type", widget: "hidden", default: "post" }
      - { label: "Title", name: "title", widget: "string" }
      - { label: "Body", name: "body", widget: "markdown" }

Conclusion

These are my top five configuration tips starting off with Netlify CMS. I hope to come back and do a follow up post in the future if I have any updates, and have another one in the works where I dig into using the beta feature of Variable Types with Gatsby (not as easy as I first thought!).

One of the things I have loved about Netlify CMS, that I know I have already mentioned, is it's simplicity. This is probably one of the main reasons that this isn't an essay of a post. It really just gives you what you need for basic content administration in the quickest way possible.

Are there any options you think I have missed or improvements that I can make? Please let me know at Twitter

Hell-bent for Webperf

info@matthewshields.co.uk — Sat, 28 Mar 2020 00:00:00 GMT

Remote Development Team Assistance Using VS Code Live Share

info@matthewshields.co.uk — Sun, 22 Mar 2020 00:00:00 GMT

Requirements: Either a Github or a Microsoft account

My development team are very close knit and the majority of us work in very close proximity of each other, like most people right now though we are all working from home. For the most part it has actually been working well, we have access to our bitbucket server and staging environments via VPN and have been able to transition pretty seamlessly.

One thing that we have noticed though, is the inability to ask another member of the team for those quick 'can you take a look at this?' moments. This is something that we regularly do to help each other, it could be that you are wondering how to approach something or having difficulty debugging a particularly tricky issue. So how do we not lose the ability to do this in the best way possible, quickly and efficiently for both parties to minimise time taken and get the problem solved?

What was our criteria for a solution

We knew that one of our biggest criteria here was speed, the ability to have someone help you without requiring any more of their time than needed. Despite us all being helpful souls, we are of course all busy too. As a team we work on a mixture of static and CMS based work, with static pieces it can be quite quick to get up and running to take a look, but when it's a CMS issue this might require setting up on your local or even getting someone's specific database if its something they are actively working on. This is all time invested into setting up rather than helping though and still loses an aspect of looking at something collaboratively.

Having identified a few of the initial speed bumps, we set up some base criteria:

Speed – the ability to quickly invite someone to help you and for them to easily assist.
Run from their machine – the ability to look at it without needing to set up on your local machine.
Collaborative – rather then fixing and delivering back, it should be a discussion between multiple people (ideally more than just two if needed), something that screen sharing even when someone can request control, doesn't always provide.
Universal – any person in the team is able to help another. It's no good if we are dependent on one person to provide assistance to the whole team. Every person in the team has their own expertise and we all need to be able to share this knowledge.

The whole of our development team use the editor VS Code so it works seamlessly. We find it to be absolutely fantastic and if you haven't used it before I would genuinely recommend it. If you don't though you can also get this extension for Visual Studio or even utilise it in browser, which is mind-blowing if you ask me.

What Live Share will allow you to do is allow someone to start a collaborative session and allow them to open your workspace, but in their actual editor. What this means practically is that you aren't just observing or limited to a single view, you really do have access to their project in a natural easy to use way. You can both explore different files, run terminal sessions, commit to git with automatic co-author comments; and all whilst still being natural to them by having their own VS Code themes.

Criteria met: Speed, Run from their machine, Universal

Some of our favourite features

We are still quite new to this being part of our development process, so don't take this as an exhaustive list of every feature that it has, for that you may have to do some exploring yourself. For us though these are the features that we are most excited about for us working together.

User cursors

Unsurprisingly, if you are bringing multiple people into editing a file at the same time, you will need to be able to differentiate between them. Live Share manages to do this in a way that works really well, between the differing colours and use of labels. We are yet to have any issues with it, and although its not the most advanced feature without this being refined I think the rest may have fallen flat.

Criteria met: Speed

Focus participants

I have previously said that one of the great things about Live Share is the ability to move around the project independently (and it really is great for when it comes to exploring the issue) but what about when you want to explain the issue or (hopefully) explain the solution? When you want to do that, anybody partaking in the session will have the ability to use the 'Focus Participants' command. When this is used it will bring everyone to the part of the file that the person who runs it is looking at, even following them as they move around it or between files.

Criteria met: Collaborative

Follow to the side

You can also choose to follow a participant at any time rather than them making the call out themselves. Another option you get at this time is 'Follow to the side', if you use this feature then a split screen will be initiated where one side is for you whilst the other follows them. I believe you would call this the best of both worlds if you are figuring something out together.

Criteria met: Collaborative

Audio Chat / Text Chat

We already have plenty of options for talking to each other remotely; Slack, Microsoft Teams, Google Hangouts, Skype or an actual phone call, there are more options than you could ever need to do this. But why should you need to bring another application into the mix? You can actually open up an audio chat within Live Share to talk through the issue as you work. Is audio chat not your thing or you're in a public place where it's not appropriate? No worries, Live Share has your back and will also provide a chat window for you all to communicate. Whatever works for you!

Criteria met: Collaborative

You are probably going to be running sessions with a limited group of people for the most part, namely members of your team. You have the ability to add contacts to your Live Share list, after you have done that you will be able to initiate sessions with specific people instantly. What about if you want to share with someone that you haven't got in your contacts list? No worries they can join through a simple URL that will be automatically copied into your clipboard when you start a session.

A nice addition to this is also that if you have been in a session with someone before they will be added to your contacts list, making it super easy if you need to pick something back up with a specific person. Easy!

Criteria met: Speed

But what about viewing it in the browser?

One of our criteria was the ability to have it running completely from the session creators machine, without any setup required on the part of the participant's machines. Everything above is amazing, but what about actually being able to see the site in your browser? It would be hard to know sometimes if your fix has worked if you can't actually see it wouldn't it.

Initially we started by simultaneously sharing the persons screen on Microsoft Teams at the same time, however this felt like we weren't really achieving what we set out to do. It still required you to instruct the other person to refresh and users couldn't both control the browser independently, this was an issue.

We quickly shifted from using this approach and moved to using ngrok to create a localtunnel to our local environments. This meant that we could, within seconds, create a publicly accessible link that we could share with anybody in the team, allowing both independent control of the browsers and an efficient work flow to help each other. This solution was really simple for when we were working with static sites, however there was a bit more to figure out when it came to WordPress sites. We are really happy with the results of this though and think is going to help us with any remote debugging in the future.

I have written up guides to both solutions though for you to take a look at if you want, links are at the bottom of the article.

Criteria met: Speed, Run from their machine, Universal

Conclusion

Through a combination of using Live Share and ngrok we have been able to help each other, something that we are really passionate about as a team. At this point, we don't know how long we will be working from home, but this set up has taken one more challenge away from us. Even when we aren't though, I think our relationship with the idea of remote working will be fundamentally changed. If you have a team I would highly recommend that you think about what you can do to make it work as easily as possible for everyone.

I think you can tell from this post that I am blown away by the Live Share extension if you are looking for something to try I couldn't recommend this enough. If you have any ideas of improvements we can make please also reach out to me on Twitter, I would love to hear them.

Shoutout

I would be amiss to not give a big shoutout goes to Jonathan Carter, the creator of this extension, and so the person who is allowing my team to be able to work together so well at this difficult time. I first came across this extension when it was in beta and he was nice enough to share an invite with me, however I didn't get the full benefits at the time until we were working remotely. A genuine thanks to you!

Sharing Local WordPress Sites Remotely Using ngrok

info@matthewshields.co.uk — Sun, 22 Mar 2020 00:00:00 GMT

Disclaimer: you will need to have ngrok configured on your machine for this approach to work, the person viewing the site doesn't need to have it set up though.

There is a link to the ngrok documentation at the bottom of this post.

I wrote a post recently about how my team and I have been working to come up with a way to help each other debug remotely, the important part being without the need to set up the site on each others' computer to do so. One of the important parts of this was having the ability to visit their local environment in your own browser.

This is quite easy to do with static sites, I have wrote about this too which you can read here, but it is a little more difficult with WordPress sites. WordPress will use the site URL stored in the database for a variety of things such as redirecting to it when visiting the site.

Additionally to this, with the way that WordPress works you tend to have absolute URLs prolific through the source code. Having absolute URLs will cause an issue when someone else views the site through their browser, as they may not have http://yourlocalsite.localhost configured on their machine and their browser won't be able to resolve it.

These issues would cause problems if I tried to serve the site through ngrok without changing anything and you definitely don't want to be having to change the URLs in the database every time you want to share the site with someone.

The solution that my team and I use deals with this in two ways. Firstly, by dynamically setting the WP_SITEURL and WP_HOME constants in the wp-config.php. Secondly, making any instances of the local site URL into a relative link, ensuring that they will still resolve when viewed through a different URL. This will also only need to be done once per site, so not a bad investment of a couple of minutes.

Step One: Dynamically changing wp-config constants

I add this snippet into the wp-config.php, it detects if the URL that it's accessing contains ngrok in the host name before it does anything. If that is the case then it defines the WP_SITEURL and WP_HOME constants to the URL that is visiting it, taking care of the dynamic URL that ngrok creates. It then also sets a constant of LOCALTUNNEL_ACTIVE for use by the plugin that I will come to next.

if(strpos($_SERVER['HTTP_X_ORIGINAL_HOST'], 'ngrok') !== FALSE) {
	if(
		isset($_SERVER['HTTP_X_ORIGINAL_HOST']) && 
		$_SERVER['HTTP_X_ORIGINAL_HOST'] === "https"
	) {
		$server_proto = 'https://';
	} else {
		$server_proto = 'http://';
	}
	define('WP_SITEURL', $server_proto . $_SERVER['HTTP_HOST']);
	define('WP_HOME', $server_proto . $_SERVER['HTTP_HOST']);
	define('LOCALTUNNEL_ACTIVE', true);
}

I personally use a split wp-config system with our sites meaning that I can add this only into my local wp-config.php file. I highly recommend that you have a look at how you can do this for your WordPress setup.

Step Two: Making WordPress URLs relative

I created a plugin to make the URLs in the site relative. I ended up using the approach of creating a plugin which only ever does anything when it detects the LOCALTUNNEL_ACTIVE constant. The plugin ensures that the negative performance impact is limited to only local versions of the site when visited through an ngrok URL.

The plugin works by hooking to the start and end of the page creation and capturing it into an output buffer, it then uses the URL from the database for a str_replace, stripping it out before sending back out to the shutdown hook. This means that I can share either the HTTP or HTTPS versions of the ngrok URLs.

function change_urls($page_html) {
  if(defined('LOCALTUNNEL_ACTIVE') && LOCALTUNNEL_ACTIVE === true) {

    $wp_home_url = esc_url(home_url('/'));
    $rel_home_url = wp_make_link_relative($wp_home_url);

    $esc_home_url = str_replace('/', '\/', $wp_home_url);
    $rel_esc_home_url = str_replace('/', '\/', $rel_home_url);

    $rel_page_html = str_replace($wp_home_url, $rel_home_url, $page_html);
    $esc_page_html = str_replace($esc_home_url, $rel_esc_home_url, $rel_page_html);

    return $esc_page_html;
  }
}

function buffer_start_relative_url() { 
  if(defined('LOCALTUNNEL_ACTIVE') && LOCALTUNNEL_ACTIVE === true) {
    ob_start('change_urls'); 
  }
}
function buffer_end_relative_url() { 
  if(defined('LOCALTUNNEL_ACTIVE') && LOCALTUNNEL_ACTIVE === true) {
    @ob_end_flush(); 
  }
}

add_action('registered_taxonomy', 'buffer_start_relative_url');
add_action('shutdown', 'buffer_end_relative_url');

This process is an inefficiency which I would not want to be happening all the time for my site, especially in production. By limiting the plugin to only perform its functionality when it detects this constant, it provides the ability to control when it happens.

The reason I decided to package this up as a plugin is purely for ease of installing and updating if I need to in the future, however this could equally be added into my functions.php as an alternative.

Hat tip to https://sparanoid.com/work/relative-url/ for the lead of how to approach this, however I didn't want to have this applied all the time or risk it ending up on production.

Step Three: Creating the localtunnel

With the way that our team have our WordPress sites set up, I need to send through the host name of the site that we use locally as well as the port number and this will then direct the traffic to my local site. This works whether I had created it, or using something like MAMP Pro to set this up for me.

~/ngrok http -host-header=sitename.localhost 8888

Once ngrok is up and running I will be presented with the display that you can see below, giving me the URLs that I need to share. I will need to keep this terminal window open for the length of time I want the localtunnel open, so I need to not close it until I mean to, but also be nice to the ngrok service and close it when I'm not currently needing it, I can always open another one.

And thats it, I now have the ability to share WordPress sites dynamically through ngrok with anybody, without any setup required on their machines. I hope this approach might inspire you or help with any remote debugging or sharing needs that you have, especially at the moment when so many of us are working from home.

Sharing Local Static Sites Remotely Using ngrok

info@matthewshields.co.uk — Sun, 22 Mar 2020 00:00:00 GMT

Disclaimer: you will need to have ngrok configured on your machine for this approach to work, the person viewing the site doesn't need to have it set up though.

There is a link to the ngrok documentation at the bottom of this post.

Like most development teams around the world at the moment, my team are transitioning from an office environment to all working remotely. I wrote a post recently about the need we had to be able to debug remotely, an important part of which is being able to see the site in browser with absolute minimal setup.

I work on around a 50/50 split between static sites and CMS sites, most of which use WordPress. I have written about how you can share a WordPress site remotely, which requires a little bit more work, but for most static site setups using ngrok to open a tunnel is very straight forward.

Creating the tunnel

There are two different local static site setups that I have used:

Static site using grunt-browser-sync which creates a localhost server with a dynamic port number
Static site using a static hostname and port number

Whichever kind of site I am wanting to share though ngrok makes this incredibly easy to set up and use.

Static site using a localhost server and dynamic port number

When using a package like browser-sync (where it creates you a local URL such as http://localhost:3000), you can expose this URL publicly with the following command in your terminal. The only dynamic part of this would be the port number that you would like to expose.

~/ngrok http 3000

By default ngrok will assume the hostname is 'localhost', if this isn't the case then please use the next example.

Static site using a static hostname and port number

When your local site has a static host name and port number, you will need to pass this to the ngrok command in this format. A nice simple one-liner!

~/ngrok http -host-header=sitename.localhost 8888

Whichever option from above you use, you will be presented with this when the ngrok tunnel is successfully open, giving you the URLs that you can share. This terminal window will need to remain open for the length of time you want the tunnel to remain open, so don't close it until you mean to. Please bear in mind that this is probably a free service that you are using, remember to close it when not needing it. You can always open another one later.

You now have a publicly shareable tunnel through to your static local site, something that can be really helpful for remote debugging or checking in with the design team. I hope this helps and if you have any other local static site setups not covered by these two then let me know and I will update the post.

Netlify CMS

info@matthewshields.co.uk — Sun, 22 Mar 2020 00:00:00 GMT

VS Code Live Share

info@matthewshields.co.uk — Sun, 22 Mar 2020 00:00:00 GMT

digita11y - Accessibility Toolkit

info@matthewshields.co.uk — Wed, 18 Mar 2020 00:00:00 GMT

Elevator.js

info@matthewshields.co.uk — Wed, 18 Mar 2020 00:00:00 GMT

My First Site Using Gatsby.js

info@matthewshields.co.uk — Tue, 17 Mar 2020 00:00:00 GMT

Disclaimer: this isn't a guide to learning Gatsby, there are resources much better then I could provide for this, some of which I have linked to at the bottom of this post.

To give some context, I've used React on a few sites now, primarily ones which have been heavily API driven rather than traditional content based. I've always had some misgivings about the fact that there is no content delivered as part of the initial HTML document and purely rendered in browser.

Working at an SEO agency I have seen several client sites be severely negatively impacted by React / Angular sites implemented incorrectly, something that I have always wanted to avoid (for obvious reasons), but I then became aware of the great work that Gatsby and the like have been doing.

Since hearing a lot about them I've been wanting to dive into JAMstack technologies for a while now and finally blocked off a weekend to dedicate myself to it. I've been to talks, read blogs, talked about it with people and planned out in my head. All that was missing was me getting my hands dirty and getting started. Here are some of the observations that I had during this process, there is a mix of positive, negative and just some unanswered questions for the time being.

The positives

Let's start off with the positives, because there were some great things that I really enjoyed about this development experience that I really want to talk about.

Documentation as a priority

As more people are picking up a particular technology, documentation will be vital as their first point of contact for support. I have to commend the Gatsby team for the effort they have made into making their documentation top notch and accessible, even to someone new to it like myself. Between the documentation itself, showcase sites, tutorials, starter sites and the like there really are a wealth of resources to help you on your way.

The power of the 'gatsby-image' component

I genuinely love this component. With lazy loading, service worker caching, src-sets and blurred base64 images built in, what's not to love? Images can be detrimental to performance of sites and this definitely makes it a lot easier to lessen this impact. I want to do some further investigation into this and make sure that I'm not taking it as a given that it is all pros and no cons but so far it seems to be working great.

PageSpeed results

The foundations of how Gatsby works seem to be focused on optimisation in a way which is extremely compatible with the metrics that PageSpeed measures against. Without much intervention from myself, the performance of the site from a PageSpeed perspective was great. I need to take into consideration the size of the site that I am analysing, it is admittedly quite a basic site, but I'm in no doubt that the same could be achieved with a more complex site too.

Built in powerful functionality for great user experience

Service workers for offline support, content and asset caching, automatic prefetch functionality to name a few. All of these were just, there. There is always a balance between configuring things yourself and letting someone do the heavy lifting for you, but in this case I've got to say I'm alright with it. I definitely want to pick it apart a bit more incase I need to do more custom configuration in the future but the basic setup seems like I wouldn't need to do that in most cases (I could be wrong!).

Some issues that I ran into

As with picking up any new technology, especially when it has fundamental differences to something you have used before, you are going to hit some challenges as you learn. These aren't necessarily criticisms of the technology, but just things that I struggled with and have identified areas for me to keep learning further. I fully expect in time, if I was to write this post again in six months, I would be giving you a whole different list.

'gatsby-node' and 'gatsby-config' might take some getting used to

Theres nothing that different here in the configuration between this and plenty of other things that you may already be using, or have used, such as Grunt or Gulp. What I did find personally with Gatsby was that these files were a bit unintuitive getting started as a newbie. I'm sure over time that I will get much more to grips with these setups but I will definitely need a few more rounds before I feel really comfortable.

The number of images and their impact on build time

One thing that I found with Gatsby is that the number of images very quickly will impact the build time for your site. This makes sense when you look at how it works which was a big shift from what I am used to, but its definitely something to be aware of. I don't have that many images on my site yet but I very quickly found myself with a 15 minute build time on Netlify. The biggest tip I can give you on this one? Pre-optimise your images. I know this might seem like something that you want it to take care of, and it will, but with it being something that you need to repeat every time that you spin up locally or deploy you will get the rewards back in time.

For pre-optimising my images I just exported them at a reasonable size, ideally the maximum image size they would ever be displayed, and ran them through imageoptim. This then took my build process back down to three minutes, much better! I want to do more investigation with this one as I can see this creeping back up again as I add more images into my site, thanks to the photography section.

GraphQL queries, do the research

GraphQL has been a learning curve. Its not its actually that complex to write, in fact its actually shockingly simple to write queries to fetch your content (in my case querying content from markdown files). There are however several gotchas that I got caught with as I was working on the site. In hindsight I wish I had put more time into researching and learning the concepts of graphQL beforehand. It is extremely powerful but I would say it's very strict. A few of the things I came across were:

GraphQL queries may look like a string, but they're not and don't try to treat them as such
Only page based queries have access to variables, no component based queries

Images are expected to be siblings to the queried content

When querying images you will probably want to use the 'gatsby-image' component to render them, as previously discussed it's great, so why wouldn't you? Gatsby however will expect that images are siblings to the content that is being queried. This differs to NetlifyCMS where images are stored in a single assets directory, not an unreasonable thing with a content management system with the ability to upload images.

When I was doing childImageSharp queries though this would return null, removing your ability to use this component. You could query as a string and display as an tag, however the benefits would then be reliant on you to implement separately, luckily though someone has resolved this for you. Using the gatsby-remark-relative-images plugin this will allow you to have your images in a singular directory and still use your childImageSharp query. The page on NPM will show you how to configure the plugin, but it is incredibly easy. After that you can then query with relatively little difference to before as you can see below.

export const query = graphql`
  query {
    fileName: file(relativePath: { eq: "matthew-shields.jpg" }) {
      childImageSharp {
        fluid(maxWidth: 800) {
          ...GatsbyImageSharpFluid_withWebp
        }
      }
    }
  }
`

Conclusion

I have really enjoyed my first dive into this new approach to web development, I fought through the times where I knew I could have achieved certain bits in a fraction of the time in my traditional stack and to be honest with you, I'm proud of what I have put together.

This is only the first step, there's lots more for me to learn and am fairly certain that in a few months I will want to burn this site down and build it again from the ground up with what I have learnt, and that's OK. I will however be wanting to document this journey on here for anyone to see, and for me to reflect on as I go.

Useful Gatsby links

Launch of my new site

info@matthewshields.co.uk — Sun, 15 Mar 2020 00:00:00 GMT

I've built websites for so many different people at work over the last eight years, however it has probably been five years of me saying that I need to do the same for myself... I've finally done it! Not counting the multiple abandoned projects sat in Github...

In typical developer fashion I used it as an opportunity to learn a new technology and for me this was the combination of using Gatsby with React and Netlify CMS for content management. Up until this point with CMS work I have mostly used WordPress so this was quite a big shift for me, some parts were fantastic, others were challenging to say the least. I am going to follow up with a separate post where I address some of the challenges that I have hit along the way, some of which were due to me being new to the technology, others were with fundamental shifts in approach that were required.

Either way I have managed to finally carve out my own little corner of the web and have some goals that I want to achieve with it:

Develop further to make it more optimised – I am aware that as my first build of this type that I have more work to do. Performant websites are something I care about so I can't be a hypocrite.
Develop my writing skills – I'm not a natural writer, I envy the rare few who are but most people need to work hard and practice to get there. I am going to use my blog to practice this skill myself so any feedback is welcomed.
Display my personality – if you are reading this you are probably a developer too, but coding isn't the entirety of who we are. My other big passion at the moment is learning and improving my photography skills so I'm going to be showing them on here too.
Engage with the community more – my relationship with the development community has probably been a little one-sided up till now but I want to change this and contribute back.
Document my progression – I've never been one to keep a diary or anything like that, but I wish I had kept a record of my progression so far in my career to look back and remember how far I have come. So at least I can start now and look back in 10 and 20 years (hopefully).

I don't think these are lofty goals, and may even change over time, but I am looking forward to seeing how it goes! A pre-emptive thank you also goes out to my girlfriend, Phoebe, as I am fairly certain she will keep pushing me at times when I start to slack on this... She's kept her blog going for over 10 years now so she knows a thing or two about dedication.

CodeTour

info@matthewshields.co.uk — Sun, 15 Mar 2020 00:00:00 GMT

The CSS Podcast

info@matthewshields.co.uk — Sun, 15 Mar 2020 00:00:00 GMT

Ladybug Podcast

info@matthewshields.co.uk — Sun, 15 Mar 2020 00:00:00 GMT

Poker Probability Engine

info@matthewshields.co.uk — Sat, 14 Mar 2020 00:00:00 GMT

Matthew Shields | Leeds based Web Developer

Using Optional Chaining and Nullish Coalescing Operator in JavaScript

What is so good about Optional Chaining?

How could we stop these errors from happening?

Optional Chaining to the rescue!

Nullish Coalescing Operator as your backup

But what if I don't work with APIs or data?

Get element attribute

Get first element in array

Call function only if it exists

What can't you do with it?

Requirements and Browser Support

Optional Chaining

Nullish Coalescing Operator

Tip: Are you using Netlify Serverless Functions?

Wrapping it up on this one

How to ask for help debugging the right way

Respect for each other

How to provide context of the issue

An example of asking for help, the right way

Making time for understanding

Side note update

Using React Helmet to Manage the Document Head and SEO tags

The NFL to the rescue: react-helmet

Where do I use it?

Nested instances

Another Example: JSON Schema

SEO Requirements for the document head

Time to start using react-helmet

Netlify CMS Variable Types and Gatsby

My issue: The static nature of my Netlify CMS content

Introducing Netlify CMS Variable Types

How to get the variable data with GraphQL?

Using createSchemaCustomization API and createTypes to define field content type

Building your GraphQL query

It's all Markdown-hill from there

Flexible Content in React

FlexibleContent Component

Using the FlexibleContent Component

Gatsby and Variable Types - One Happy Family

Tae'lur Alexis 100 days of Vanilla JS

Setup

About Me

Configuration tips for Netlify CMS

Simple but configurable

Editorial Workflow

Editorial Workflow and Git

Main Navigation

Media Folders Per Collection

Post Type Hidden Value

Conclusion

Hell-bent for Webperf

Remote Development Team Assistance Using VS Code Live Share

What was our criteria for a solution

Introducing the VS Code extension 'Live Share'

Some of our favourite features

User cursors

Focus participants

Follow to the side

Audio Chat / Text Chat

Contacts / Link Share

But what about viewing it in the browser?

Conclusion

Shoutout

Related Links

Sharing Local WordPress Sites Remotely Using ngrok

How to share local WordPress sites through ngrok

Step One: Dynamically changing wp-config constants

Step Two: Making WordPress URLs relative

Step Three: Creating the localtunnel

Related Links

Sharing Local Static Sites Remotely Using ngrok

Creating the tunnel

Static site using a localhost server and dynamic port number

Static site using a static hostname and port number

Sharing the remotely accessible

Related Links

Netlify CMS

VS Code Live Share

digita11y - Accessibility Toolkit