whateverthing.com

Thumbnails in Sculpin with Icelus

I've created a new Sculpin extension called "Icelus". You can use it to automatically generate thumbnails of images on your Sculpin-based website or blog. I chose the oddball name because Icelus is a genus of fish otherwise known as “Scaled Sculpin”, and thumbnails are scaled images (it's imaginative, dammit!).

For those who haven't heard of it, Sculpin is a static site generator like Jekyll or Octopress (or many others). Instead of acting as a dynamic application on a web server, it takes your blog posts or website pages and outputs them as a set of simple HTML files that can be hosted on any web server.

This results in easier maintenance and greater security for your blog. You don't have to worry about bugs in the code allowing intruders to take control of your server, so you don't have to constantly update a complicated blogging platform. Having just the raw HTML and not having to worry about a server-side application also gives you the freedom to host your site on a simple storage service like Amazon S3.

Having graphical content alongside blog posts has been shown to increase engagement, and we all know that working with images can be a bit time-consuming. Using a static site generator tends to make imagery more challenging, because of the lack of dynamic functionality you find in Wordpress and other platforms.

In this first version, Icelus provides a {% thumbnail() %} function for Twig templates. It allows you to specify any image in your “source/“ folder as an image to be scaled to the height and width you specify.

Combined with Twig's built-in macro system, you can wrap the thumbnail function in helpers that automatically inject the proper HTML for your thumbnails. An example of this is shown in the Icelus documentation:


thumbnail(image, width, height, crop)

  • image (string): The relative path to the image in the source/ folder.
  • width (int): Maximum width, in pixels
  • height (int): Maximum height, in pixels
  • crop (bool): False will fit the whole image inside the provided dimensions. True will crop the image from the center. Default: FALSE

Inline Example:

<a href="image.jpg"><img src="{% thumbnail('image.jpg', 100, 100) %}"></a>

Macro Example:

index.html:

{% import '_macros.html.twig' as m %}

<h1>Gone Fishin'!</h1>
{{ m.small_thumbnail('image.jpg', 'A picture from my fishing trip') }}


_macros.html.twig: 

{% macro small_thumbnail(image, caption) %}
  <a href="{{ image }}">
    <img src="{% thumbnail(image, 100, 100) %}">
    <br>
    <em>{{ caption }}</em>
  </a>
{% endmacro %}

Installing it is a matter of adding Icelus to your sculpin.json or composer.json file and then running the appropriate update command (e.g., sculpin update).

{
  "requires": {
    "beryllium/icelus": "~1.0.0"
  }
}

Icelus uses the Imanee image manipulation library to make Imagick operations tolerable. In the future, this could give Icelus the ability to do even more advanced image manipulations, such as watermarks or animations.

I would like to thank Beau Simensen (the creator of Sculpin) and Erika Heidi (the creator of Imanee) for their contributions to the PHP world. Keep up the good work! :-)

Published: March 7, 2015

Categories: coding, news

Tags: dev, development, coding, twig, sculpin, imanee