OVER ENGINEERING

over

The days of pure HTML, CSS and Javascript are over. Now we must learn CSS pre-processors and frameworks, multiple Javascript libraries (usually based on jQuery) HTML templating engines based in Javascript, task runners such as grunt and gulp, etc. With all of these tools available, and becoming an ‘industry standard’, it’s easy to misuse them and make a real mess of your website coding.

The reality is, you don’t need any add-on technologies. You can always create websites with highly organised, easily maintainable code, even when using the base technologies.

Modern web development often involves over-engineering. By this, I mean that too much time is spent on setting things up, writing and configuring tools and finding ‘smart’ ways of doing things instead of just doing what needs to be done in a logical manner.

CSS Preprocessors

Nesting

We all know the rule that selectors shouldn’t be nested more than 4 levels deep. However, I disagree with this, as I find that nesting selectors at all will make the code less readable. It’s easy to scan code in a vertical manner, but when my eyes need to also scan horizontally, it makes scanning much less efficient.

If I am looking through a style sheet and I find a class nested a few levels deep, I need to know the parent selectors to understand how the class is being applied. I need to scroll up to see the parent selector, then scroll up again to see its parent selector, then again. It’s not immediately obvious or straight-forward how it will be applied, I need to scan entire blocks of code to understand one line. It’s not a problem if the blocks are small, but there are usually quite a few child selectors under the parent block.

What I often see is a top-level class being used like a namespace. While it may seem neat to organise code this way, it takes more time and effort to understand it. It doesn’t add anything to the code organisation that you couldn’t do with a few line-breaks or comments. The only benefit is reduction of selector repetition. If organising CSS like programming code was that important, we would have adopted JSS instead of CSS.

I prefer to only use nesting for states and, sometimes, pseudo elements.

Media Queries

Another issue I sometimes come across is the use of multiple repeated media queries. Should each selector have its own media query? What about when they’re nested? It can become a bit messy and hard to see the big picture if so much functionality is separated into multiple super small media queries.

I prefer to use a set of media queries per ‘module’ or ‘feature’, so I don’t have a million media queries and yet I also don’t have one big monolithic set of media queries at the end of the file.

Useless complexity

One of the worst examples of investing time into making something that is often unnecessary, useless or even detrimental, would be the idea of wrapping media queries in pre-processor functions or mixins. I can understand the desire to use this when you have a lot of very complex media queries, used often. However, in most cases it’s just not necessary. You will see a line of code like this:

1
@include respond-to($medium) { }

What exactly does this do? It’s media query related, but you will need to go looking for the definition of $medium to know if it is just a pixel value, a query or a key relating to a keymap. Either way, you need to find the query text, the associated pixel values, how to use this function and what options are already available.

You will need to read and understand the definition of the function to see how it implements these variables. Does it use min-width or max-width as a default? Does it have default functionality?

What benefits does this function hold over a set of variables? You don’t need to type the word ‘@media’ anymore, instead you need to write ‘respond-to’. This is replacing a universally understood piece of fundamental CSS with a lesser-known custom implementation.

It’s always interesting to see what you can do with the tools available and how far you can go. However, we are replacing a straight forward set of readable statements with a slightly more cryptic line of code that needs to be investigated and understood by a programmer.

The benefit of this technique relies largely on how complex your media queries are, and how often your media queries are used. For sites that use simple media queries, storing the pixel value in a variable will be just as effective. For slightly more complex queries, you can store the entire query in a variable.

The creator of this technique warns his readers about finding a balance and picking the right tool for the job. I’ve seen this technique used in a way that is detrimental to the project many times.

Before using this technique, you need to consider if it’s the right thing to use for your project. Consider your development environment, project size, tooling and style of coding. Don’t just use this because it’s ‘good / standard practice’. Use it only if it suits your project.

Javascript

Libraries

When you want to read a book, you go to the library and borrow one. However, common practice with Javascript is to borrow the whole library just to read one book. Often, libraries like Bootstrap are included and used just for one feature. One feature that you could write in three lines of code. It’s important to justify the inclusion of an entire library before you do so.

Insane code

A previous company that I used to work for, had outsourced a project to an overseas company. One feature of the website was a little call to action button that would stick to the top right of the screen when the user scrolled past a certain point.

The developers had implemented this by using a collision detection system about a page long. It detected when any part of the element collided with the banner above it, so they knew when to remove the fixed position if the user was scrolling upwards. It was probably ripped from some game engine. I’m surprised they didn’t go one further and program some sort of self-learning AI to achieve the same task.

How many lines of code would it take you to implement that functionality?

Lack of programming knowledge

