Here is a real world example of when this might be useful, an image carousel where the slides have a fixed height and variable widths:

At different viewport widths the carousel is taller, so we can’t simply hardcode each slide’s width. Before today I would have told you that the only reliable way of scaling the slides was to pass their aspect ratios to JavaScript, calculate the width of each slide relative to its height, then resize them accordingly. And to do that for every slide, every time the viewport is resized. It would be much simpler if the slides could be scaled once by CSS, but to achieve that we need a way to give each slide a relative width.

The solution: a canvas shim

My solution is to use a transparent canvas element to force the aspect ratio. The key to this technique is the fact that if you define width and height attributes for a canvas, then it keeps the same aspect ratio when you change its height with CSS (the same is not true of the img element, which is is why I didn’t use a transparent PNG or GIF as a shim).

<div class="intrinsic-ratio">
  <canvas class="ratio-shim" width="200" height="100"></canvas>
  <img src="my-image.jpg">
</div>

.intrinsic-ratio {
  position: relative;
  display: table-cell;
  width: auto;
  height: 200px; /* height can be any value */
}
.ratio-shim {
  height: 100%;
}
/* The content could be anything. In this case an img */
.intrinsic-ratio img {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
}

So yeah, an extra HTML element is required for this to work, but that’s not so awful when you consider that the alternative is measuring and resizing the element with JavaScript.

You might also notice that the wrapping element has its display property set to table-cell. This makes it shrink-wrap to the width of its content. display: inline-block would work too, as would floating the element or giving it absolute positioning.

I don’t imagine that I am the first person to come up with this technique, but it’s not one I’ve seen in the wild so it might be worth keeping in the toolbelt until browsers have native support for aspect-ratio.

Demo

View a demo on CodePen

Notes

The CSS padding technique doesn’t work when an element’s width is unknown because percentage-based padding is relative to the width of the containing element, not its height. When you only know the height of the element, setting padding-left or padding-right as a percentage will produce inconsistent results.

Flywheel is a WordPress hosting provider so Local is aimed at WordPress developers, but can theoretically be used for any PHP application regardless of where it will be hosted.

I ignored Local for a long time because early versions ran inside a virtual machine. In my experience virtualisation is painfully slow, even on fast host systems, and by many accounts that was the case with Local too. In fact performance was bad enough that Flywheel decided to rebuild Local from scratch as a native application. They even dubbed the new version “Lightning” to emphasise the speed boost.

I am a long longtime MAMP Pro user, and despite having no major complaints about MAMP I was curious about Local’s new direction and recently took it for a spin.

Teething issues

Unfortunately, things got off to a rocky start. After launching Local and configuring my first site, my browser hit me with a 404. After some head scratching I deduced that there was a conflict between MAMP and Local. MAMP was listening on ports 80 and 443, which are the standard HTTP and HTTPS ports, and was blocking Local from doing its thing. After quitting MAMP and restarting my computer Local’s server ran smoothly. Little did I realise that my port-hijacking woes were far from over – more on that shortly – but for now let’s focus on the positive.

Once I got Local up and running, its features really impressed me.

Setup Wizard

Installing a new site with Local takes about 30 seconds. A setup wizard asks you a few basic questions about the site – what is it called, what username and password you want for your WordPress admin user – and then it installs a fresh copy of WordPress for you, pre-configured and ready to go. It really couldn’t be simpler.

One-click certificate trust

In this day and age every website should have an SSL certificate. When you’re developing locally this may not seem important, but having a certificate ensures that your WordPress database doesn’t get polluted with http:// prefixed URLs. Plus, eCommerce applications will complain loudly if you try to make a transaction using an unsecured connection.

With MAMP, the process of adding a self-signed SSL certificate goes like this:

1. Generate a certificate inside MAMP
2. Choose a location to save it on your hard drive
3. Navigate to that location, and drag the certificate into Apple’s Keychain Access app
4. Double click the certificate to edit its preference, and change the Trust setting to “always trust”
5. Type your macOS password to authorise the change

I’ve done it so many times that this process takes me about a minute, but it still irks me that I need to jump through these hoops.

When you create a site in Local it creates a certificate for you automatically. Then, you can trust the certificate without leaving the app (trusting a certificate stops your website browser from displaying a security warning).

My one niggle with this feature is that Local doesn’t configure WordPress to use HTTPS by default. You’ll need to change WordPress’ home and site URL to use the https:// prefix yourself.