1
2
3
4
5
6
If (I == true)
 {
     I = false
 } else if (I == false) {
     I = true
 }

Actual code. From a teacher in a web development course. This was back in 2008. It’s memorable, but not in a good way.

This is not as common nowadays as most people know about the ‘not’ operator, but I have seen people implement code to replicate the functionality of the ‘modulus’ operator.

It’s important to know the features of the languages you use.

Conclusion

There are many motivations to complicate your code. To improve maintainability, improve functionality, boredom, being a smartypants, to annoy people for fun etc. However, keep in mind that in a year’s time, you may be the one working with your own code, cursing the developer who made this mess, only to find out that it was you who screwed you over. Yes, I’ve been in that situation, which is how I know. It’s also why I do things simpler and, for the lack of a better term, slightly more old-school than most people when possible.

Create Higher Order Components in React

Create Higher Order Components in React

Higher Order Components (HOCs) are the coined term for a custom Component that accepts dynamically provided children. For example, let’s make <LazyLoad /> Component that takes child image tags as children, waits until the <LazyLoad /> Component is scrolled into view, and then loads the images they point to in the background (before rendering them to the DOM).

An HOC accepts children via props:

DOM.render(
    <LazyLoad>
        <img src="../media/1.gif"/>
        <img src="../media/2.gif"/>
        <img src="../media/3/gif" />
    </LazyLoad>,
    document.body)

Creating an HOC means handling this.props.children in the Component’s code:

class LazyLoad extends Component {
    constructor(p){
        super(p)
        this.state = { loaded:0 }
        this._scroll = this._scroll.bind(this)
    }
    _scroll(){
        let el = DOM.findDOMNode(this)
        let {top} = el.getBoundingClientRect()
        let viewportHeight = Math.max(document.documentElement.clientHeight, window.innerHeight || 0)
        if(top < (viewportHeight + this.props.top)) {
            window.removeEventListener('scroll', this._scroll)
            this.setState({loaded:1})
        }
    }
    componentDidMount(){
        window.addEventListener('scroll', this._trackYPosition)
        this._scroll()
    }
    componentWillUnmount(){
        window.removeEventListener('scroll', this._trackYPosition)
    }
    render(){
        let {children} = this.props,
            {loaded} = this.state
        return <div>
            {loaded && children}
        </div>
    }
}

LazyLoad.defaultProps = {
    top: 100
}

Noting a few things about this code:

  1. We set up initial state (this.state = {loaded: 0}) in the constructor(). This will be set to 1 when the parent container is scrolled into view.
  2. The render() returns the props.children as child elements when this occurs. Extract the src by using ES6 destructuring, where {props:{src}} creates a variable src with the appropriate value.
  3. We used a single componentDidMount() lifecycle method. This is used because on mount, we’d like the component to check if the HOC is visible.
  4. The largest function of our component, _scroll(), grabs the HOC Component’s DOM element with DOM.findDOMNode() and then gets the elements position. This position is compared to the height of the browser window, and if it is less than 100px from the bottom, then the scroll listener is removed and loaded is set to 1.

This technique is called HOC (Higher Order Component) because we pass in elements as this.props.children when we nest those elements inside the container component:

<HOC>
    <div>some</div>
    <span>children</span>
    <Props/>
</HOC>

All of these nested elements (which can be custom components) are nested under <HOC/>, thus HOC’s code will be able to access them as this.props.children.

Build a SEO-friendly React blog with an API-based CMS

Build a SEO-friendly React blog with an API-based CMS

Have you ever wanted to build a server-rendered, SEO-friendly website using React and Node.js? The typical solutions for achieving this are either using a pre-rendering service like Prerender.io, or implementing server-side rendering of React components.

A relatively new alternative is Next.js, a framework for building universal React webapps. Next.js provides out-of-the-box tools for server-side rendering including setting HTML tags for SEO and fetching data before rendering components. Read more about the philosophy behind Next.js here.

In this Blog, I’m going to show you how to build a CMS-powered blog using React, Next.js, and ButterCMS.

ButterCMS is an API-based CMS and content API. You can think of Butter as similar to WordPress except that you build your website in your language of choice and then plug-in the dynamic content using an API. You can try ButterCMS for yourself by signing in with Github.

Getting Started

Create a new directory for your app and add a package.json file:

{
  "name": "react-blog"
}

Install Next.js and React. As of the time of this writing, we’ll want to install the Next.js so we can setup dynamic routes later:

npm install next@beta react react-dom --save

Then add a script to your package.json:

{
  "scripts": {
    "start": "next"
  }
}