Automatic database dumps

This is a big one. After working with MAMP for years I have resigned myself to the fact that to back up a site’s local database I need to manually export it to disk. Local has an elegant solution to this problem. Anytime a site is stopped within the Local application, a database dump is performed. No more manual MySQL dumps!

Mailhog

One of the drawbacks of developing locally is that without a mail server none of your site’s transactional email is delivered, which makes testing difficult. For instance you can’t verify that an eCommerce system is actually sending order notification emails.

Local comes bundled with Mailhog, a nifty application that runs a simple SMTP server that “hogs” any mail sent from your site so that you can view it later. As someone who’s gone without this feature for so long, it feels like magic.

Config and files stored together

Unlike MAMP, which stores each site’s configuration files who-knows-where, Local stores them right next to your application’s database and public files. It feels very tidy to have everything in one place.

Drag-and-drop import

To import a website into Local, you can simply drag a .zip file into the app. The only requirement is that the archive needs to contain a WordPress wp-content directory and an SQL database file.

If the domain of the site you’re importing doesn’t match the .local domain you chose in Local, you will be prompted to fix the issue, which will perform a find & replace in the site’s database. It gracefully handles serialized data too, which a naïve find & replace won’t.

Sequel Pro integration

Local uses Adminer to let you administer your site’s’ MySQL databases, but it will also detect if you have Sequel Pro installed and give you a button that opens a database in Sequel. It’s a nice touch that shows Local’s developers are in touch with their user’s workflow (or they just really like Sequel Pro).

Free as in beer

Did I mention that you get all of this for free?! There is a paid version of Local, but as far as I can tell its additional features only benefit Flywheel’s hosting customers.

Port-hijacking hijinx

Remember how I said that my port-hijacking woes weren’t over yet? I ran into more problems when I needed to fire up MAMP to work on one of my other projects. I knew that Local and MAMP didn’t play nice together, so I quit Local first, but MAMPs server still didn’t seem to be responding. For some reason Local wasn’t releasing ports 80 and 443 when I quit the application.

After extensive debugging I concluded that the problem is specific to macOS High Sierra, since it doesn’t affect my MacBook which runs Mojave. On High Sierra Local installs a launch daemon that starts NGINX when the OS boots up, and never stops it again. It is an obscure bug (feature?) that most people won’t notice, but it irritated me so much that I upgraded to Mojave!

No subdirectory or custom table prefix

Another shortcoming of Local is that it doesn’t officially support installing WordPress in a subdirectory, or choosing a custom database table prefix (which the standard WordPress installer does).

Ultimately not a big deal, but if you’re accustomed to changing the installation directory or table prefix then you might find Local restrictive in this respect.

No hot swapping or Apache

Unlike its virtualised predecessor, Local Lightning doesn’t offer an option to hot swap between different versions of PHP, or between Apache and NGINX. These features are on the roadmap, though.

Verdict

Overall I’m very impressed by Local. It is an elegant software suite that improves on MAMP in some important ways. Local is a little more prescriptive than I’m comfortable with, but I guess that’s the price of its simplified workflow.

“Lightning” has only been out of beta for a couple of weeks, so of course it’s not perfect, but the development team seem to be hard at work adding features and squashing bugs, and I am optimistic that it will continue to improve.

Access to https://my-server.com/font.woff from origin https://remote-server has been blocked by CORS policy: No ‘Access-Control-Allow-Origin’ header is present on the required resource.

The problem can be fixed by adding an Access-Control-Allow-Origin header to the font file, which allows access from the remote application.

Note: Instructions below this point are specific to Runcloud and won’t work for other NGINX configurations.

If you’re operating a Runcloud server then you need to edit NGINX configuration files to add that header. Runcloud already adds a location block for static files to your app’s main.conf:

location ~ .(ico|css|gif|jpe?g|png|gz|zip|flv|rar|wmv|avi|css|js|swf|png|htc|mpeg|mpg|txt|otf|ttf|eot|woff|woff2|svg)$ {
    expires     1M;
    include /etc/nginx-rc/conf.d/your-app-name.d/headers.conf;
    add_header  Cache-Control "public";
    include /etc/nginx-rc/extra.d/your-app-name.location.static.*.conf;
    try_files $uri @proxy;
}

Runcloud’s documentation explains that you should never edit that file directly, since your changes might be overwritten, but you can hook into the include near the end of the block to create a nested location for fonts.

Issue the following command to create a new NGINX configuration file, remembering to replace <your-app-name> with the name of your Runcloud web application:

touch /etc/nginx-rc/extra.d/<your-app-name>.location.static.cors.conf

Then open that file in a text editor such as nano:

nano /etc/nginx-rc/extra.d/<your-app-name>.location.static.cors.conf

Paste the following location block into the file you just created, again remembering to customise <your-app-name>:

location ~ .(ttf|eot|woff|woff2)$ {
    # Include default Runcloud headers for static files
    include /etc/nginx-rc/conf.d/<your-app-name>.d/headers.conf;
    add_header Cache-Control "public";

    # Allow fonts to be accessed from remote applications
    add_header Access-Control-Allow-Origin *;
}

This location block uses a regular expression, indicated by the ~ modifier, to target files with a font extension, and adds an Access-Control-Allow-Origin with a wildcard * value. The wildcard means that any domain can access the font. You could specify a domain instead.

You will notice that we have included Runcloud’s default headers too. NGINX’s add_header nukes any headers defined outside the current scope, so we need to re-add them.

After saving the file, reload NGINX’s configuration by issuing the following command:

systemctl reload nginx-rc

You should notice that an Access-Control-Allow-Origin header is added to fonts when they are served. You can use cURL to test this from the command line:

curl -I https://my-server.com/path/to/font.woff

1. It is time consuming
2. The files take up space on your local drive

I recently discovered a way to seamlessly handle missing images so that they never 404 or occupy space on your local machine. The solution is an htaccess rewrite rule that checks if an image exists locally, and if it doesn’t, attempts to load it from your production server.

Here is a sample htaccess directive for WordPress:

# Load media files from production server if they don't exist locally
<IfModule mod_rewrite.c>
  RewriteEngine on
  RewriteBase /
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{HTTP_HOST} ^localsite\.dev$
  RewriteRule ^wp-content/uploads/(.*)$ http://remotesite.com/wp-content/uploads/$1 [NC,L]
</IfModule>

Remember to change “remotesite.com” and “localsite.dev” in the example to match your own domain, and adjust your file paths as necessary. If you’re implementing this on a WordPress site make sure to place it before WordPress’ own htaccess directive.

Hat tip to @stevegrunwell for bringing this technique to my attention.

A long standing gripe is that classes are added to every paragraph and span when I paste text into the editor:

<p class="p1">This is <span class="s1">pasted</span> text</p>

This odd behaviour is consistent across many applications – InDesign, TextEdit, Mail – so I suspect it may be occurring at an OS level. In any case, I don’t want class attributes finding their way into markup unless I put them there!

A more significant problem is that TinyMCE doesn’t filter out HTML tags from pasted content. If you copy and paste text from a website you might unknowingly bring its markup along for the ride, and end up with something like this:

<div class="row">
  <div class="col-8">
    <table>
      <tr>
        <td><p>This is pasted text</p></td>
      </tr>
    </table>
  </div>
</div>

I’m sure you can imagine how disastrous that extra markup could be on your website’s front end.

Unfortunately TinyMCE doesn’t have a configuration option to specify which tags are permitted in pasted markup. The valid_elements option allows us to define which elements will remain in the edited text when TinyMCE saves, but that is an overzealous solution. On occasion you might need to add markup via TinyMCE, and valid_elements would strip it out again when you save your post. What is needed is a way to clean up text when it is pasted into TinyMCE, but still allow the user to type markup into the editor if they choose.

The solution comes in the form of the paste_preprocess option, which allows us to specify a callback that will be executed when content is inserted into the editor. Within that callback we can strip out any tags that we don’t want, and remove class, id and any other undesirable attributes from our content.

In WordPress you can hook into TinyMCE’s configuration using the tiny_mce_before_init filter. In your theme’s functions.php file:

add_filter('tiny_mce_before_init','configure_tinymce');

/**
 * Customize TinyMCE's configuration
 *
 * @param   array
 * @return  array
 */
function configure_tinymce($in) {
  $in['paste_preprocess'] = "function(plugin, args){
    // Strip all HTML tags except those we have whitelisted
    var whitelist = 'p,span,b,strong,i,em,h3,h4,h5,h6,ul,li,ol';
    var stripped = jQuery('<div>' + args.content + '</div>');
    var els = stripped.find('*').not(whitelist);
    for (var i = els.length - 1; i >= 0; i--) {
      var e = els[i];
      jQuery(e).replaceWith(e.innerHTML);
    }
    // Strip all class and id attributes
    stripped.find('*').removeAttr('id').removeAttr('class');
    // Return the clean HTML
    args.content = stripped.html();
  }";
  return $in;
}