Next.js treats every js file in the ./pages directory as a page. Let’s setup a basic homepage by creating a ./pages/index.js inside your project:

export default () => (
  <div>My blog homepage</div>
)

And then just run npm run start and go to http://localhost:3000.

Finally, create a ./pages/post.js and make sure it loads at http://localhost:3000/post:

export default () => (
  <div>A blog post</div>
)

Fetching blog posts

Next we’ll integrate ButterCMS so we can fetch and render blog posts dynamically.

First install the ButterCMS Node.js API client and restart your server:

npm install buttercms --save

We’ll update index.js to be a React component that fetches and displays posts using the ButterCMS SDK:

import React from 'react'
import Link from 'next/link'
import Butter from 'buttercms'

const butter = Butter('de55d3f93789d4c5c26fb07445b680e8bca843bd')

export default class extends React.Component {
  static async getInitialProps({ query }) {
    let page = query.page || 1;

    const resp = await butter.post.list({page: page, page_size: 10})    
    return resp.data;
  }
  render() {
    const { next_page, previous_page } = this.props.meta;

    return (
      <div>
        {this.props.data.map((post) => {
          return (
            <div>
              <a href={`/post/${post.slug}`}>{post.title}</a>
            </div>
          )
        })}

        <br />

        <div>
          {previous_page && <Link href={`/?page=${previous_page}`}><a>Prev</a></Link>}

          {next_page && <Link href={`/?page=${next_page}`}><a>Next</a></Link>}
        </div>
      </div>
    )
  }
}

With Next.js getInitialProps will execute on the server on initial page loads, and then on the client when navigating to a different routes using the built-in <Link> component. getInitialProps also receives a context object with various properties – we access the query property for handling pagination. We are fetching posts from a ButterCMS test account – sign in with Github to setup your own posts.

In our render() method we use some clever syntax to only display pagination links only when they’re applicable. Our post links will take us to a 404 – we’ll get these working next.

Displaying posts

To get our post links working we need to setup dynamic routing for our blog posts. Create a custom server ./server.js that routes all /post/:slug URLs to our post component:

const { createServer } = require('http')
const { parse } = require('url')
const next = require('next')

const dev = process.env.NODE_ENV !== 'production'
const app = next({ dev })
const handle = app.getRequestHandler()

app.prepare().then(() => {
  createServer((req, res) => {
    // Be sure to pass `true` as the second argument to `url.parse`.
    // This tells it to parse the query portion of the URL.
    const parsedUrl = parse(req.url, true)
    const { pathname, query } = parsedUrl

    if (pathname.includes('/post/')) {
      const splitPath = pathname.split("/");

      // Add post slug to query object
      query.slug = splitPath[2];

      app.render(req, res, '/post', query)
    } else {
      handle(req, res, parsedUrl)
    }
  })
  .listen(3000, (err) => {
    if (err) throw err
    console.log('> Ready on http://localhost:3000')
  })
})

We’ll also update our post component to fetch blog posts via slug and render the title and body:

import React from 'react'
import Butter from 'buttercms'

const butter = Butter('de55d3f93789d4c5c26fb07445b680e8bca843bd')

export default class extends React.Component {
  static async getInitialProps({ query }) {
    const resp = await butter.post.retrieve(query.slug);  
    return resp.data;
  }
  render() {
    const post = this.props.data;

    return (
      <div>
        <h1>{post.title}</h1>
        <div dangerouslySetInnerHTML={{__html: post.body}} />
      </div>
    )
  }
}

Finally, update our package.json start script to use our customer server and restart:

"scripts": {
  "start": "node server.js"
}

SEO

Next.js provides a <Head> component for setting HTML titles and meta tags. Add import Head from 'next/head' to the top of ./pages/post.js and use the component in the render() method:

render() {
  const post = this.props.data;

  return (
    <div>
      <Head>
        <title>{post.seo_title}</title>
        <meta name="description" content={post.meta_description} />
        <meta name="og:image" content={post.featured_image} />
      </Head>

      <h1>{post.title}</h1>
      <div dangerouslySetInnerHTML={{__html: post.body}} />
    </div>
  )
}

Restart the server and inspect the HTML source of a post to verify that tags are getting set correctly.

Wrap Up

Next.js is a powerful framework that makes it easy to build universal React apps. With ButterCMS you can quickly build CMS-powered blogs and websites with React.

Be sure to check out ButterCMS, a hosted API-based CMS and content APIand blog engine that lets you build CMS-powered apps using any programming language including Ruby, Rails, Node.js.NET, Python, Phoenix, Django, React, Angular, Go, PHP, Laravel, Elixir, and Meteor.

Code Source: available on Github.