We use jQuery to populate the DOM with the pasted content, then traverse the DOM and remove tags and classes we don’t want. Finally we extract the cleaned HTML markup and pass it back to the editor. This approach may seem convoluted, but it is far less error prone than using regular expressions to sanitize our content.

All you need to do is modify the whitelist variable, which contains a list of tags to allow past your filter.

One last thing: You might notice that our entire JavaScript function is contained in a string. This might seem odd, but is necessary since WordPress stores TinyMCE’s configuration options as an array of strings.

The particle system can be fine tuned using several configuration options, including a parallax effect which is controlled by the mouse on desktop computers or the gyroscope on smart devices. Particleground works in any browser that supports HTML5 canvas.

See a demo

Download

View on Github

Here’s the blurb:

As an industry we are obsessed with technical implementation. We write endlessly about front-end processes or the latest CSS and JavaScript techniques, but by focussing so much of our attention on technical concerns we have squeezed design issues out of the conversation.

The Web Designer’s Bookshelf is my attempt to rectify this imbalance. The site is an archive of articles that examine the history and craft of web and interface design, and related design disciplines, in a critical and thought provoking fashion.

Unlike technical articles, which date quickly, writing about design principles tends to have a longer shelf life. My hope is that the articles collected here will be of lasting interest to designers of all persuasions, and contribute to an ongoing conversation about the interactive design discipline.

Visit The Web Designer’s Bookshelf website, subscribe to the newsletter or follow @webdesbookshelf on Twitter.

Simply save each hooked function in a separate file, then use PHP includes to import them into functions.php:

require_once('includes/custom_excerpt_length.php');
require_once('includes/another_function.php');
require_once('includes/a_third_function.php');
// etc.

It doesn’t get much more minimal than that!

In this example our custom_excerpt_length.php file might look like this:

function custom_excerpt_length () {
  return 10;
}
add_filter('excerpt_length', 'custom_excerpt_length');

Keep the global space clean

One problem with the typical functions.php file – and, it could be argued, with WordPress generally – is that variables and functions are declared in the global scope. That means you risk naming conflicts with functions and variables declared elsewhere in your own code, in plugins, or in the WordPress core.

As an example, suppose you create a function named get_post_slug in functions.php. Now let’s imagine that in the future a function with the same name is introduced to the WordPress core. Your function declaration will now throw a fatal error:

Fatal error: Cannot redeclare get_post_slug()

To avoid naming collisions you could prefix your function names to make them unique – for example yourthemename_get_post_slug – but a more robust approach is to encapsulate your theme’s logic in a class.

A typical hooked function looks like this:

function custom_excerpt_length () {
  return 100;
}

add_filter('excerpt_length', 'custom_excerpt_length');

Here is that same functionality encapsulated in a class:

class YourThemeName {
  function __construct() {
    add_filter('excerpt_length', array($this, 'custom_excerpt_length'));
  }

  function custom_excerpt_length () {
    return 100;
  }
}

$yourthemename = new YourThemeName();

Because the custom_excerpt_length function is a class method it no longer has global scope, and the $yourthemename variable ensures that our theme’s logic has a single point of access. (Note: You should change YourThemeName and $yourthemename to something unique to your theme.)

You might have noticed that the second parameter passed to add_filter is an array, with $this as the first value. This tells WordPress to use a class method as a callback. You can read more about the different types of callbacks in the add_filter documentation.

Theme setup

Most themes have some setup code that needs to run straight away. Let’s add an init method to our class to handle this job:

class YourThemeName {
  function __construct() {
    add_action('after_setup_theme', array($this, 'init'));
    // Register action/filter callbacks here...
  }

  function init() {
    // All theme initialization code goes here...
    register_nav_menus(
      array(
        'header-menu' => __('Header Menu', 'yourthemename')
      )
    );
  }

  // Action/filter callbacks go here...
}

$yourthemename = new YourThemeName();

Any functionality you want hooked to the after_setup_theme action can go in the init method. In the example above we registered a navigation menu.

Utility methods

In addition to WordPress action/filter hooks your theme class can also provide utility methods, which can be accessed from templates.

Here is a simple utility method to get the ID of a category by supplying its name:

function get_category_id ($cat_name) {
  $term = get_term_by('name', $cat_name, 'category');
  return $term->term_id;
}

If you include that method in your theme’s class you can now access it from a template like so:

$yourthemename->get_category_id('category-name');

Group your functions by type

Rather than arranging callback function in a haphazard fashion, grouping them by type makes them easier to find.

As we saw earlier all of your theme’s filter/action callbacks are registered in the class constructor, and all setup logic is placed within the init method. I also like to group all my action callback functions together, my filter callback functions together and my utility methods together.

class YourThemeName {
  function __construct() {
    add_action('after_setup_theme', array($this, 'init'));
    // Register action/filter callbacks here...
  }

  function init() {
    // Theme setup code goes here...
  }

  // Action callbacks go here...

  // Filter callbacks go here...

  // Utility methods go here...
}

Comment your code

It might go without saying, but well written comments make your code easier to read and comprehend. Well structured comments can go a long way toward organizing your functions.php file.

/**
 * Get the category id from a category name
 *
 * @param string $cat_name The category name
 * @return int The category ID
 */
function get_category_id ($cat_name) {
  $term = get_term_by('name', $cat_name, 'category');
  return $term->term_id;
}

Use a plugin for site-specific functionality

While it may be tempting to dump all your site’s custom functions into your functions.php file, it is good practice to encapsulate site-specific logic in a separate functionality plugin. In addition to long term maintenance benefits, this separation of concerns streamlines your functions.php file by offloading some of its functionality to a plugin.

There have been many good articles written about what belongs in a functions.php file and what belongs in a functionality plugin, but I think Curtis McHale sums it up nicely:

The only deciding factor in where you put your code is the life of the functionality. Will you still need to have that portfolio custom post type the next time you redesign your site? If the answer is yes then you should be building a plugin with the code. If the answer is no, then put the code in you theme functions.php.

Example functions.php file

If you employ the strategies I have outlined in this post I hope you will find that your functions.php file is better organized and easier to manage. Here is an example of how the final file might look:

/**
 * YourThemeName
 */
class YourThemeName {
  /**
   * Constructor
   */
  function __construct() {
    // Register action/filter callbacks
    add_action('after_setup_theme', array($this, 'init'));
    add_filter('excerpt_length', array($this, 'custom_excerpt_length'));
  }

  /**
   * Theme setup
   */
  function init() {
    // Register navigation menus
    register_nav_menus(
      array(
        'header-menu' => __('Header Menu', 'yourthemename')
      )
    );
  }

  /**
   * Filter callbacks
   * ----------------
   */

  /**
   * Customize post excerpt length
   *
   * @return int The new excerpt length in words
   */
  function custom_excerpt_length () {
    return 100;
  }

  /**
   * Utility methods
   * ---------------
   */

  /**
   * Get the category id from a category name
   *
   * @param string $cat_name The category name
   * @return int The category ID
   */
  function get_category_id ($cat_name) {
    $term = get_term_by('name', $cat_name, 'category');
    return $term->term_id;
  }
}

// Instantiate theme
$yourthemename = new YourThemeName();

The technique uses CSS3 transforms, so it works in all modern browsers, including IE9 and above.

<div class="thumbnail">
  <img src="landscape-img.jpg" alt="Image" />
</div>
<div class="thumbnail">
  <img src="portrait-img.jpg" class="portrait" alt="Image" />
</div>

.thumbnail {
  position: relative;
  width: 200px;
  height: 200px;
  overflow: hidden;
}
.thumbnail img {
  position: absolute;
  left: 50%;
  top: 50%;
  height: 100%;
  width: auto;
  -webkit-transform: translate(-50%,-50%);
      -ms-transform: translate(-50%,-50%);
          transform: translate(-50%,-50%);
}
.thumbnail img.portrait {
  width: 100%;
  height: auto;
}

The technique works by positioning the image so that its top left corner is in the centre of its container. Then, a 2D translation moves it up and left by half its own width.

The key here is that the percentage values passed to the translate function are relative to the element, not its container, as would be the case if we were to manipulate the element’s top and left properties instead.

View a demo

Note that the portrait format image has the class portrait, so that we can correctly scale it to fill its container.

So there you go. A really simple CSS technique for centering and cropping thumbnails.